Maximizing Developer Productivity with JBuilder and StarTeam

1. Maximizing Developer Productivity with JBuilder and StarTeam Preconference Tutorial

2. Agenda • Introduction • Customizing StarTeam Forms • StarTeam SDK Overview • Using the StarTeam SDK • StarTeam Dynamic Toolbar • Integrations

3. Introduction

4. The Need for Control Didn’t we fix this already? Did we update the model? Do we have that build? How much is left to do? What was fixed in this build? Who approved this change? How do we know when we are finished? Why are they working on that? Didn’t we test for this? Who made this change? But it works on my machine! Is this code documented? Why is it taking so long?

5. ROI of Software Process Improvement Category Median Total yearly cost of Software Process Improvement (SPI) activities To Do It Yourself $245,000 Years engaged in SPI 3.5 Productivity gain per year 35% Early detection gain per year (defects discovered pre-test) 22% Benefits Yearly reduction in time to market 19% Yearly reduction in post-release defect reports 39% Business value of investment in SPI (value returned on each dollar invested) 5.0 Source: Software Engineering Institute, CMU/SEI-94-TR-13, page 15.

6. Requirement Driven Development Process • Process items • Automatic linking • Rich IDE integration • Custom forms • Custom workflow • Change packages • Custom tools

7. The StarTeam Product Family

8. Publish requirements from CaliberRM or enter directly into StarTeam Publish defects from Test Director or enter directly in StarTeam Link Select a Requirement, Change Request or Task and check in all modified files Check out files to the local workstation for editing StarTeam automatically links the development assets Implementing RDDP Local Workstation

9. CR Driven Development Mercury TestDirector StarTeam Change Request 58 Bug 89 Out of date logo on web site and all applications Out of date logo on web site and all applications File: Main.cpp Revision: 1.1 File: Layout.java Revision: 1.1 File: Logo.jpg Revision: 1.4

10. Task Driven Development Microsoft Project StarTeam Task 1: Change Task 1:Change Layout Task2: Replace Logo Layout Revision: 1.1 File: Layout.java Revision: 1.1 StarTeam Task 2:Replace Logo File: Main.cpp Revision: 1.2 File: Logo.jpg Revision: 1.4

11. CaliberRM Requirement 128 User must logon to system Requirement Driven Development StarTeam Requirement 5 User must logon to system File: Main.cpp Revision: 1.1 File: Layout.java Revision: 1.1 File: Logo.jpg Revision: 1.4

12. Customizing StarTeam Forms

13. Custom Forms • Gather the information required by your development process • Customize Change Requests, Tasks, and Requirement forms • Control access to information and approval by role

15. Custom Workflow Enter • Implement the workflow required by your development process • Graphically customize the workflow model • Program custom workflow behaviors Design and Implement Review Approve Defer Deploy

16. Using the Workflow Designer • Workflow is separate from the form • Defined in <Item Type>.workflow.xml • Example: ChangeRequest.Workflow.XML • Stored in the StarFlow Extensions project • Automatically deployed when changed

18. S D K

19. Extending Custom Forms • ItemWrapper class put() method • ExtendedItemWrapper subclass allows you to override the put() method • Alternate launcher in propertyeditor.xml • <?xml version="1.0" encoding="UTF-8"?> • <propertyeditor name="Change Request Editor"> • <javaclass name="com.starbase.starteam.changerequest.ChangeRequestLauncher2"> • <jar name="ChangeRequest.jar"/> • <jar name="guicomponents.jar"/> • <jar name="starflow-extensions.jar"/> • </javaclass> • </propertyeditor>

20. StarTeam Extensions • API Documentation • Workflow classes • Locator classes • GUI Builder Classes • Deployer Classes • Tool Framework Classes

21. StarFlow Services • Custom behavior that is independent of form code and applies to all forms • Defined in <Item Type>.service.xmlExample: ChangeRequest.service.xml • Stored in StarFlow Extensions project • Automatically deployed when changed • NOT used by Web Edition Web Edition requires custom ASP coding

22. Repository Customizer and Setup • CreateTypeCustomizer.js • Captures repository metadata • Generates a script to use in customizing a new repository • Setup.java • Hand coded method to customize a new repository

