StarTeam SDK New FeaturesRandy Guck, Chief Scientist, Borland

Overview

Summary of new SDK features for StarTeam 2005 R2 Deeper probe into key features:

Auto-logon The CheckoutManager family Not-in-view folders New, non-MPX event facility

Also see the sessions: Accelerating File Check-outs with the StarTeamMPX Cache

Agent StarTeam URLs: Creating and Using Persistent Links to

StarTeam Artifacts

What’s new with R2

Notes and minor new features StarTeam 2005 R2 SDK internal release number: 8.0 SDK apps can access servers back to 5.2 release

Exceptions thrown for inaccessible features

Supports for “delta check-out” (aka “optimize for slow connections”)

Part of new CheckoutManager class

EnumeratedValue class: new SortOrder property ServerAdministration.updateEnumeratedField() sets sort order

Foreign archives: can refresh and convert foreign files View.close(): Releases resources without having to call

Server.disconnect()

Auto-logon

Credential caching Currently uses StarTeam Toolbar May use other facilities later

New Server methods isCredentialCachingAvailable(): is Toolbar installed? isCredentialCachingEnabled(): Is Toolbar running? enableCredentialCaching(): start the Toolbar cacheLogOnCredentials(String username, String password):

save credentials for this server isAutoLogOnAvailable(): are credentials saved for this server? autoLogOn(): call logOn() with cached credentials for this server

Auto-logon: Java Example

// Demonstrate SDK auto-logon featurevoid logOnDemo() { // Create the Server object we want to connect to. Server server = new Server("localhost", 49201);

// See if credential caching is available and enabled. boolean bCanCacheCredentials = false; if (Server.isCredentialCachingAvailable()) { // Credential caching is available; is it enabled? if (Server.isCredentialCachingEnabled()) { // Credential caching is available and enabled. bCanCacheCredentials = true; } else { // Attempt to enable credential caching. Wait 1 second to let Toolbar // initialize. Server.enableCredentialCaching(); try {Thread.sleep(1000);} catch (InterruptedException ex) {} if (Server.isCredentialCachingEnabled()) { bCanCacheCredentials = true; } else { // Couldn't enable credential caching. } } }

// continued next slide...

Auto-logon: Java Example (cont.)// ...continued from previous slide // If credential caching is working, see if we can auto-logon to server. try { // logOn throws an exception is the logon fails if (bCanCacheCredentials) { // See if credentials are already cached for this server. if (server.isAutoLogOnAvailable()) { // Credentials are available for this server; attempt auto-logon. server.autoLogOn(); } else { // Credentials are not available for this server; get them from the // user and cache them if they work. Credentials credentials = promptForCredentials(); // local method server.logOn(credentials.userid, credentials.password); server.cacheLogOnCredentials(credentials.userid, credentials.password); } } else { // Credential caching is not available, just prompt for credentials. Credentials credentials = promptForCredentials(); server.logOn(credentials.userid, credentials.password); } // Here, we're logged-on. } catch (RuntimeException ex) { // StarTeam logon failed. }} // logOnDemo

The CheckoutManager Family

If File.checkOut(Xx) is the father of check-out… Then CheckoutManager is the “mother of all check-outs” Meet the whole family

CheckoutOptions: Lots of check-out options in one place CheckoutManager: The check-out engine CheckoutListener (Java) and CheckoutEventSource (.Net):

receive events for and optionally modify options for each file ContentFilter: Insert your own code in the check-out stream CheckoutProgress: Get in-progress or final snapshot of check-

out statistics

CheckoutOptions

What can you do with CheckoutOptions? Initialize from View or StarTeamClientOptions Set desired options (defaults are underlined)

Set ViewConfiguration: tips, by date, by label, by promotion state Install a ContentFilter object (null) Set EOL conversion (true) and EOL char (text files; platform default) Enable keyword expansion (overrides project setting) Set file encoding for keyword expansion (platform default) Set lock type: UNCHANGED, EXCLUSIVE, etc. Mark non-locked files as “read only” (false) Restore failed partially checked-out files (true) Set workfile timestamp to check-out time (false) Allow “delta check-out” for out-of-date text files (false) Update each file’s status (true)

