9204 - StarTeam URLs: Creating and Using Persistent Links to StarTeam Artifacts

Jim WogulisPrincipal Architect, Borland Software Corporation

Introduction

Same goals as those of URLs (RFC 1738) Uniform Resource Locator

Opens the door for interoperability Use it to embed hyperlinks to StarTeam resources within

documents, web pages, etc.

Existing Approaches

stcmd command line Only supports projects, views and folders

SDK classes: StarTeamURL, StarTeamFinder Similar to stcmd

Problems Can only reference File items (not CRs, Tasks, Topics etc) Limited specification of views Can’t specify view configurations in the URL Only name-based Don’t conform to IETF URL specifications

Support in CPC

New in StarTeam 2005 R2 StarTeam Cross-Platform Client can create and resolve URL

references URL Creation:

Drag an item or multiple items from the client on to an appropriate drop target such as Word, Excel, Outlook

Menu item: “Copy URL to Clipboard” Clipboard contains several data flavors: plain text URL and HTML link

fragment. Can control the HTML link text through “Personal Options”

URL resolution: Project->Open StarTeam URL… menu item Command line option –openurl CPC is registered as protocol handler for starteam: (clicking a link in

a browser, Word etc will launch StarTeam)

General format

URLs using IP-based host addressing have a common format: <scheme>://<user>:<password>@<host>:<port>/<url-path>

Can specify user name and optional password starteam://tedison:password@host:49201/ starteam://tedison@host:49201/

<url-path> is scheme specific and describes how the specified resource can be accessed

Sample StarTeam URLs

To a StarTeam server starteam://stdemo.borland.com:49201/

To a Project starteam://host/StarDraw

To a View starteam://host/StarDraw/Main

To a Folder starteam://host/StarDraw/Main/src/

To a File starteam://host/StarDraw/Main/src/Main.java

Project URL

<url-path> is hierarchical First segment of <url-path> identifies resources with

“server” scope. StarTeam project has server scope

starteam://host/ProjectName

Other resources with server scope Users, groups Types (File Type, Change Request Type, etc.)

I18N Issues

URLs must only contain a subset of ASCII characters There are no restrictions on StarTeam project names What to do with Unicode characters, spaces etc? Encode names as follows:

Convert Unicode string name to UTF-8 encoding Leave resulting legal ASCII chars as-is Re-write non-ASCII chars with hex encoding

Example Name: “Pepsi©” (copyright char © is Unicode U+00A9) UTF-8 encoding (hex): [50, 65, 70, 73, 69, C2, A9] Hex encoded: “Pepsi%c2%a9”

ID-based references

All StarTeam resources have both a name and ID ID is the “true” resource identifier, name is a property Either one may be desirable depending on use-case Name-based more “readable” than ID-based “Check out the file named build.xml”

Used by build script, doesn’t care if some user deleted and re-added the file.

“Bug was introduced in revision 4 of file id=321” Immune to changes in the file name, identifies the exact file

object.

Name and ID-based syntax

All resources that have both name and ID use a common syntax

Uses URL segment parameters (RFC 2396) Name-based is the default

/Project /Project;scheme=name

ID-based: /42;scheme=id

View URL

StarTeam Views are organized in a hierarchy The View hierarchy does not reflect containment View names do not have to be unique in the hierarchy View reference is contained in a single URL segment:

/project/Main specifies the root view “Main” of the project /project/Main!Foo specifies the view “Foo” which was

derived from the “Main” view.

The view hierarchy is delimited by the ‘!’ character Same rules for I18N and ID-based URLs applies A view name that includes ‘!’ must hex encode as “%21”

View Configuration

Prior example was reference to the view in its “current” or “tip” state.

It is possible to reference a view in a particular configuration

View configurations can be time-based, label-based or promotion state based. /project/View;cfgl=labelName /project/View;cfglid=14 /project/View;cfgd=1999-06-17T16:43:07.982Z /project/View;cfgp=promotionState /project/View;cfgpid=7

Folder URL

Folder hierarchy is the same as containment hierarchy /project/view/RootFolder /project/view/RootFolder/subfolder

I18N rules apply Folder references can be name or ID based.

File URL

Files live within the folder hierarchy /project/view/folder/index.html

I18N rules apply File URLs can be name or ID-based How to distinguish files from subfolders:

/project/view/folder/foo/ (folder named foo) /project/view/folder/foo (file named foo)

non-File Item URLs

In StarTeam, multiple different item types can exist in the same folder: Files, CRs, Topics etc.

Q: How can the URL distinguish between a file or CR reference?

A: Use name-spaces: …/folder/index.html;ns=File …/folder/1234;ns=ChangeRequest …/folder/34;ns=ChangeRequest;scheme=id

General Format

Each URL segment can optionally specify a namespace and indicate whether or not the reference is name or ID-based: ../<identifier>[;ns=<namespace>][;scheme=(id|name)]

The <identifier> is based on the scheme: either an ID or the “primary descriptor” for the object

The <namespace> is the type-name of the item. This corresponds to the SDK’s Type.getName() method

Every container has a default namespace if none specified: for Folder it is “File” for servers it is “Project”

If not specified, the scheme is assumed to be name.

Scope Parameter

Sometimes it is useful to reference and item without respect to which folder it is in.

For example, CRs could get moved to different folders for organization but we would still like a URL to reference the CR even if it moves.

Scope parameter: /project/view/4567;ns=ChangeRequest;scope=full

URLs to Other StarTeam Resources

Our spec includes references to other StarTeam artifacts: Users, groups Labels, promotion states Type objects (Server.getTypes()) Type properties (Type.getProperties()) Attachments Item property values Item revisions

CPC currently only supports server, project, view, folder, file, CR, task, topic, requirement

MPX+URL+RSS Demo

http://startteam-demo.blogspot.com