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

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

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 Major FeaturesStarTeam StandardStarTeam EnterpriseStarTeam Enterprise Advantage Configuration Management √√√ Change Requests√√√ Tasks√√ Requirements√ Customization√ Workflow√ Dynamic Tools√ NotificationBasic Customizable

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

9. CR Driven Development Mercury TestDirector Bug 89 Out of date logo on web site and all applications StarTeam Change Request 58 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 Task 1:Change Layout Task2: Replace Logo StarTeam Task 1: Change Layout StarTeam Task 2:Replace Logo Revision: 1.1 File: Layout.java Revision: 1.1 File: Main.cpp Revision: 1.2 File: Logo.jpg Revision: 1.4

11. Requirement Driven Development CaliberRM Requirement 128 User must logon to system 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  Implement the workflow required by your development process  Graphically customize the workflow model  Program custom workflow behaviors Enter Review Design and Implement Defer Approve Deploy

16. Using the Workflow Designer  Workflow is separate from the form  Defined in.workflow.xml  Example: ChangeRequest.Workflow.XML  Stored in the StarFlow Extensions project  Automatically deployed when changed

18. SDKSDK

19. Extending Custom Forms  ItemWrapper class put() method  ExtendedItemWrapper subclass allows you to override the put() method  Alternate launcher in propertyeditor.xml 

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.service.xml Example: 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 StarTeam Server Windows Client Native GUI StarTeam SDK APIs

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

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. StarTeam Object Model s = new Server( address, port ); s.connect(); s.logOn(); Server Project... Projects View Default View DerivedViews View... Folder Root Folder... SubFolders Project[] projects = s.getProjects(); // Find your Project and assign to p View[] views = p.getViews(); // Find your View and assign to v Folder f = v.getRootFolders(); Folder[] subFolders = f.getSubFolders();

28. 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]); } ListFolder Example

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

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

31. Types and Properties Server TypeNames Type... Types Property... Properties FILE CHANGEREQUEST REQUIREMENT TASK TOPIC typeForName(strTypeName) PropertyNames Name DisplayName TypeCode EnumValues getEnumDisplayName() propertyForName(strName)

32. Users and Groups Server Group... User... AdministrationMyUserAccount GroupAccount... 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 100 ChangeRequest 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()

51. Optimized Refresh with MPX  Caching mechanism requires explicit method calls to retrieve data from the server and discard cached data:  Refresh()  RefreshItems()  Discard()  When MPX is enabled, refresh operations are faster

52. Event Notification with MPX  Use the java listener model: java.util.EventListener  Adapters for each listener interface are available  Listeners may be registered with a View, Folder, or ItemListManager

53. Item Listeners  ItemListener  Notified when an items of a type gets added, removed, or modified.  ItemListListener  Notified when items of a type have changed (without the details).  ItemIDListener  Notified when an item has been added, removed, or modified  Only provides access to the ItemID.  NotificationListener  Notified when an item reaches a certain state (workflow)

54. Item Events  ItemEvent  getOldItem()  getNewItem()  ItemIDEvent  getItemID()  ItemListEvent  getFolder()  getType()  NotificationEvent  getItem()

55. Adding an Item Listener  Create the ItemListener (easiest to use Adapters): ItemListener myListener = new ItemAdapter() { public void itemAdded(ItemEvent event) { System.out.println("Item Added."); } };  Register with the desired container: folder.addItemListener(myListener, type, depth);  Start event handling thread: server.handleEvents();

56. Where to get the StarTeam SDK  Download the complete StarTeam SDK http://www.borland.com/ http://www.borland.com/  Includes complete API documentation and basic samples  Download additional samples from http://codecentral.borland.com http://codecentral.borland.com

57. StarTeam Dynamic Toolbar

58. Dynamic Toolbar  Cross-Platform Client custom toolbar Only available with the Cross-Platform Client  Automatically distributes custom tools No need for separate installation for custom tools  Integrates with the cross-platform client Makes using custom tools and utilities easy

59. Custom CR Tools Custom View Tools

60. Custom Task Tools Custom View Tools

61. public class MyTool extends AbstractTool { public void service() throws ToolException, UnavailableException { final ItemListContext ctx = (ItemListContext)getService(ItemListContext.class, null); if (ctx == null) {throw new UnavailableException("ItemListContext not available", 0);} final String eol = System.getProperty("line.separator"); final String msg = "Item Type: " + ctx.getType() + eol + "All Items: " + ctx.getAllItems().size() + eol + "[" + (ctx.getAllItems().size() > 0 ? ctx.getAllItems().getAt(0) + ", " : "") + "...]" + eol + "Selected Items: " + ctx.getSelectedItems().size() + eol + "[" + (ctx.getSelectedItems().size() > 0 ? ctx.getSelectedItems().getAt(0) + ", " : "") + "...]" + eol; final JTextArea ta = new JTextArea(15, 30); ta.append(msg); JOptionPane.showMessageDialog(null, new JScrollPane(ta), "MyTool", JOptionPane.INFORMATION_MESSAGE); releaseService(ctx); } MyTool Sample

62. Integrations

63. Team Menu

64. Rich Integration  Direct access to StarTeam  Workflow enabled custom forms for all StarTeam item types  Permits customizations to be integrated into the JBuilder and C++ Builder IDEs

66. Custom Tools

68. Dynamic Tools in C++ Builder Custom CR Tools

69. CaliberRM Integration  Import CaliberRM requirements  Utility included does not support UDAs  Custom tool can import UDAs  Custom StarTeam form can launch CaliberRM  StarTeam Addin for CaliberRM  Supports External Traceability tab  Displays custom forms  Replicating StarTeam links as CaliberRM traces  Follows StarTeam links  Displays links in Traceability Matrix