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