9204 - starteam urls: creating and using persistent links to starteam artifacts jim wogulis ...
TRANSCRIPT
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