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