23. StarTeam SDK Overview

24. StarTeam Architecture Windows Client StarTeam SDK Native GUI APIs StarTeam Server

25. Scriptable Clients VB WSH ASP C/C++ Clients Java Clients Automation COM APIs Public Java APIs Java Implementation StarTeam APIs

26. StarTeam SDK Development Environment • Java: • Add starteam-sdk.jar to your classpath • VB (or other COM language): • Register StarTeamSDK.dll • C++: • Link StarTeamSDK_i.c • Include StarTeamSDK.h • C# or VB.NET: • Use the StarTeam.NET.dll • Use the StarTeam.vjs.dll • Cross-compiled J#: • Use the StarTeam.vjs.dll

27. Projects View DefaultView Folder DerivedViews Project Root Folder Folder SubFolders Project Folder ... View ... Project View Folder ... View StarTeam Object Model s = new Server( address, port ); s.connect(); s.logOn(); Server Folder f = v.getRootFolders(); Project[] projects = s.getProjects(); // Find your Project and assign to p View[] views = p.getViews(); // Find your View and assign to v Folder[] subFolders = f.getSubFolders();

28. ListFolder Example public static void main(String[] args) { Server s = new Server("localhost", 49201); s.connect(); s.logOn("SReynolds", ""); Project[] projects = s.getProjects(); for (int i = 0; i < projects.length; i++) { Project p = projects[i]; View[] views = p.getViews(); for (int j = 0; j < views.length; j++) { View v = views[j]; Folder f = v.getRootFolder(); folders(f); } } } static protected void folders(Folder f) { Folder[] subfolders = f.getSubFolders(); for (int i = 0; i < subfolders.length; i++) { folders(subfolders[i]); } }

29. TypedResource File ChangeRequest Requirement Task Folder Items get(strPropertyName) put(strPropertyName, Value) Item ParentFolder History addAttachment() checkin() checkout() Status Severity Priority

30. Files Change Requests Requirements Tasks Req. File Task CR File CR Task Req. ... ... ... ... CR File Req. Task Folders Folder f.getItems( s.getTypesNames().FILE ) f.getItems( s.getTypesNames().CHANGEREQUEST ) f.getItems( “Requirement” ) f.getItems( s.getTypesNames().TASK )

31. TypeNames Types PropertyNames TypeNames Property PropertyNames Property Type Properties ... Type Property ... Type Types and Properties Server typeForName(strTypeName) propertyForName(strName) FILECHANGEREQUESTREQUIREMENT TASK TOPIC Name DisplayName TypeCode EnumValuesgetEnumDisplayName()

32. User Group User Group GroupAccount ... ... User Group GroupAccount ... GroupAccount Users and Groups Server MyUserAccount Administration UserAccount UserAccount ... UserAccount

33. Using the StarTeam SDK

34. StarTeam Finder • Connects directly to StarTeam server, project, view, folder • Server URL:user:pass@servername:49201 • Server/Project/View/Folder URL:user:pass@servername:49201/ProjectName/ViewName/FolderA/FolderB • Connecting to a Folder: ...//connect directly to a folder on the StarTeam Server String url = "user:pass@servername:49201/ProjectName/ViewName/FolderA/FolderB";Folder myFolder = StarTeamFinder.openFolder(url);...

35. Getting and Setting Item Properties • Methods on TypedResource base class: • put (String propertyName, Object value) • get(String propertyName) • Use the getPropertyNames enumeration on the Server instance to retrieve standard property names for items. • Convenience methods on specific object types • Example: getSynopsis(), setSynopsis(String synopsis) • Note that .NET syntax is different: • Access the properties directly as member variables on the object instance • Example: myCR.synopsis ...String crTypeStr = myServer.getTypeNames().CHANGEREQUEST;String synopsisStr = myServer.getPropertyNames().CR_SYNOPSIS;Item[] crs = myFolder.getItems(crTypeStr);for (int i = 0; i < crs.length; i++){ crs[i].set(synopsisStr,"New Synopsis"); crs[i].update(); } ...

36. Custom Fields • Retrieve custom fields (User Defined Attributes) using the field name string that the user defined when creating the field. • Custom fields always begin with the "Usr_" prefix • (for example "Usr_CustomFieldName")