CheckoutOptions Example: C#// Create CheckoutOptions from a View.View view = StarTeamFinder.OpenView("joe:pw@localhost:49201/StarDraw");CheckoutOptions coOpts1 = new CheckoutOptions(view);

// Clone CheckoutOptions.CheckoutOptions coOpts2 = new CheckoutOptions(coOpts1);

// Create CheckoutOptions from default client options.StarTeamClientOptions defaultClientOptions = StarTeamClientOptions.Default;CheckoutOptions coOpts3 = new CheckoutOptions(defaultClientOptions);

// Enable EOL conversion and set EOL char to CRLF.coOpts1.EOLConversionEnabled = true;coOpts1.EOLChars = CheckoutOptions.EOL_CRLF;

// Request each file to be locked exclusively.coOpts1.LockType = Item.LockType.EXCLUSIVE;

// Request keyword expansion and set keyword encoding.coOpts1.KeywordExpansionEnabled = true;coOpts1.FileEncoding = "ISO-10646";

CheckoutManager

What can you do with a CheckoutManager? Request check-out from an MPX Cache Agent

Specific or auto-located; one of more request threads

Register one or more CheckoutListener objects (Java) or CheckoutEventSource delegates (.Net)

Monitor the check-out progress via CheckoutProgress Check out files in various ways:

Single File to the default or alternate workfile or to an OutputStream (Java) or Stream (.Net)

All files in a Folder, optionally to a specified depth All files in an Item array (Java) or ItemCollection (.Net) All files in an ItemList All files returned by an Items interface object

Call setCanceled() to cancel check-out

CheckoutManager Example

// Create a CheckoutManager from a View with the options from above.CheckoutManager coMgr1 = new CheckoutManager(view, coOpts3);

// Create a CheckoutManager from a View with default options.CheckoutManager coMgr2 = new CheckoutManager(view);

// Clone a CheckoutManager.CheckoutManager coMgr3 = new CheckoutManager(view, coMgr2);

// Check-out a single file to its default location from an auto-located// MPX Cache Agent.coMgr1.setMPXCacheAgentEnabled(true); // default is auto-locatecoMgr1.setMPXCacheAgentThreadCount(2); // allow two request threadsFolder rootFolder = view.getRootFolder();File file = StarTeamFinder.findFile(rootFolder, "index.htm", false);coMgr1.checkout(file);

// Checkout all files in a folder, recursively (still Cache Agent-enabled)coMgr1.checkout(rootFolder, -1); // -1 means "all descendents"...// From another thread, cancel the check-outcoMgr1.setCanceled();

CheckoutListener (Java)

How do you use a CheckoutListener? Install via CheckOutManager.addCheckoutListener() During check-out, CheckoutListener is called for each file:

onStartFile(CheckoutEvent event) event.getCurrentFile(): the File about to start event.setCurrentWorkingFile(): change File’s working file event.getOptions(): to modify file-specific CheckoutOptions

onNotifyProgress(CheckoutEvent event) event.isFinished(), event.isSuccessful(), event.isCanceled():

examine check-out outcome event.getProgress(): get CheckoutProgress snapshot

If you want to cancel the check-out: event.getCheckoutManager().setCanceled()

CheckoutListener Example// Create an in-line anoynymous CheckoutListener object.CheckoutListener listener = new CheckoutListener() { public void onStartFile(CheckoutEvent checkoutEvent) { String fileName = checkoutEvent.getCurrentFile().getFullName(); System.out.println("Starting file: " + fileName); } // onStartFile

