maximizing developer productivity with jbuilder and starteam preconference tutorial
TRANSCRIPT
Maximizing Developer Productivity with JBuilder and StarTeam
Preconference Tutorial
Agenda
Introduction Customizing StarTeam Forms StarTeam SDK Overview Using the StarTeam SDK StarTeam Dynamic Toolbar Integrations
Introduction
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
ROI of Software Process Improvement
Category MedianTotal 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 ItYourself
Benefits
Requirement Driven Development Process
Process items Automatic linking Rich IDE integration Custom forms Custom workflow Change packages Custom tools
The StarTeam Product Family
Major Features StarTeam Standard StarTeam Enterprise StarTeam Enterprise Advantage
Configuration Management
√ √ √
Change Requests √ √ √
Tasks √ √
Requirements √
Customization √
Workflow √
Dynamic Tools √
Notification Basic Basic Customizable
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
CR Driven Development
MercuryTestDirector
Bug 89Out of date logo on web site
and all applications
StarTeamChange Request 58
Out of date logo on web siteand all applications
File: Main.cppRevision: 1.1
File: Layout.javaRevision: 1.1
File: Logo.jpgRevision: 1.4
Task Driven Development
Microsoft ProjectTask 1:Change LayoutTask2: Replace Logo
StarTeamTask 1: Change
Layout
StarTeamTask 2:Replace Logo
Revision: 1.1
File: Layout.javaRevision: 1.1
File: Main.cppRevision: 1.2
File: Logo.jpgRevision: 1.4
Requirement Driven Development
CaliberRMRequirement
128User must logon to
system
StarTeamRequirement 5
User must logon to
system File: Main.cppRevision: 1.1
File: Layout.javaRevision: 1.1
File: Logo.jpgRevision: 1.4
Customizing StarTeam Forms
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
Custom Workflow
Implement the workflow required by your development process
Graphically customize the workflow model
Program custom workflow behaviors
Enter
ReviewDesign and Implement
Defer Approve
Deploy
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
StarTeam VTS ServerStarFlow Extensions Project
Form.JarWorkflow.XML
PropertyEditor.XML
SDK
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>
StarTeam Extensions
API Documentation Workflow classes Locator classes GUI Builder Classes Deployer Classes Tool Framework Classes
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
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
StarTeam SDK Overview
StarTeam Architecture
StarTeam Server
Windows Client
Native GUI
StarTeam SDK
APIs
StarTeam APIs
Java Implementation
Java Clients
Public Java APIs
C/C++ Clients
COM APIs
Automation
Scriptable Clients
VBWSHASP
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
StarTeam Object Model
s = new Server( address, port );s.connect();s.logOn();
Server
Project
Project
Project
...
ProjectsView
DefaultView
DerivedViews
View
View
View
...
Folder
RootFolder
Folder
Folder
Folder
...
SubFolders
Project[] projects = s.getProjects();// Find your Project and assign to pView[] views = p.getViews();
// Find your View and assign to v
Folder f = v.getRootFolders();
Folder[] subFolders = f.getSubFolders();
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 ExampleListFolder Example
Items
File
Task
ChangeRequest
Requirement
Item
TypedResource
Folder
get(strPropertyName)put(strPropertyName, Value)
ParentFolderHistoryaddAttachment()
checkin()checkout()
StatusSeverityPriority
Folders
Folder
FilesFile File File...
CR CR CR...ChangeRequests
Req. Req. Req....Requirements
Task Task Task...Tasks
f.getItems( “Requirement” )
f.getItems( s.getTypesNames().CHANGEREQUEST )
f.getItems( s.getTypesNames().FILE )
f.getItems( s.getTypesNames().TASK )
Types and Properties
Server
TypeNames
TypeNames Type
Type
Type
...
Types
Property
Property
Property
...
PropertiesFILECHANGEREQUESTREQUIREMENTTASKTOPIC
typeForName(strTypeName)
PropertyNames
PropertyNames
NameDisplayNameTypeCode
EnumValuesgetEnumDisplayName()
propertyForName(strName)
Users and Groups
Server
Group
Group
Group
...
User
User
User
...
AdministrationMyUserAccount
GroupAccount
GroupAccount
GroupAccount
...
UserAccount
UserAccount
UserAccount
...
Using the StarTeam SDK
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 ServerString url = "user:pass@servername:49201/ProjectName/ViewName/FolderA/FolderB";Folder myFolder = StarTeamFinder.openFolder(url);...
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();
} ...
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")
Item State
Your changes will not save until you call update() !
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());
}...
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()
Caching Sequence
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
Performance Considerations
Slow Simple loop
Faster PopulateNow PopulateInBackground ItemList
Fastest ListManager
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.
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
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
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
Resolving a Link
// Retrieve all the links for myItemLink[] 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); ...}
}
Labels
Label Types View Label Revision Label
View.fetchAllLabels() Item.getAttachedLabels() Label.getLabeledItemIDs() Label.attachToItem(item)
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
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()
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
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
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)
Item Events
ItemEvent getOldItem() getNewItem()
ItemIDEvent getItemID()
ItemListEvent getFolder() getType()
NotificationEvent getItem()
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();
Where to get the StarTeam SDK
Download the complete StarTeam SDKhttp://www.borland.com/
Includes complete API documentation and basic samples
Download additional samples fromhttp://codecentral.borland.com
StarTeam Dynamic Toolbar
Dynamic Toolbar
Cross-Platform Client custom toolbarOnly available with the Cross-Platform Client
Automatically distributes custom toolsNo need for separate installation for custom tools
Integrates with the cross-platform clientMakes using custom tools and utilities easy
Custom CR Tools
Custom View Tools
Custom Task Tools
Custom View Tools
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
Integrations
Team Menu
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
Custom Tools
Custom Tools
Dynamic Tools in C++ Builder
Custom CR Tools
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