1. StarTeam SDK New Features  Randy Guck, Chief Scientist, Borland

2. 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

3. 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()

4. 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

5. Auto-logon: Java Example // Demonstrate SDK auto-logon feature void 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...

6. 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

7. 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

8. 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)

9. 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";

10. 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

11. 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-locate coMgr1.setMPXCacheAgentThreadCount(2); // allow two request threads Folder 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-out coMgr1.setCanceled();

12. 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()

13. 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"

14. 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

15. 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.OnStartFile void OnStartFile(CheckoutEventSource source, CheckoutEventArgs args) { System.Console.WriteLine("Starting file: {0}", args.CurrentFile.FullName); } // OnStartFile // Callback for CheckoutEventSource.OnNotifyProgress void 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

16. 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

17. 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);

18. 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

19. 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 statistics CheckoutProgress 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);

20. 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

21. 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...

22. 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

23. 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

24. 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

25. 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

26. 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

27. 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

28. Questions? Contact me at: randy.guck@borland.com