public void onNotifyProgress(CheckoutEvent checkoutEvent) { String fileName = checkoutEvent.getCurrentFile().getFullName(); if (checkoutEvent.isFinished()) { // File is finished, successfully or cancelled if (checkoutEvent.isCanceled()) { System.out.println("File canceled: " + fileName); } else if (checkoutEvent.isSuccessful()) { System.out.println("File finished: " + fileName); } else { System.out.println("File failed: " + fileName); } } } // onNotifyProgress};

// Register the CheckoutListener and then check-out all files in a folder,// recursively.coMgr1.addCheckoutListener(listener);coMgr1.checkout(rootFolder, -1); // -1 means "all descendents"

CheckoutEventSource (.Net)

CheckoutEventSource uses .Net event model Created by CheckoutManager.NewCheckoutEventSource() CheckoutEventSource.Handler is a delegate with two

parameters: CheckoutEventSource: source of the event CheckoutEventArgs: similar to Java CheckoutEvent

CurrentFile, Options, Progress, IsFinished, IsSuccessful, etc.

CheckoutEventSource has two events: OnStartFile: called just before the check-out of each file OnNotifyProgress: called upon completion of each file

Events have same semantics as Java CheckoutListener interface

CheckoutEventSource Example// Create a CheckoutEventSource and register event handlers.CheckoutEventSource eventSource = coMgr1.NewCheckoutEventSource();eventSource.OnStartFile += new CheckoutEventSource.Handler(OnStartFile);eventSource.OnNotifyProgress += new CheckoutEventSource.Handler(OnNotifyProgress);

// Check-out all files from the root folder, which will generate events.coMgr1.Checkout(rootFolder, -1); // -1 means "all descendents"...// Callback for CheckoutEventSource.OnStartFilevoid OnStartFile(CheckoutEventSource source, CheckoutEventArgs args) { System.Console.WriteLine("Starting file: {0}", args.CurrentFile.FullName);} // OnStartFile

// Callback for CheckoutEventSource.OnNotifyProgressvoid OnNotifyProgress(CheckoutEventSource source, CheckoutEventArgs args) { if (args.IsFinished) { // File is finished, successfully or cancelled if (args.IsCanceled) System.Console.WriteLine("File canceled: {0}", args.CurrentFile.FullName); else if (args.IsSuccessful) System.Console.WriteLine("File finished: {0}", args.CurrentFile.FullName); else System.Console.WriteLine("File failed: {0}", args.CurrentFile.FullName); }} // OnNotifyProgress

ContentFilter

How to use a ContentFilter Insert via CheckoutManager.setContentFilter() Java or

CheckoutManger.ContentFilter property in .Net CheckoutManager calls interface’s sole method for each file:

OutputStream getOutputStream(File file, OutputStream stream)for Java

Stream GetOutputStream(File file, Stream stream) for .Net

ContentFilter must return a stream, to which file content will be written

ContentFilter should write pass its (filtered) output to the stream it receives

ContentFilter Example// Create a ContentFilter object that counts spaces of each file whose check-out// it hooks.ContentFilter spaceCounter = new ContentFilter () { // Method we're required to implement for the ContentFilter interface. public OutputStream getOutputStream(File file, OutputStream outputStream) { // Create a CounterStream specific for this file and return it. Since we // create a new stream for each file, this technique is thread-safe. CounterStream counterStream = new CounterStream(file, outputStream); return counterStream; } // Embedded OutputStream subclass that counts total bytes and spaces that // flow through the stream. class CounterStream extends OutputStream { // Implement constructor, Write, Flush, and Close // ... } // embedded class CounterStream}; // anonymous ContentFilter object

// Check-out all files from the root folder down using a ContentFilter so we can// count the number of bytes and spaces in each file.CheckoutOptions coOpts = new CheckoutOptions(view);coOpts.setContentFilter(spaceCounter);CheckoutManager coMgr = new CheckoutManager(view, coOpts);coMgr.setMPXCacheAgentEnabled(true);coMgr.checkout(view.getRootFolder(), -1);

CheckoutProgress

How to use CheckoutProgress Snapshots obtained from check-out events

CheckoutEvent.getProgress() – Java CheckoutEventArgs.Progress property – .Net

Final results obtained from CheckoutManager.GetProgress() Statistics you can obtain:

Number of fetch threads used Last error that occurred Overall, per-thread, and Cache Agent-specific statistics:

Files fetched, skipped, remaining, and failed Bytes checked-out Elapsed time consumed

CheckoutProgress Example

// Check-out all files from a view’s root folder via the Cache Agent.CheckoutManager coMgr = new CheckoutManager(view);coMgr.MPXCacheAgentEnabled = true;coMgr.Checkout(view.RootFolder, -1);

// Display final check-out statisticsCheckoutProgress stats = coMgr1.Progress;System.Console.WriteLine("Final check-out statistics");System.Console.WriteLine(" Total files: {0}", stats.TotalFilesCheckedOut);System.Console.WriteLine(" Total bytes: {0}", stats.TotalBytesCheckedOut);float caTimeSecs = ((float)stats.TotalCommandTimeByMPXCacheAgent / 1000);System.Console.WriteLine(" CA c/o time: {0} seconds", caTimeSecs);float totalTimeSecs = ((float)stats.TotalCommandTime / 1000);System.Console.WriteLine(" Total time: {0} seconds", totalTimeSecs);float bytesPerSec = stats.TotalBytesCheckedOut / totalTimeSecs;System.Console.WriteLine(" Bytes/sec : {0}", bytesPerSec);

Not-in-View Folders

New methods make it easier to manage “not-in-view” folders, which are those missing in current view: New Folder methods:

Folder getFolderTree(int context, int depth): returns Folder tree copy with local, server, or both folder types included, up to depth

File[] getNotInViewFiles(): now works with local-only folders void updateFolderTree(int depth): creates missing server folders in

tree up to depth

FolderListManager: now supports not-in-view folders ItemListManager: now supports not-in-view folder items

Not-in-View Folders Example// Demonstrate how to find all not-in-view folders and files in a given view.void notInViewFilesDemo(Server server) { // Get the root folder for the StarDraw main view. View view = findView(server, "StarDraw"); Folder rootFolder = view.getRootFolder(); try { // Get the same folder, populated with "local and server" context, which // means that non-in-view folders will be included in the tree, and display // them recursively. Folder rootFolderWithNIVs = rootFolder.getFolderTree(Filter.CONTEXT_LOCAL_AND_SERVER, -1); displayNIVFoldersAndFiles(rootFolderWithNIVs); } catch (IOException ex) { System.out.println("Couldn't get NIV Folders: " + ex); }} // notInViewFilesDemo

// continued...

Not-in-View Folders Example (cont.)// Find and display all non-in-view folders and files in the given folder,// recursively descending the folder tree.void displayNIVFoldersAndFiles(Folder folder) { if (folder.isNew()) { System.out.println("Folder not in view: " + folder.getPath()); } else { System.out.println("Folder: " + folder.getPath()); } // Display not-in-view files in this folder. try { File[] nivFiles = folder.getNotInViewFiles(); for (int i = 0; i < nivFiles.length; i++) { if (nivFiles[i].isNew()) { System.out.println(" " + nivFiles[i].getName() + " is not in view"); } } } catch (IOException ex) { /* Error accessing local files. */ }

// Recurse to call subfolders that don't start with a ".". Folder[] childFolders = folder.getSubFolders(); for (int i = 0; i < childFolders.length; i++) { if (childFolders[i].getName().charAt(0) != '.') { displayNIVFoldersAndFiles(childFolders[i]); } }} // displayNIVFoldersAndFiles

New Event Methods

Update events can now be generated without MPX Java Interface

New event objects FolderUpdateEvent: represents a Folder change ItemUpdateEvent: represents a change to an Item Events are passed old and new objects

New listeners FolderUpdateListener and ItemUpdateListener Register via View.addFolderUpdateListener() and

View.addItemUpdateListener()

Each listener has callbacks for: folder/item added, changed, moved, removed

New Event Methods (cont.)

.Net Interface New event sources

FolderUpdateEventSource delegate ItemUpdateEventSource delegate

Event sources are generated by new View factories View.NewFolderUpdateEventSource() View.NewItemUpdateEventSource()

Each event source has events for: folder/item added, changed, moved, and removed

New update events are triggered by: Local changes: Item.update(), Item.move(), Item.remove() New ViewConfigurationDiffer class New ViewPollingAgent class

New Event Methods: Example// Demonstrate the new non-MPX event methods.void newEventsDemo(Server server) throws IOException { // Create an anonymous class to handle an ItemUpdateEvent. ItemUpdateListener itemCrier = new ItemUpdateListener() { public void itemAdded(ItemUpdateEvent event) { ... } public void itemMoved(ItemUpdateEvent event) { ... } public void itemChanged(ItemUpdateEvent event) { ... } public void itemRemoved(ItemUpdateEvent event) { ... } };

// Open a view and register the listener created above for file changes. View view = findView(server, "StarDraw"); view.addItemUpdateListener(itemCrier, server.typeForName(server.getTypeNames().FILE)); // Now make some changes. Folder rootFolder = view.getRootFolder(); File newFile = new File(rootFolder); newFile.setName("TestFile.txt"); String workfileName = newFile.getFullName(); java.io.File workFile = new java.io.File(workfileName); if (!workFile.exists()) { workFile.createNewFile(); } newFile.update(); Folder srcFolder = StarTeamFinder.findFolder(rootFolder, "Source Code"); newFile.move(srcFolder); newFile.remove();} // newEventsDemo

ViewConfigurationDiffer Example// Demonstrate the new ViewConfigurationDiffer object.void viewConfigDifferDemo(Server server) { // Open the StarDraw main view. View view = findView(server, "StarDraw"); // Create item and folder update listeners (these methods are defined elsewhere). ItemUpdateListener itemCrier = createItemUpdateListener(); FolderUpdateListener folderCrier = createFolderUpdateListener();

// Create a view configuration differ, and register update listeners for all item // types (except Audits) and for folders. ViewConfigurationDiffer viewDiffer = new ViewConfigurationDiffer(view); Type[] types = server.getTypes(); for (int i = 0; i < types.length; i++) { if (types[i].isItemType() && !types[i].getName().equals("Audit")) { viewDiffer.addItemUpdateListener(itemCrier, types[i]); } } view.addFolderUpdateListener(folderCrier); // Create view configuration objects based on the labels "Build 1" and tip. int labelID = findViewLabel(view, "Build 1"); ViewConfiguration config1 = ViewConfiguration.createFromLabel(labelID); ViewConfiguration config2 = ViewConfiguration.createTip();

// Compare the two configurations, which will fire ItemUpdateEvents and // FolderUpdateEvents for differences. viewDiffer.compare(config1, config2);} // viewConfigDifferDemo

ViewPollingAgent Example// Demonstrate the new ViewPollingAgent class.void viewPollingAgentDemo(Server server) { // Open the StarDraw main view. View view = findView(server, "StarDraw"); // Create a ViewPollingAgent object whose first timestamp is "now". OLEDate timestamp = new OLEDate(); ViewPollingAgent viewPoller = new ViewPollingAgent(view, timestamp); // Register item and folder update listeners. ItemUpdateListener itemCrier = createItemUpdateListener(); FolderUpdateListener folderCrier = createFolderUpdateListener(); Type[] types = server.getTypes(); for (int i = 0; i < types.length; i++) { if (types[i].isItemType() && !types[i].getName().equals("Audit")) { viewPoller.addItemUpdateListener(itemCrier, types[i]); } } view.addFolderUpdateListener(folderCrier);

// Ask the user when to take successive snapshots. String prompt = null; do { System.out.println("Last view snapshot taken at: " + timestamp.localString(DateFormat.MEDIUM, DateFormat.MEDIUM)); prompt = prompt("Press Enter for next snapshot; Q to quit"); if (!prompt.regionMatches(true, 0, "q", 0, 1)) { timestamp = viewPoller.refresh(); } } while (!prompt.regionMatches(true, 0, "q", 0, 1));} // viewPollingAgentDemo

Questions?

Contact me at:

randy.guck@borland.com