1. 9204 - StarTeam URLs: Creating and Using Persistent Links to StarTeam Artifacts  Jim Wogulis  Principal Architect, Borland Software Corporation

2. 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.

3. 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

4. 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)

5. General format  URLs using IP-based host addressing have a common format:  :// : @ : /  Can specify user name and optional password  starteam://tedison:password@host:49201/  starteam://tedison@host:49201/  is scheme specific and describes how the specified resource can be accessed

6. 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

7. Project URL  is hierarchical  First segment of 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.)

8. 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”

9. 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.

10. 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

11. 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”

12. 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

13. 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.

14. 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)

15. 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

16. General Format  Each URL segment can optionally specify a namespace and indicate whether or not the reference is name or ID- based: ../ [;ns= ][;scheme=(id|name)]  The is based on the scheme: either an ID or the “primary descriptor” for the object  The 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.

17. 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

18. 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

19. MPX+URL+RSS Demo  http://startteam-demo.blogspot.com http://startteam-demo.blogspot.com