37. Item State Your changes will not save until you call update() !

38. Finding Items by ItemID • A method to retrieve an item, given a specific type and ID. ...String crTypeStr = myServer.getTypeNames().CHANGEREQUEST; // find CR with ItemID 100ChangeRequest cr = (ChangeRequest) myView.findItem (crTypeStr, 100);if (cr == null){ System.out.println(“Error: CR 100 not found!”);}else{ System.out.println(cr.getSynopsis());}...

39. Caching • StarTeam uses an internal caching mechanism • Item properties are retrieved as requested • Properties are then cached • Data is not saved until the update() command is called • The following methods indicate an item that requires updating: • isDirty() • isNew()

40. Caching Sequence

41. Tuning the Caching Mechanism • Populate required properties in a single network call: • populateNow(java.lang.String typeName, java.lang.String[] propertyNames, int depth) • populateAsNeeded(java.lang.String typeName, java.lang.String[] propertyNames, int chunkSize) • populateInBackground(java.lang.String typeName, java.lang.String[] propertyNames, int chunkSize) • Populate required properties in a single call: • populateNow(java.lang.String typeName, java.lang.String[] propertyNames, int depth) • Release cached objects: • discardItems(java.lang.String typeName, int depth) • Refresh cached items: • refreshItems(java.lang.String

42. Performance Considerations • Slow • Simple loop • Faster • PopulateNow • PopulateInBackground • ItemList • Fastest • ListManager

43. Checking Out Files • checkout • (lockStatus, timeStampNow, eol, updateStatus) • Checks out to current working folder. • checkoutTo • (checkoutTo, lockStatus, timeStampNow, eol, updateStatus) • Specify the local folder to check out to. Since you are passing in a java.io.File object, you can even check out to a temporary directory. • checkoutToStream • (destination, lockStatus, eol) • Check out to an OutputStream.

44. Checking Out Files from History • checkoutByDate • (checkoutTo, date, lockStatus, timeStampNow, eol, updateStatus) • Checks out the file version at a specific date. • checkoutByLabelID • (checkoutTo, labelID, lockStatus,  timeStampNow,  eol, updateStatus) • Checks out file version pinned to the specified label. • checkoutByVersion • (checkoutTo, viewVersion, lockStatus, timeStampNow, eol, updateStatus) • Checks out specified version of a file

45. Checking In Files • checkin • (reason, lockStatus, forceCheckin, eol, updateStatus) • Check in file from the current working directory • checkinFrom • (file, reason, lockStatus, forceCheckin, eol, updateStatus) • Check in file from a different location • checkinFromStream • (source, checkinReason, lockStatus, eol) • Check in file from an output stream • Always trap IOException

46. Links • Any StarTeam Item can be linked to any number of other Items • Items can be linked to specific versions of Items • Every Link is an association between 2 items • Source Item • Target Item • Server.findLinks(parentItem) • Returns an array of Link objects • Link.getParentEndpoint & link.getChildEndpoint • Will retrieve endpoints for the relationship • View.resolveLinkEndpoint(endpoint) • Will resolve to the StarTeam object

47. Resolving a Link // Retrieve all the links for myItem Link[] links = myServer().findLinks(myItem); // Iterate through the links, and find the context-knowledgeable Item for (int i = 0; i < links.length; i++){ LinkEndPoint endPoint = links[i].getChildEndPoint(); View linkView = findView(endPoint.getViewID); Item linkItem = linkView.findItem( endPoint.getType(), endPoint.getItemID); ... } }

48. Labels • Label Types • View Label • Revision Label • View.fetchAllLabels() • Item.getAttachedLabels() • Label.getLabeledItemIDs() • Label.attachToItem(item)

49. MPX Event Listener • Available in StarTeam Version 5.4+ for the Java API only • Allows clients to receive notification when a StarTeam object is created, deleted, or modified • Provides ability to trigger external events when an item changes, or report on changed items

50. Enabling MPX • MPX must be enabled for events to be broadcast • Multicast is not yet supported • Manually enable MPX for login • Server.enableMPX() • Server.isMPXEnabled()