Transcript Document

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
The Need for Control
Did we update the model? Didn’t we fix this already?
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!
Why is it taking so long?
Is this code documented?
ROI of Software Process Improvement
Category
Median
Total yearly cost of Software Process
Improvement (SPI) activities
$245,000
Years engaged in SPI
3.5
Productivity gain per year
35%
Early detection gain per year (defects
discovered pre-test)
22%
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.
To Do It
Yourself
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
Publish
requirements from
CaliberRM or
enter directly into
StarTeam
Check out files to
the local
workstation for
editing
Publish defects
from Test Director
or enter directly in
StarTeam
StarTeam automatically links
the development assets
Local Workstation
Select a
Requirement,
Change Request or
Task and check in all
modified files
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
Task Driven Development
Microsoft Project
Task 1:Change Layout
Task2: Replace Logo
StarTeam
Task 1: Change
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
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
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
Enter
 Implement the workflow required by
your development process
Review
Defer
Design and
Implement
Approve
Deploy
 Graphically customize the workflow
model
 Program custom workflow behaviors
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
S
D
K
StarTeam VTS Server
StarFlow Extensions Project
Form.Jar
Workflow.XML
PropertyEditor.XML
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.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
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
Windows Client
StarTeam SDK
Native GUI
APIs
StarTeam Server
StarTeam APIs
Scriptable
Clients
C/C++
Clients
Java
Clients
Automation
COM APIs
Public Java APIs
Java Implementation
VB
WSH
ASP
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();
Projects
Folder f = v.getRootFolders();
Server
Default
Project[]
View
View
projects = s.getProjects();
View[] views = p.getViews();
Project
// Find your DerivedViews
Project and assign to p
Folder
// Find your View and assign to v
Root
SubFolders
Folder[] subFolders = f.getSubFolders();
Project
...
View
Project
View
Folder
Folder
...
Folder
View
...
Folder
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]);
}
}
Items
TypedResource
get(strPropertyName)
put(strPropertyName, Value)
Item
ParentFolder
History
addAttachment()
File
checkin()
checkout()
ChangeRequest
Requirement
Task
Folder
Status
Severity
Priority
Folders
Folder
f.getItems( s.getTypesNames().FILE )
Files
File
File
...
File
f.getItems( s.getTypesNames().CHANGEREQUEST )
Change
Requests
CR
CR
...
CR
f.getItems( “Requirement” )
Requirements
Req.
Req.
...
Req.
f.getItems( s.getTypesNames().TASK )
Tasks
Task
Task
...
Task
Types and Properties
Server
typeForName(strTypeName)
TypeNames
TypeNames
FILE
CHANGEREQUEST
REQUIREMENT
TASK
TOPIC
Types
PropertyNames
Type
Type
propertyForName(strName)
PropertyNames
Properties
...
Type
Name
EnumValues
DisplayName
getEnumDisplayName()
TypeCode
Property
Property
...
Property
Users and Groups
Server
User
Group
User
...
Group
...
User
Group
MyUserAccount
Administration
UserAccount
GroupAccount
UserAccount
...
GroupAccount
...
UserAccount
GroupAccount
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 Server
String 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 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());
}
...
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 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);
...
}
}
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 SDK
http://www.borland.com/
 Includes complete API documentation and basic samples
 Download additional samples from
http://codecentral.borland.com
StarTeam Dynamic Toolbar
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
Custom CR Tools
Custom View Tools
Custom Task Tools
Custom View Tools
MyTool Sample
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);
}
}
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