StarTeam SDK Overview Anil Peres-da-Silva Principal Engineer, StarTeam Borland (A Micro Focus Company)

Public Packages Java C# com.starteam StarTeam
com.starteam.viewcomparemerge StarTeam.ViewCompareMerge com.starteam.events StarTeam.Events com.starteam.exceptions StarTeam.Exceptions com.starteam.util StarTeam.Util com.starteam.xml StarTeam.Xml com.starteam.diff StarTeam.Diff

Public Packages Languages & Runtimes Java (JRE); C# (.NET)
The SDK is available in Java & C#. The C# version of the SDK is functionally identical to the Java version. As per C# conventions, the namespace name is StarTeam. Names are capitalized & Java get/set accessors become C# properties. e.g. (Java) int s.getPort()  (C#) int s.Port Developed using JDK 1.2-, cross-compiled into J#; a small set (+/-20) of language specific java/j# edge classes J# assembly further wrapped in an external C# assembly, generated using meta data reflection Custom Java applications that do not care about SDK type specific exceptions can ignore the com.starteam.exceptions namespace, and catch java.lang.RuntimeException, Exception or Throwable Similarly, custom C# applications can catch System.Exception Custom applications that do not care about events can ignore the events namespace. However, MPX aware applications reduce server commands. COM is no longer supported. Application developers can use StarTeamSDK11.0.dll, our last shipping COM release, which is backward compatible to 2005 servers and forward compatible to the 12.5 server

Public Packages (C# SDK, .NET 4.0 & VS 2010)
The SDK C# solution StarTeam.dll depends upon the StarTeam J# assembly (StarTeam.Core.dll) which in turn depends upon the Microsoft .NET 2.0 native .J# assemblies, vjslib.dll & vjsnativ.dll. They can be downloaded from (32) (64) The .NET 4.0 runtime does not load .NET 2.0 assemblies. Application developers need to assume this responsibility themselves. There are a few issues you may run into when using VS2010. If you are developing a Windows Forms Application, the default Project Setting for the Target Framework is '.NET Framework 4 Client Profile'. Attempting to compile your code with this setting returns the following warning Warning The referenced assembly “…" could not be resolved because it has a dependency on "System.Web, …" which is not in the currently targeted framework ".NETFramework,Version=v4.0,Profile=Client". Please remove references to assemblies not in the targeted framework or consider retargeting your project. & error Error The type or namespace name 'StarTeam' could not be found (are you missing a using directive or an assembly reference?) To address this, you must change the Target Framework setting to '.NET Framework 4' and rebuild

Public Packages (C# SDK, .NET 4.0 & VS 2010)
Your 32 bit application code (whether Windows Forms or ASP.NET) must load the vjsnativ & vjslib assembly .dll's. 1) include the assembly System.Runtime.InteropServices; 2) explicitly declare & load the assemblies (keep them loaded for the life of your application) [DllImport("kernel32.dll")] private extern static IntPtr LoadLibrary(string fileName); [DllImport("kernel32.dll")] private extern static bool FreeLibrary(IntPtr lib); string folder = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.System), @"..\Microsoft.NET\Framework\v "); folder = Path.GetFullPath(folder); IntPtr ptr1 = LoadLibrary(Path.Combine(folder, “vjslib.dll"); IntPtr ptr2 = LoadLibrary(Path.Combine(folder, “vjsnativ.dll"); then instantiate & use the StarTeam objects Server s = new Server("localhost", 49201); s.LogOn("Administrator", "Administrator"); … You may choose to free the loaded libraries when your application is shutting down FreeLibrary(ptr1); FreeLibrary(ptr2);

Object Model Grouped classes with common functionality; Reduced ‘clutter’ in com.starteam Java implementation compiled using JDK 1.5 but constrained to JDK 1.2- api’s (for J#.NET); client application developers have no such constraint Encapsulation Techniques: Tight Binding & Close Coupling example Typed Resource is the base of all StarTeam Artifacts; Type is the base of all StarTeam types Every Typed Resource has a unique Type Items & Projects are both TypedResources; An ItemType is not a ProjectType Alternatives development approaches :- ItemType.java, ProjectType.java (weak coupling between Item & it’s Type) – the separate classes approach Item.Type, Project.Type (strong coupling between Item & its Type) – the public static class approach Consistency & Strong Typing. The ‘objects everywhere’ approach

Object Model Consistency & Strong Typing Objects v/s Strings
Names are user friendly properties, not representations of SDK Objects. Example – Folder.countItems(String typeName, int depth) (com.starbase.starteam) Folder.countItems(Type t, int depth) (com.starteam) Objects v/s Integers Integer IDs are internal keys, not representations of SDK Objects. Example ACLEntry.addPermission(int permissionID) (com.starbase.starteam) ACE.addPermission(Permission p) (com.starteam)

Object Model Objects v/s Static Integer Constants Example
public static final int Label.NEXT_BULD_ID; (com.starbase.starteam) public static final Label Label.NEXT_BUILD; (com.starteam) Objects v/s Grouped Static Integer Constants public class ProductCodes { (com.starbase.starteam) public static final int STANDARD; public static final int ENTERPRISE; public static final class Server.ProductCode { (com.starteam) public static final ProductCode STANDARD; public static final ProductCode ENTERPRISE;

Object Model Typed Resource is the base class for all StarTeam Artifacts Type is the base class for all StarTeam types Each Typed Resource has a unique Type; each Type has a unique Property Collection which derives from the underlying type’s property collection. SDK Objects have properties, methods, events Properties may be primitives (String, int, boolean, double), SDK Objects, arrays of primitives or arrays of SDK Objects Properties may be specialized SDK Collections (themselves SDK Objects) Method arguments and return types may be primitives, SDK Objects, arrays or SDK Collections Event arguments may be primitives, SDK Objects, arrays or SDK Collections Custom component application developers may choose to sub-class Item or Tree Item directly Types may be customized; custom properties can be added to stock or custom components The new SDK Object model closely mirrors the Server Object Model.

Object Model (Artifact Hierarchy)

Object Model (Type Hierarchy)

Object Model (Property Hierarchy)

Object Model (PropertyCollection Hierarchy)

Server, MPX & CacheAgent
import com.starteam.*; An application must connect to the StarTeam Server before it can do anything else Server s = new Server(“localhost”, 49201); User u = s.logon(“Administrator”, “Administrator”); // is equivalent to s.getLoggedInUser() if (s.isMPXAvailable()) s.enableMPX(); // MPX aware applications minimize server commands. Updates are pushed to the client CacheAgent ca = s.locateCacheAgent(“localhost”, 5101); // OR ca = s.autoLocateCacheAgent(); s.disconnect(); // automatically disables MPX, if s.disableMPX(); Once a Cache Agent is located, the SDK automatically fetches File Content from the Cache Agent if available. see {Root/Remote}CacheAgentConfig.xml in your Cache Agent install folder Commands issued on a server instance are throttled through a single socket. (But multiple server instances can be used to form a connection pool, which is the basis for the web framework)

Server, MPX & CacheAgent
MPX is a framework for publish/subscribe messaging. The StarTeamMPX Server uses an advanced caching and communication technology that both improves the performance of StarTeam clients and extends the scalability of the StarTeam Server. StarTeamMPX benefits StarTeam SDK applications in two important ways: Instant Refresh. An MPX-enabled SDK application can refresh changes from the server with very little overhead. For applications that perform frequent refresh operations, the resulting performance benefits are significant. Event-Handling. An MPX-enabled SDK application can subscribe to specific server events (for example an Item is added, modified or deleted), and provide event-handlers that are invoked when those events occur. When MPX is enabled, the SDK establishes a connection to the StarTeamMPX message broker, and subscribes to events for this server. Even though MPX is enabled through a specific Server object, it is really the communication layer between the SDK and the StarTeam repository that is MPX-enabled. Thus, enabling MPX on a specific Server object also enables MPX for other Server objects in the same runtime that share the same address and port.

Types & Properties // TypeCollection extends StarTeamCollection implements java.util.Collection // StarTeamCollection is a type safe abstract base class for all SDK collections TypeCollection tc = (Server) s.getTypes(); Type[] tt = (Type[])tc.toArray(new Type[tc.size()]); for (int i = 0; i < tt.length; i++) { Type t = tt[i]; // && access the properties for a give Type t PropertyCollection pc = t.getProperties(); Property[] pp = (Property[])pc.toArray(new Property[pc.size()]); } // OR find a Type by it’s name, useful for custom component developers. Custom Components are new to12.0 Story.Type t = (Story.Type)tc.find(“Story”); //The 12.0 Server supports creation of custom types (components) via the SDK. @see Server.createType(String xmlDefinition);

Types & Properties Type.newXXXProperty(…) api’s are used to create/add Custom Properties to any Item derived Type The StarTeam Server supports creation of all Property Types except Link and Binary Properties The 12.0 Server Release introduces three new property types; ContentProperty, MapProperty & Multi-Select Enumerations. It also supports the creation of custom Object and ObjectArray properties - which store User(s) or Group(s) values; and custom Date (without a time component) properties Content Property types store arbitrary binary, rich text, html, .pdf etc. content in the StarTeam & Cache Agent Vaults. Just like File Content, Content Property Values are retrieved either from the server or the closest cache agent. Map Property types serialize Maps (Hash Sets) of arbitrary key-value pairs to the StarTeam database Maps can be queried using new Query Relations (CONTAINS_KEY, CONTAINS_VALUE & KEY_CONTAINS_VALUE) The Map Property supports the native value types String, Integer, Long, Boolean, Double, Float and Date. In addition, it supports the SDK types Date, DateTime, MD5, GUID, DotNotation, TimeSpan and Content Multi-Select Enumerations allow more than 1 Enumerated Value to be selected, stored & retrieved.

Types & Properties Property p = t.newDoubleProperty(“CostPrice”); Create custom properties for a given Type t p.update(); // issue the server command, and creates the property on the server p = t.getProperties().find(“Usr_CostPrice”); // the server automatically prefixes Usr_ to the name Type & Property creation can be slow, and can adversely affect connected users Types have associated metadata (properties) t.isBranchable(); // Tree Item types are NOT branchable t.isComponentType(); // Files, Folders, ChangeRequests, Custom Components are all component types The 12.0 server supports modifying the Type display name & Translations for all Item derived Types. Properties have associated metadata p.isClientCalculated(); // Client side property whose value is calculated on the fly p.isServerCalculated(); // Server side property whose value is calculated on the p.isStored() p.isRevisionIndependent(); // Server property whose value is fixed across all revisions

Projects, Views, Folders & Items
Project[] pp = s.getProjects(); Project p = s.findProject(“StarDraw”); // A server manages multiple projects View[] vv = p.getView(); View v = p.findView(“Release 1.0 Maintenance”); // a project can contain multiple views // The root or default view of a project has a special accessor p.getDefaultView() View[] vv = v.getDerivedViews(); // Views can be arranged in trees Folder f = v.getRootFolder(); // every view has a default root folder created by the server Folder[] kids = f.getSubFolders(); // Folders can be arranged in trees Projects, View and Folders form a containment hierarchy. Items are contained in Folders, and can be accessed from the parent folder or the view. Item.Type cstmTyp = s.getTypes().find(“Visualization”); // Item.Type extends com.starteam.Type v.findItem(cstmTyp, -1); // load all item id’s of a given type in a single server command ViewMemberCollection vmc = f.getItems(cstmTyp); // gather the entire set of items in a specific folder ViewMemberCollection vmc = f.getView().getViewMembers(cstmTyp); // gather the entire set of items in the view Item itm = v.findItem(cstmTyp, 145); // find a specific item by ID (IDs are unique server wide)

Items & View Members ViewMembers are artifacts that reside ‘in a view’, (technically, in the default root folder of the view) Non-Item View Members do not have a parent folder property Change Packages & Traces are view members, not items. They do not reside in parent folders. Stock & Custom Components are Items. Items are View Members that reside in a parent folder in the view. By definition, component instances are contained in their parent folder and contained in their view. Tree Items are Items that have parent child relationships. An entire tree must reside in a single folder – but different trees may reside in the same or different folders. By default (i.e. out of the box) Custom Component Types are surfaced as Item or TreeItem instances. Client application developers may choose to extend the SDK object model in their own namespace and have their {Tree}Item derived classes become first class SDK citizens!

Items & ViewMembers Every view member has a type, which in turn has a collection of properties. At runtime, the values of the properties of view member instances can be retrieved or changed generically Object o = itm.getValue(Property); // return the value of this property for this item instance Object itm.setValue(Property, Object); // set the value of this property, return the previous value itm.update(); // persists this item in its new state on the server. The in memory item is no longer dirty Stock component types also have type safe accessors that supplement the generic get/set Value api’s When an item is updated more than once, the history of all changes can be queried ViewMemberCollection history = item.getHistory(); // the first entry in the collection is the tip Item instances may be shared across folders and views. A share tree represents the class of items with the same root Item shr = itm.shareTo(f); // share this item to a different folder, return the newly created share The specified folder may be in the same view or a different view of this project, Items cannot be shared across servers. Share[] ss = itm.getAllShares(); // returns the share tree of this item, which may be walked recursively

Items & ViewMembers for all the stock item types, each generic get/set accessor typically has equivalent type specific accessors boolean b = ((Boolean)itm.getValue(pc.find(ViewMember.Type.IsReadOnlyProperty.NAME))).booleanValue(); // is equivalent to boolean b = itm.isReadOnly(); // a read-write property example Requirement.Type rqmtTyp = s.getTypes().REQUIREMENT; Requirement r = (Requirement)v.findItem(rqmtTyp, 12345); Requirement.Type.PropertyCollection pc = r.getProperties(); int ambiguities = r.getAmbiguitiesCount(); // is equivalent to… ambiguities = ((Integer)r.getValue(pc.AMBIGUITIES_COUNT)).intValue(); r.setAmbiguitiesCount(ambiguities); // is equivalent to… r.setValue(pc.AMBIGUITIES_COUNT, new Integer(ambiguities)); pc.AMBIGUITIES_COUNT is equivalent to pc.find(Requirement.Type.AmbiguitiesCountProperty.NAME) There is typically more than one way to do the same thing through the SDK. Pick the model that suits you best.

Folders & Items Folders are Items. Folders are also containers for items. A folder can have at most one parent folder, bur multiple child folders. An item can have at most one parent folder. Related Tree Items, i.e. parents, children, descendants, can be contained in at most one folder. f.populate(cstmTyp, pc, depth); // ensures that the set of items specified by this type and depth are populated with the set of properties specified in the property collection. The property values need not be up to date over time. f.refreshItems(cstmTyp, pc, depth); // ensures that the set of items specified by this type and depth are populated with the set of properties specified in the property collection and are kept up to date. If MPX is enabled, refresh will not Issue a server command. Without MPX, a server command to re-fetch properties is triggered, whether or not they are up to date. boolean f.isRefreshItemsRequired(cstmTyp, pc, depth); // tests whether property values are up to date. MPX enabled applications will only return true if an in-memory refresh is required. This method always returns true for applications that are not MPX enabled. boolean f.isPopulated(cstmTyp) will return true iff all the items of this type in this folder have all properties populated..

Collections Public abstract base class StarTeamCollection
In Java, implements java.util.Collection In C#, implements System.Collections.IList Assignable member type safety enforced Collections returned through SDK Interfaces are immutable & read-only, i.e. members cannot be added or removed, e.g. Server.getTypes() a read-only collection of server supported types . Type.getProperties() a read-only collection of type specific properties Newly created collections are write-able by default new PropertyCollection(), new ViewMemberCollection() return empty, mutable collections Application developers can ‘roll their own’ collections by sub-classing StarTeamCollection

Collections

ViewMemberCollection
A managed collection of ViewMember instances spanning project(s) or view(s) across a server provides several methods with bulk implementations, minimizing network round trips i.e. one command issued (per type, per view) for the entire set of ViewMembers in the collection ViewMemberCollection vmc = new ViewMemberCollection(); // collect items as necessary from different projects or views or folders across the server vmc.addAll(s.findProject(“StarDraw”).getDefaultView().getRootFolder().getItems(cstmTyp)); vmc.addAll(s.findProject(“StarDraw”).findView(“Release 1.0 Maintenance”).getRootFolder().getItems(cstmTyp)); PropertyCollection pc = new PropertyCollection(); pc.add(cstmTyp.getProperties().find(ViewMember.Type.ItemDeletedByProperty.NAME); // a stock property pc.add(cstmTyp.getProperties().find(“Usr_CostPrice”); // a custom property vmc.getCache().populate(pc); // populate all items in this collection with the property values specified ViewMemberCollection hstry = vmc.getFromHistory(new DateTime(2009, 00, 01)); // return all historical revisions of these view members as of the specified date (this may be a smaller set, since some of these items may not have existed on that day and at that time)

ViewMemberCollection
HistoryContainer hc = vmc.getHistory(); // return all historical revisions of all the ViewMembers in the collection // to access the history of an individual view member, query the HistoryContainer for that one ViewMemberCollection hstry = hc.getHistory(vmc.getAt(0)); // the history of the zero-th ViewMember // History is the set of all revisions of an item from the tip (0th) to the oldest (nth) instance vmc.lockExclusive(true); // exclusively lock all the members of this collection (break another users lock), or unlock() BehaviorContainer bc = vmc.getViewMemberBehavior(); // return the behavior of all view members in this collection; (Behavior describes the branching or floating characteristic) // to access the behavior of an individual view member, query the BehaviorContainer for that one ViewMemberBehavior vmb = bc.getBehavior(vmc.getAt(0)); // Similarly, create and use a BehaviorContainer to change the behavior of a set of ViewMembers in bulk; // using the fewest set of server commands. Once items are in the view member collection, they can be searched for by itemid or ‘name’, the name being the value of the Primary Descriptor vmc.find(int)

TypeCollection A managed collection of all Types surfaced by the Server. This includes types for custom components created by application developers, at server startup or on the fly. The server wide type collection is obtained by querying the server object after TypeCollection Server.getTypes(); Types may be iterated over or found by id (int) or name (string); i.e. Server s = new Server(“host”, port); … TypeCollection tc = s.getTypes(); tc.PROJECT is equivalent to tc.find(Project.Type.NAME) is equivalent to tc.find(tc.PROJECT.getID()); Each system defined type is declared as a public property on the TypeCollection. for example, TypeCollection.PROJECT, TypeCollection.FILE Custom types (created at runtime) may be found by name (preferably, since the name is assigned by the component developer) or integer id (assigned by the server when the type is created).

PropertyCollection A managed collection of all Properties surfaced by the Server for a given Type. This includes types for custom components created by application developers, at server startup or on the fly. A property collection is obtained as a query on a PropertyCollection Type.getProperties(); Properties may be iterated over or found by id (int) or name (string); PropertyCollection.find(int), PropertyCollection.find(String) Each SDK Type defines a PropertyCollection that extends the base class PropertyCollection, and provides accessors for individual properties injected by that type. for example, File.Type.PropertyCollection.HIVE is equivalent to File.Type.PropertyCollection.find(File.Type.HiveProperty.NAME) Custom properties can be found by name (the server appends Usr_ to the name of custom properties created through the SDK) or by ID (a unique integer value assigned by the server when the property is created)

Populating Item Properties
If the property value of an item instance is not available in memory, querying for that value issues a server call Well behaved applications pre-populate the properties they care about, on the items they care about, early. The SDK can populate a set of requested properties for a given set of items in a single ‘bulk’ server command PropertyCollection pc = new PropertyCollection(); pc.add(cstmTyp.getProperties().find(ViewMember.Type.ItemDeletedByProperty.NAME); // a stock property pc.add(cstmTyp.getProperties().find(“Usr_CostPrice”); // a custom property f.populate(cstmTyp, pc, /*depth=*/ 0); // populate all items // depth = 0  in this folder only // depth = 1  this folder & its subfolders, etc; depth = -1  recurse entire folder tree from this folder down ViewMemberCollection vmc = f.getItems(cstmTyp); for (int i = 0; i < vmc.getSize(); i++) { ViewMember mbr = (ViewMember)vmc.getAt(i); User u = mbr.getDeletedBy(); // this property value is now in memory double dbl = ((Double)mbr.getValue(cstmTyp.getProperties().find(“Usr_CostPrice”))).doubleValue(); // and so is this boolean b = mbr.isReadOnly(); // but this one is NOT & triggers a separate cross network server command per item! Poor application performance, increased network traffic, decreased server scalability } // To conserve memory, discard cached data when ViewMember.getCacheService().discard();

NetMonitor & ServerCommandListener
// an interface through which server command notifications are fired // useful for debugging, identifying unnecessary server commands and optimizing client-server traffic in SDK applications class SrvrCmdLstnr implements ServerCommandListener { public void onStart(ServerCommandEvent e) { System.out.println(e.isPropertyFetchTrigered()); System.out.println(e.getCommandName()); } SrvrCmdLstnr scl = new SrvrCmdLstnr(); // // when writing & testing code, put this in a DEBUG section NetMonitor.addServerCommandListener(scl); // the listener gets notified when the command starts and ends … boolean b = mbr.isReadOnly(); // from the earlier example, isPropertyFetchTriggered() will print true in the listener NetMonitor.removeServerCommandListener(scl); // always remove the listener when done

Users & Groups Given a logged in Server Object s, load Users & Groups from the server. Full user & group information is not retrieved, since the user logging in may not have administrative privileges to access full account information of other users. A logged in user with full administrative privileges can retrieve fully loaded users & groups through ServerAdministration. A user may belong to multiple (un)related groups User[] uu = s.getActiveUsers(); // s.getUsers() includes deleted users Group[] gg = s.getActiveGroups(); // s.getGroups() includes deleted groups User u = s.getLoggedInUser(); // the user who logged into this session for (int i = 0; i < gg.length; i++) { Group[] ss = gg[i].getSubGroups(); // subgroups of this group; a group may have only one parent User[] mm = gg[i].fetchMembers(/*descendants=*/ false); // the set of users who are members of this group // true to retrieve the entire set of Users who are members of this group and all its descendants } Groups are MPX enabled from refreshUsers(); refreshGroups(); User Group membership (relationship) queries are bulkified from servers

Filters A Filter is a user definable ordered & grouped collection of Properties Type cstmTyp = s.getTypes().find(“Visualization”); Filter[] ff = cstmType.getFilters(); // Load Filters for a specific Type Filter l = cstmType.getFilter(“<Must Fix CRs>”); // find a filter by Name Filter l = cstmTyp.getFilter(12345): // find a filter by ID ( a server wide unique integer) cstmTyp.refreshFiltersAndQueries(); // ensures an up to date list of Filters and Queries is available. for (int i = 0; i < ff.length; i++) { Filter l = ff[i]; Filter.Column[] cc = l.getColumns(); // the set of properties comprising this filter, in columnar order Filter.Grouping[] gg = l.getGroupings(); // the subset of properties used for sorting or grouping }

Queries A Query is a user definable condition that may be applied to select a subset of Items for a given Type A query is constructed from a QueryNode, which recursively comprises QueryNodes, QueryParts & Relations. Typically the Cross Platform Client (CPC) is best used to construct Queries Type cstmTyp = s.getTypes().find(“Visualization”); Query[] qq = cstmTyp.getQueries(); // Load Queries for a specific Type Query q = cstmType.getQuery(“By Status And Responsibility”); // // find a query by Name Query q = cstmTyp.getQuery(12345): // find a filter or a query by ID PropertyCollection pc = q.getProperties(); // the set of properties described by this query’ QueryNodes & QueryParts Item itm = v.findItem(cstmType, /*ID=*/ ); boolean b = q.evaluate(null, itm); // evaluate the query; returns true if the query includes (selects) this item QueryNode qn = q.getQueryNode(); QueryNode[] nn = qn.getQueryNodes(); // the set of QueryNodes that belong to ‘this’ Query Node QueryPart[] pp = qn.getQueryParts(); // the set of QueryParts that belong to ‘this QueryNode

ViewMemberRevision ViewMemberRevision’s are created when one modifies the view level properties of the item. These property modifications include 1) Changing the Item Branching Behavior 2) Changing the Item Configuration 3) Branching the Item 4) Moving the Item To access a ViewMemberRevision array, use the api ViewMember::getViewMemberRevisions(); The api returns revisions ordered from most recent (first) to least recent (last) Walk this array to discover when an item has moved. (a common use case). The ParentFolderItemID property of a ViewMemberRevision will have changed between two back to back revisions, signifying a move. If the ViewID property has also changed, then the move is a cross view move. Walk the array to discover other property modifications as well, even though these may be less common use cases.

Share Shares are created when you share an item across folders (The folder may belong to the .same or a different Item.shareTo(Folder), Item.reverseShareTo(Folder), Trace.shareTo(View) A reverse share is prefered when the direction of the share is opposite to the direction of the share tree, i.e. when ‘sharing’ an item from a child view to its parent view, using a reverse share ensures that the resultant share tree follows the direction of the view Share[] ViewMember.getAllShares() to query the share tree of an item or view Share ViewMember.getShare() to query the single share that represents ‘this’ item or view member in its tree. A Share has a Parent Share (may be null for the root share) and a set of child shares (which may be empty) ViewMember’s with the same root object ID are all members of the same share tree. They may reside in different folders in the same or different views. Shares may have different object ids, which represent their depth in the share tree. Items whose ‘parent share’ have the same object id are all at the same level in the share tree. Note that ChangePackages cannot be shared across views. However, they can be replayed, which results in the creation of a new change package in the target view, and shares of the contained items that represent the differences.

Labels A named configuration of ViewMember instances. Labels may be applied to an entire view (View Labels) or to individual Item revisions in a View (Revision Labels) View v = s.findProject(“StarDraw”).getDefaultView(); Label l = v.createViewLabel(“label name”, “description”, DateTime.CURRENT_SERVER_TIME, /*buildLabel=*/ true, /*frozen=*/ false); // a build label set to the current server time Label l = v.createRevisionLabel(“label name”, “description”, /*frozen=*/ false); // a revision label ViewMemberCollection vmc = new ViewMemberCollection(); vmc.addAll(v.getRootFolder().getItems(cstmTyp); l.attachTo(vmc); // attach all the members of the collection to this label; (these members are from the tip configuration) vmc = vmc.getFromHistory(new DateTime(2009, 0, 1)); // get all historical revisions on 1/1/2009 l.attachTo(vmc); // attach historical revisions to the label

Labels l.detachFrom(vmc); // detach the label from the members of the collection ViewMemberCollection vmcEx = l.getLabeledItems(vmc); // returns the (sub)set of items in this collection which have label l attached to them There is no direct way to query a label for the set of items (at the specific revisions) which are attached to it. Currently, an application needs to fetch all the id’s of any items it is interested View.findItem(Type, -1) find the subset which has some revision attached to the Label.getLabeledItems(ViewMemberCollection) and then query for the actual ViewMemberCollection.getFromHistory(Label) which is a bulk query from StarTeam 12.0 Alternatively, an application may open a view (using a label based configuration) find the items, process them, and close the View(ViewConfiguration) Note that opening a view is a fairly expensive operation on the StarTeam server

Traces A strongly typed bi-directional relationship between two artifacts. Traces can be created across views, projects and even servers. Traces may be stored in any view on the source or target server, or in a view on an entirely different Server. Traces may be created between StarTeam artifacts and non StarTeam artifacts (e.g. an HTTP URL) Traces are ViewMembers, and consequently, may be branched, versioned or shared. However, unlike Items, Traces are not stored in Folders. Traces are created by VCM, and by Checkin Manager, between the ChangePackage and any Process Item(s) in Scope. These Traces are created in the same view as the ChangePackage. Unlike links, traces have history which may be queried. A historical revision may be pinned to different source or target revisions or may float. Trace t = new Trace(view); t.setSource(view.findItem(cstmTyp, 12345)); t.setTarget(view.findItem(rqrmntTyp, 67890)); // or alternatively t.setTarget(LinkValue.forURL(“ t.unpinTarget(); // the Trace floats at the tip revision of the target t.update(); TraceCollection trc = view.getTraces(); // query all the traces in a view TraceCollection trc = trc.getTraces(view.findItem(cstmTyp, 12345)); // find the subset of traces that reference this item Traces subsume StarTeam links.

Change Packages A set of changes comprising a single logical Change
Committed in a single atomic transaction Created by a VCM session (Promote, Rebase, replicate) in the target view For each change, record the source & the target revisions at the transaction commit time Created by Checkin Manager Record newly added files & folders, changed, deleted or moved files. Source & target revision are from the same view, the change records the pre commit and the commit(ted) revisions ChangePackage APIs query for ChangeCollection, Source View, Target View and Transaction properties. All these properties are read-only. ChangePacakges may be replayed from one view to another within a project. ChangePackages provide a valuable audit trail of file checkin changes & deltas

Attachments Attachments are named Content values stored by the StarTeam Server per artifact Each artifact instance has an implicit associated Attachment ‘Property’. Files & Folders do not subscribe to the Attachment Service. All other ViewMember & Custom Component Types do The server can store up to 64 attachments per artifact instance. The 11.0 server stores attachments in a private folder managed by the server. The 12.0 server stores attachments in the StarTeam vault, keyed by MD5, along with File & Content Values. (eliminates duplication, orphans can be pruned, fits existing vault back up startegies, etc) The SDK exposes Attachments as a Content[]. Each Content object has a unique integer ID, a Name & an MD5. Content[] ViewMember.getAttachments(). The Attachment Content (data payload) itself is fetched by calling the toBytes(), toFile(), toStream() or toString() api’s on the Content object from the array. ViewMember.setAttachments(Content[]) saves the Attachments to the server, and updates the internal state with the new Attachment Names, IDs and MD5s.

Impersonation Enable User Impersonation via a single connected Server Instance (useful for developing web applications, Import Export algorithms, etc.) User admin = s.getLoggedInUser(); // the original logged in User ImpersonateUser iu = new ImpersonateUser(s); iu.enableImpersonation(); // once enabled, impersonation cannot be disabled User u = s.logon(“anotherUser”, “password”); // The StarTeam server does NOT support logging off a User iu.switchContext(u); // subsequent commands are executed in this user context iu.switchContext(admin); // until you switch back to a different user, OR alternatively, use iu.setCommandUser(other); // unlike switchContext(), the other user need NOT have been logged in via this server instance; but subsequent commands are executed in his/her context at the appropriate privilege level com.starteam.util.DateTime dt = new DateTime(2010, /*January*/ 0, 1); iu.setCommandTime(dt); // overrides current server time, sets the ‘execution time’ for all subsequent commands iu.setCommandTime(DateTime.CURRENT_SERVER_TIME); // reset to use server time from here on out

Access Rights & Permissions
StarTeam supports Server wide, view specific, container (project, view & folder) level & individual item permissions. Supported permissions are described in Permission & aggregated in PermissionCollection (a StarTeamCollection) All StarTeam SDK components (including containers like view & folder) implement the ISecurable interface. Folders, Projects & Views implement the ISecurableContainer interface Securable Object instances may be assigned a collection of Access Control Entries (ACE’s) Each ACE is a collection of Permissions that may be assigned to a Securable in the context of a User or Group. A common misconception is that denying access to a user (or group) is sufficient – that everyone else (or the Administrator or the Administrators Group) automatically has access to the object. This is the source of most pitfalls when using the security model. An ACE must be explicitly granted access to those who require it and denied access to those who do not. Securable Object instances may be queried for permissions granted to the currently logged in user. Similarly, Securable Containers may be queried for permissions granted or denied to the currently logged in user for all objects of a given type. Against servers, getRights will not issue a server command if MPX is enabled.

AccessRightsManager A dynamic managed collection of access rights for a set of Securable Objects and Containers across a server AccessRightsManager arm = new AccessRightsManager(s); // create an Access Rights Manager for a given server ViewMember[] vmb = view.getRootFolder().getItems(cstmType, 0); arm.populate(ISecurable[] {vmb[0], vmb[1], …}); // load and manage access rights for the specified collection of securable object instances; all access rights queries are bulkified from servers arm.populate(new ISecurableContainer[] {view.getRootFolder()}, cstmTyp); // load and manage the access rights for instances of the custom Type contained within the root folder of the view ACE[] aces = arm.getRights(vmb[0]); // the access control list for this securable instance PermissionCollection pc = new PermissionCollection(); pc.add(Permission.GENERIC_SEE_OBJECT); pc.add(Permission.GENERIC_MODIFY_OBJECT); boolean b = arm.isAccessGranted(s.getLoggedInUser(), pc, vmb[0]); // does the logged in user have the right to see or modify the specified securable object instance? arm.refresh(); // discard & re-populate cached Access Rights Information for all managed Objects & Containers. // Optimized NOT to issue server commands against servers with MPX enabled

FolderListManager & ViewMemberListManager
A managed dynamic collection of Folders created by including &/or excluding selected folders &/or their sub-folders FolderListManager flm = new FolderListManager(view); // create a Manager in a specific view context flm.includeFolders(view.getRootFolder(), Filter.Context.SERVER, /*depth=*/ -1); // exclude an entire branch of the tree using flm.excludeFolders(…) ViewMemberCollection ff = flm.getFolders(); // the flattened set of Folders being managed by this collection flm.refresh(); // ensure that the list is up to date. If MPX is enabled, refresh() may not issue any server commands A managed dynamic collection of Items of type cstmTyp, contained in the folders specified by the FolderListManager ViewMemberListManager vmlm = new ViewMemberListManager(cstmTyp, flm); Once the collection is built up, it can be queried in different ways ViewMemberCollection vmc = vmlm.getViewMembers(); // return all the members of this collection vmc = vmlm.selectBy(cstmTyp.getQuery(“By Status And Responsibility”)); // return those members of this collection that satisfy the constraints imposed by the selected query vmc = vmlm.selectBy(Label“xxx”); // return those members of the collection attached to the label ViewMemberListManager now supports non item ViewMembers, i.e. ChangePackages, Traces

ViewConfigurationDiffer & ViewPollingAgent
ViewConfigurationDiffer is used to compare two configurations of a given view, triggering Item, Folder and ViewMember Update Events, describing the changes detected between the two configurations. ViewPollingAgent is used to periodically poll a given view for recent changes, triggering Item, Folder and ViewMember Update Events describing the changes detected since the last poll. With this release of the SDK, both ViewConfigurationDiffer and ViewPollingAgent supports event notification for non item ViewMembers, i.e. ChangePackages and Traces. The two algorithms also support event notification for custom components. However, both these algorithms are memory intensive. A lightweight MPX listener, also new to this release of the SDK, may be a preferable alternative.

ViewConfiguration Used to open rolled back (i.e. snapshots from history) views View v = s.findProject(“StarDraw”).getDefaultView(); // the ‘tip’ or current configuration of the view Label[] ll = v.getActivelabels(); v = new View(v, ViewConfiguration.createFrom(new DateTime(2009, 00, 01)); // rolled back to Jan 01, 2009 v = new View(v, ViewConfiguration.createFrom(ll[0]); // rolled back to the label; i.e. the exact moment in server history when the label was created v = new View(v, ViewConfiguration.createTip()); // revert back to the tip or current configuration Opening a rolled back view is expensive. Resources are allocated on the server and retained in the server cache until the view is closed. Rolled back views represent snapshots from history. New items cannot be added to a rolled back view. Existing items cannot be modified or deleted. Rolled back views are used extensively in View Compare Merge (VCM) to pick a fixed point in time at which the compare is executed, so as not to be influenced by subsequent changes to the tip.

Recycle Bin A recycle bin is a view that provides access to deleted items & deleted folders In addition to the standard view api’s, the RecycleBin exposes properties which allow applications to control the classes of active or deleted items that the RecycleBin should surface. RecycleBin r = view.getRecycleBin(); r.setIncldeActiveItems(true); // Active items are excluded by default r.setIncludeDeletedItems(true); // Deleted items are included by default r.setIncludeDeletedFolders(true); // Deleted folders are included by default r.setDeletedAsOf(new DateTime(2009/00/01)); // include everything deleted since Jan 01, 2009 // now, surface all active & deleted items in the root Item.isDeleted() Item[] all = r.getRootFolder().getItems(cstmTyp); The RecycleBin is extensively used in VCM to identify ItemDifferences like ‘Deleted in {Source | Target}’ Note that deleted items are no longer available once a view has been purged.

Application The context of a client application. Creating a Server instance creates a default application instance Alternatively, create an Application instance, and one or more servers in its context. Particularly useful for creation and resolution of cross server Traces, federating trace servers, etc. Application a = new Application(“MicroFocus Team Management”); Server s1 = a.newServer(“changeRequestServer.mydomain.com”, 49201); s1.logon(…); Server s2 = a.newServer(“sctmServer.mydomain.com”, 60000) ; s2.logon(…); Server s3 = a.newServer(“traceServer.mydomain.com”, 2000) ; s3.logon(…); // find a change request in s1, a test in s2 & create a Trace between the two, store it in s3 Trace t = new Trace(s1.findProject(“FederatedTraces”).getDefaultView()); t.setSource(s1.findProject(“Defects”).getDefaultView().find(s1.getTypes().CHANGE_REQUEST, 1234)); t.setTarget(s2.findProject(“SilkCentral”).getDefaultView().find(s2.getTypes().find(“Test”), 5678)); t.update();

Application Application is also useful for resolving StarTeam Objects to URLs and URLs to Objects String url = a.toStarTeamURL(t); // save the url on your desktop, it to a colleague, etc. Trace tt = (Trace)a.resolve(url); assertTrue(t.equals(tt)); // verify that t is tt StarTeam URL’s are well formed URI’s with a formal grammar. StarTeam URLs use ID or NAME schemes starteam://localhost:49201/0;ns=Project;scheme=id/0;ns=View;scheme=id/197;ns=File;scheme=id;scope=full starteam://be5ee3b0-c719-49c6-a1a1-f493764a03f5;id=guid/0;ns=Project;scheme=id/0;ns=View;scheme=id/197;ns=File;scheme=id;scope=full starteam://localhost:49201/Project_12926ffd7de/Project_12926ffd7de/Folder_ApplicationTest.testResolveURLS_12926ffd7df/Folder_ApplicationTest.testResolveURLS_12926ffd7e0/File_ApplicationTest.testResolveURLS_12926ffd7e1.txt // NAME based URIs are best avoided; they are case sensitive, unwieldy, and not guaranteed to be unique

Workflow StarTeam Workflow specifies a set of type specific rules, states & state transitions, which are described in XML files in the StarFlow extensions project. The xml files are created using Workflow Designer. The workflow engine triggers the rules & validates the state transitions when attempting to update an item of the specified type. Application developers can turn on the workflow engine using the static api Workflow.fromStarFlowExtensions(View) which queries the starflow extensions project for the workflow, loads it up into memory & attaches it to the respective workflow aware types. An application can also directly load workflow from an .xml file produced by Workflow designer using any of the three fromFile({Server|Project|View}, java.io.File) api’s. Once enabled, workflow cannot be disabled for the life of the application. An application may choose to verify that a workflow step will succeed, i.e. an artifact can be updated in a given Workflow.canUpdate(TypedResource). If a workflow enabled application attempts to update an artifact but canUpdate() returns false, an SDK Runtime Exception will be thrown.

Events Asynchronous change notification delivered to the client application via standard event listeners All event objects and event listeners are aggregated in the com.starteam.events namespace Client applications typically register for Folder, Item, ViewMember or ServerCommand notification Project, View, Filter, Query & Label notifications are also supported, but may occur less frequently Applications interested in receiving events create event handlers (implementing the appropriate listener interface) and register these handlers with the SDK. import com.starteam.events.*; import com.starteam.*; private class ItemEventHandler implements ItemListener { public void itemAdded(ItemEvent e) {…} … }

Events ItemEventHandler ieh = new ItemEventHandler(); assertTrue(view.getServer().isMPXEnabled()); // Item, Folder or ViewMember Events only fire if MPX is enabled view.addItemListener(ieh); … view.removeItemListener(ieh); FolderUpdateEventHandler fueh = new FolderUpdateEventListener() {…} // ItemUpdate, FolderUpdate or ViewMemberUpdate Events are not dependent upon MPX // They are triggered by explicit operations performed by the client application // for instance, View.refreshFolders(), folder.update(), folder.remove() etc. might each trigger folder update events view.addFolderUpdateListener(fueh); view.removeFolderUpdateListener(fueh);

MPX Events An MPX-enabled SDK application can subscribe to specific server events (for example, an Item is added, modified or deleted), and provide event-handlers that are invoked when those events occur. The event-handling APIs support SDK applications that, without MPX publish/subscribe services, would be very difficult to write and prohibitively expensive to run. With MPX, an application simply registers an event handler, and waits for it to be invoked by the SDK. Event handling is supported in both the Java and C# APIs, using the standard Java or C# listener model. Listeners are always registered on an SDK object that defines the scope of interest. A given listener can also be registered at different levels of the SDK object hierarchy, providing the application with a great deal of flexibility in defining the scope of interest. The scope also defines the security context. Event-handlers use the same object model as the rest of the SDK; there is no way for an application to retrieve any data via an event-handler that it would not normally be able to retrieve outside the event-handler in the same security context. Event handlers are invoked from an event-handling thread that is separate from the main application thread. As a consequence, neither outgoing commands nor incoming events are capable of starving the other.

MPX Events A new class of Light weight MPX events are fired through a Typed Resource Listener. Register for these events on the server instance. Useful for continuous monitoring tools (which may not require views to be left open), significantly reduce server load If the view is never opened on the server, events are never fired. Conversely if the event is fired, the application may now open the view, since it has already been opened on the server by some other application… private class TypedResourceHandler implements TypedResourceListener { public void resourceAdded(TypedResourceEvent e) { …} } TypedResourceHandler trh = new TypedResourceHandler(); View v = s.findProject(“StarDraw”).getDefaultView(); s.addTypedResourceListener(trh, v, new TypeCollection() {s.getTypes().FILE}); v.close(); // do not cache view, folder, file etc. resources either in the client or on the server … // keep monitoring for changes, do something if a change is detected, perhaps launch an automatic build // or send a notification message to an administrator s.removeTypedResourceListener(trh, v);

Components The StarTeam Server manages server side components. Instances of these components ‘data objects’ are called artifacts. Components may subscribe to one or more services including Persistence and Versioning; i.e. artifacts may be accessed via generic queries and transacted updates Item Configuration; i.e. artifacts may support branching, sharing and/or organization within folders Minimally, items support locking, label attachment and addressability via links or traces. Attachments; i.e. non versioned files used to annotate or supplement an artifact Bookmarks; i.e. users may flag certain artifacts for searching and tracking Notifications; i.e. subscription services that support and status notifications to be delivered based on specific state changes of selected property values. Artifacts defined by components are automatically registered in the server’s component catalog.

Components All StarTeam (stock &/or custom) components have a common set of properties. These include View Member ID – a server wide, unique ID Root Object ID – the shared ID for all members of a given reference (share) tree Object ID – the shared ID for all members of a given branch Parent Revision Number – for branchable types, the parent revision at which the resource was branched Dot Notation – a String based annotation describing an object’s position in its share tree Created By, Modified By, Deleted By – the User who created, modified or deleted this object Created At, Modified At, Deleted At – the Date and Time that the object was created, modified or deleted. Revision Number – a sequential counter issued to each revision of a given object (when an object is updated, i.e. one or more of its property values are changed, a new revision of the object is created) In addition, each stock component has a fixed, out of the box set of properties that annotate the type.

Stock Components Stock components (types) are bundled with StarTeam and shipped with a pre-defined set of properties. Stock components are customizable. An application can add custom properties to any stock component. Files and ChangeRequests are Items. Requirements, Tasks and Topics are Tree Items. Tree Items may form regular top down trees, but not graphs. i.e. a task may have several sub-tasks, but a task can have only a single parent (task). Items are branchable; Tree Items are not. Folders are a bit of an anomaly. Folders are branchable containers. Folders may contain sub folders (tree like behavior) and any/all other item or tree item types. for example, a given folder can contain 3 sub folders, 5 Files, 2 Change Requests, a tree of 3 Tasks (parent-child-grandchild), a single stand alone Task and 1 Requirement Note that a given tree (of Tree Items) cannot span folders, but distinct trees may reside in different folders. For simplicity, the SDK models Folders and Tree Items as Items.

Stock Components – Files & Folders
The file type includes properties like Name, Description, Size, MD5, & HiveID. File content is managed by the server on a file system called a vault, which is organized by hives. Unlike other StarTeam components, file objects have a client side representation, namely, physical files in the local file system (workspace) on disk. Accordingly, files have client side properties such as full (path qualified) name, working file size, MD5 & modified time. To track differences between the working file on disk and its representation in the StarTeam Vault, the File type has a Status property, with values like CURRENT (content on disk is identical to that in the vault), MODIFIED (content on disk is newer than that in the vault) and OUT_OF_DATE (content on disk is older than that in the vault) The folder type includes properties like Name, Description & Path. Folders too have a client side representation, namely, working folders on disk. However, non file applications need not surface this client side representation, treating folders strictly as organizational containers (drawers) of StarTeam components. The SDK maps the client / server representations of Files & Folders. The StarTeam server itself is completely unaware of an existing client side representation. The file system is of course unaware of a server representation.

Stock Components – Change Requests
Change Requests, Requirements and Tasks are a class of Process Items. When a set of files is checked in, the set is associated with a Process Item in a given state. As part of the checkin, the Process Item may be transitioned to a different state. So for instance, a group of files can be checked in against a Change Request in an Open State (the Status Property value of the Change Request) and the Status Property value may be moved to a Fixed State. Currently, Custom Components cannot be used as Process Items. The Change Request Type includes properties such as Platform – applicable Operating System Platform Severity – High, Medium or Low Responsibility – the User responsible for addressing this request Synopsis – a brief description of the request Request Type – Suggestion or Defect

Stock Components – Requirements, Tasks & Topics
The Requirement Type includes properties like High & Low Effort Estimates, Expected Effort Owner – the User who owns this Requirement Responsible Users – the users responsible for implementing this requirement Notes Number of identified Ambiguities The Task Type includes properties like Actual Start & Finish Dates, Estimated Start & Finish Dates Resources – the set of Users assigned to the Task Successor and Predecessor Task Dependencies & WorkRecords TaskDependencies & Workrecord queries are bulkified & the types are MPX Enabled for 12.0 servers+. Threaded Topics include the Recipients property & the text (content) of the topic Topics can be used as discussion boards Notification is automatically sent via or displayed on the toolbar. Stock components are nothing more than shrink wrapped custom components!

Custom Components Custom Components can be created & ‘dropped into’ the 12.0 server by the component developer. The custom component schema is described using a well formed xml definition, published by server engineering (They may also be created using the SDK api Server.createType(String, boolean).) Custom Components are either Branchable (Item) types or Tree(Item) types Item.Type cstmTyp = s.getTypes().find(“MyCustomComponent”); // type metadata for the new component PropertyCollection prprtys = cstmTyp.getProperties(); // property metadata for this component ViewMemberCollection vmc = fldr.getItems(cstmTyp); // instances of this custom type in a collection The SDK knows nothing about Custom Components, except in the most generic way. Out of the box, the custom component shows up as an SDK Item or TreeItem Type, and can be manipulated using the standard getValue/setValue accessors. New instance may be created using Item.Type.createItem(Folder) // TreeItems are Items with two useful additional properties TreeItem[] kids = itm.getChildren(); // returns a list of the immediate children of this tree item instance TreeItem prnt = itm.getParent(); // returns the immediate parent of this tree item or NULL if this is a root

Custom Components Standard CRUD operations can be performed using standard methods like ViewMember.update() & ViewMember.remove() on custom component instances. Custom component instances can be fetched using either ViewMemberCollection Folder.getItems(Item.Type) or ViewMemberCollection View.getViewMembers(ViewMember.Type) Their properties can be populated using either Folder.populate(Item.Type, PropertyCollection, int) or ViewMemberCollection.getCache().populate(PropertyCollection) Their properties can be refreshed using either Folder.refreshItems(Item.Type, PropertyCollection, int) or ViewMemberCollection.getCache().refresh(PropertyCollection) Out of the box, an application developer treats custom components no differently than (say) ChangeRequest or Task

Custom Components The server automatically provides a set of ‘common’ or ‘stock’ properties for a custom component. Property Name Server Type SDK Type ID int Integer Property CreatedTime decimal DateTime Property CreatedUserID int User (Object) Property DeletedTime decimal DateTime Property DeletedUserID int User (Object) Property ModifiedTime decimal DateTime Property ModifiedUserID int User (Object) Property EndModifiedTime decimal DateTime Property RevisionNumber int Integer Property RevisionFlags int Integer Property ShortComment text String Property

Custom Components // Common Properties (contd)… Property Name Server Type SDK Type Comment varchar Text Property Comment ID int Integer Property AttatchmentCount int Integer Property AttachmentIDs varbinary Object Array Property AttachmentNames varchar Text Property NotificationCount int Integer Property NotificationIDs varbinary Object Array Property <ComponentTypeName>ID int Integer Property DotNotation varchar Text Property ConfigurationTime decimal DateTime Property

Custom Components // Server Calculated Common Properties… Property Name Server Type SDK Type ReadOnly bool Boolean Property Exclusive Locker int Object Property NonExclusiveLockers varchar Text Property BranchOnChange int Enumerated Property BranchState int Enumerated Property ShareState int (User) Object Property ItemDeletedTime decimal DateTime Property ItemDeletedUserID int Object Property ReadStatusUserList varbinary Object Array Property FlagUserList varbinary Object Property

Custom Components In addition to the common properties, Branchable Custom Component Types have the following specific additional properties RootObjectID int Integer Property ParentObjectID int Integer Property ParentRevision int Integer Property PathRevision int Integer Property ViewID int Integer Property Tree Item Custom Component Types have a specific property identifying the parent tree item ID ParentID int Integer Property

Custom Components (Extending the Object Model)
Application Developers may choose to extend the SDK Object model, providing class definitions for custom Components. These definitions belong to the client developers namespace, but are treated as first class SDK citizens! NOTE: The custom component MUST have been created on the server before client implementation package com.microfocus.teamDefine; import com.starteam.*; public class Visualization extends TreeItem { private static final String myTypeName = “VISUALIZATION”; // This name MUST match the type name specified // in the component .xml definition public Visualization(Folder parentFolder) { super(myTypeName , parentFolder); // this base class constructor must be called } public Visualization(Visualization parent) { super(parent); // and so must this one // add other apis’ as necessary, extend the StarTeam Type Model implement Client Calculated Properties, if any

Developing Custom Components
The Application Developer may extend the Type Model for the custom components. (This static class is a member of the component class) public static class Type extends com.starteam.{Tree}Item.Type { public static final String NAME = myTypeName; // and assign the type the name public Type(Server s, Type.MetaData d) { super(s, d); } Add property definitions for custom properties (specified through the xml definition) & client calculated properties Integer, LongInteger, Double & Text Properties may be sub-classed to create custom client calculated properties public static class MyClientCalculatedProperty extends IntegerProperty {…} Any property type definition can be sub-classed for custom properties public static class MyCustomContentProperty extends ContentProperty {…}

The Application Developer may also extend the Property Model for the custom component. This static class is a member of the type class, which is a static member of the component class public static class PropertyCollection extends Item.Type.PropertyCollection { public final MyCustomContentProperty MY_CUSTOM_CONTENT; protected PropertyCollection(Visualization.Type t, Property[] pp) { super(t, pp); setReadOnly(false); // add the client calculated properties, if any add(new MyClientCalculatedProperty (t); setReadOnly(true); MY_CUSTOM_CONTENT = (MyCustomContentProperty)find(MyCustomContentProperty.NAME); }

Extending the Property Model (continued) protected PropertyCollection(Visualization.Type t, Property[] pp) { super(t, pp); setReadOnly(false); // & add the custom calculated properties add(new MyClientCalculatedProperty (t)); setReadOnly(true); } // override Item.newPropertyCollection protected com.starteam.PropertyCollection new PropertyCollection(Property[] pp) { return new PropertyCollection(this, pp); // hook the new property into the model protected Property getProperty(com.starteam.Property.MetaData pd) { if (pd.toString().equals(MyCustomContentProperty.NAME) return new MyCustomContentProperty(this, pd); return super.getProperty(pd);

Client calculated properties are properties injected into the component instance cache. Their values are calculated on the client, typically involving client resources or aggregations of server properties Overide ViewMember::invoke() to hook in client calculated properties public Object invoke(String method) { if (Visualization.Type.MyClientCalculatedProperty.NAME.equals(method)) return new Integer(doSomeMath()); // call a method that does some calculation return super.invoke(method); // or pass it down } private int doSomeMath() { return new Random().nextInt(); } // and the value of a client calculated property can be queried through Item.getValue() Property clntClcPrprty = myObject.getType().getProperties().MY_CLIENT_CALCULATED; Integer someMath = myObject.getValue(clntClcPrprty); // &/or by iterating over the PropertyCollection PropertyCollection pc = getServer().getTypes().find(Visualization.Type.NAME).getProperties(); for (int i = 0; i < pc.length; i++) { myObject.getValue((Property)pc.get(i)); }

// Declare the custom component class to the SDK before connecting to the server s.declareComponentDefinition(Visualization.Type.NAME, Visualization.class); // and when writing your code, you can now cast to a custom type, and a call to getValue(ClientCalculatedProperty) calculates & returns a value from a method provided in the custom class getValue(CustomComponentProperty) returns the value of the property whose definition is in the custom class i.e. the SDK treats custom component definitions from an enclosing namespace as first class SDK citizens ViewMemberCollection vmc = fldr.getItems(cstmTyp); // returns instances of this type in a collection for (int i = 0; i < vmc.size(); i++) { Visualization itm = (Visualization)vmc.getAt(i); // component instances are returned as Visualization objects } // If Visualization is not a Tree Item Component, i.e. Visualization extends Item, then only one constructor is required public Visualization(Folder parentFolder) { super(myTypeName , parentFolder); // and this base class constructor must be called

The application developer can work with custom components definitions from any namespace just as if they were stock components from the SDK namespace Visualization.Type vsTyp = (Visualization.Type)s.getTypes().find(Visualization.Type.NAME); Vizualization[] vv = (Visualization[])fldr.getItems(vsTyp).toArray(new Visualization[0]); Visualization.Type.PropertyCollection pc = (Visualization.Type.PropertyCollection)vsTyp.getProperties(); Property myCstmCntntPrprty = pc.MY_CUSTOM_CONTENT; MyCustomContentProperty prprty = (MyCustomContentProperty)pc.find(MyCustomContentProperty.NAME); Content cntnt = vv[0].getValue(prprty); Visualization vz = vsTyp.createItem(myFolder); vz..setValue(someproperty, “its value”); vz.update();

Property Definitions for Client Calculated Properties – Property IDs MUST BE UNIQUE across the Type Assign each Client Calculated Property a unique incremented ID based on Property.CLIENT_CALCULATED static final class CalculatedWeightProperty extends IntegerProperty { private static final int CALCULATED_WEIGHT_id = com.starteam.Property.CLIENT_CALCULATED + 1; protected CalculatedWeightProperty(Type owner) { super(owner, CALCULATED_WEIGHT_id, NAME); } public static final String NAME = "Calculated Weight" /*NOI18N*/;

Property Definitions for Custom Properties – extend the only protected constructor visible from com.starteam public static final class MyIntegerProperty extends IntegerProperty { MyIntegerProperty(com.starteam.Type owner, com.starteam.Property.MetaData data) { super(owner, data); } public static final String NAME = "Usr_MyInteger“ /*NOI18N*/; Note that Enumerated Properties need special code to handle conversions from com.starteam.EnumeratedValue to equivalent strongly typed class definitions which sub-class embedded code in the next slide

// An example of sub-classing Enumerated Value public static final class StarFlowStatus extends EnumeratedValue { private int m_id; private StarFlowStatus(int id) { m_id = id;} public int getID() {return m_id;} public final static StarFlowStatus ENTERED = new StarFlowStatus(100); public final static StarFlowStatus NEW = new StarFlowStatus(110); public static final StarFlowStatus[] ALL = new StarFlowStatus[] {ENTERED, NEW}; public static StarFlowStatus fromValue(EnumeratedValue value) {…} public static StarFlowStatus fromID(int id) {…} public boolean equals(Object o) {…} public int hashCode() {return m_id;} }

Checkin Manager Uses a transactional model to add and checkin files, move and/or remove items on the starteam server. The public api’s build up the internal state of the manager, without executing a server call. mgr.checkin(file); mgr.checkin(file, new checkinOptions()); // assign checkin options to file mgr.checkinFrom(file, new java.io.File(“c://temp/”)); // assign different alternate path to file mgr.ignore(file); // remove file from consideration for checkin mgr.remove(item); // remove Item from the server mgr.moveTo(item, folder); // move Item to Folder on the server

Checkin Manager canCommit() returns false if a subsequent commit() will fail; for instance, if a File is in an UNKNOWN state, and the force checkin flag is off, or if there is nothing to commit commit() makes the least number of server calls entirely within a transaction. May comprise of several remove(), moveTo() and checkin() operations on the server. If an error occurs, the entire transaction is rolled back. A successful commit() creates a ChangePackage in the target view. Each change in the change collection maps the previous (pre commit) revision of the item to the committed revision. The source and target revisions of each change are in the same (target) view. If a Process Item is specified, a Trace links the Change Package to the Process Item. The resultant Change Package may be replayed as a VCM Promote, Rebase or Replicate. Optimized to use all available bulk commands

Checkout Manager The various overloads of checkout(…) build up internal state of the manager, without executing a server call Multiple calls to checkout() for the same file overwrite the in-memory internal state accordingly mgr.checkout(file); mgr.checkout(file, new checkoutOptions()); // assign checkout options to file mgr.checkoutTo(file, new java.io.File(“c://temp/”)); // assign different alternate checkout path to file mgr.ignore(file); // remove file from consideration for checkout

Checkout Manager canCommit() returns false if a subsequent commit() will fail; for instance, if a File is in an UNKNOWN state, and the force checkout flag is off, or if there is nothing to commit commit() actually executes the checkout. Unlike CheckinManager, this commit() is non-transactional. The result of a partial or aborted checkout can leave local files on the file system in an indeterminate state. If a network near CacheAgent is available, CheckoutManager will automatically fetch file content from the Cache Agent. Optimized to use all available bulk commands, and use the least number of server calls.

View Compare Merge The VCM APIs allow an application to compare two views, and merge differences from one to the other. A typical view compare/merge (VCM) application will perform the following steps: Construct a VCM session, specifying the merge type and the source and target views. In a compare only session, you may specify two different configurations of the same view. Set the scope of the session, if necessary. By default, all files and folders are in scope. Change the default VCM options, if necessary. Options determine whether or not file content will be merged automatically, whether source and target items will be locked, and so on. Compare the two views. Examine the resulting differences. Each difference indicates the source and target items, the difference type, and the recommended action. You may accept the default action, or overide it with any other legal action. Commit the session. This executes the actions specified for each difference, merging changes to the target view. The changes are executed as a single atomic transaction. When the session is committed, StarTeam creates a ChangePackage in the target view to record the changes. The ChangePackage includes new file and folder revisions; copies of the difference and update reports are included as attachments, as is an exported session file that can be used for future reference. The committed ChangePackage can subsequently be re-opened in a read-only mode, and differences between pre & post committed files can be reviewed, thus providing an audit trail of changes as they propagate through the system.

View Compare Merge An example of using VCM import com.starteam.*;
import com.starteam.viewcomparemerge.*; Server s = new Server(“host”, port); s.logOn(“user”, “password”); Project p = s.findProject(“StarDraw”); View v = p.findView(“Release 1.0 Maintenance”); Session n = new Session(MergeType.Promote, p.getDefaultView(), v); n.compare(); // defaults to Files & Session.setScope(Scope) ItemDifference[] ii = n.getDifferences(); // for, ensure that each ItemDifference can be committed n.commit(); // executes in a transaction, creates a ChangePackage when done n.close(); // release all resources, close open views, etc.

Command Processor A state-ful implementation in the SDK (augments the state-less implementation from earlier releases) Fully backward compatible with existing commands from stcmd Automatically supports MPX, Cache Agent, file & object property content Automatically supports transactions, bulk commands Refactor existing scripts to benefit from maintaining cross command state e.g.… connect [passwordFromFile passwordFile] [storePasswordToFile passwordFile] [caseSensitiveFolders | -csf] [encryption = RC4|RC2_ECB|RC2_CBC|RC2_FCB][compression | -cmp] [mpx=on|off (default ON) profile=profileName (default autoLocate] | =off] [-mode [lock | exlock | unlock]] set project=projectName [view=viewName | viewHierarchy=viewName:viewName:…] [folderHierarchy=folderName:folderName:....] [-cfgl "label" | -cfgp "promotion state" | -cfgd "date"] // … run commands e.g. select, checkin, checkout, etc disconnect Use the ‘new’ stcmd from a Windows Command Prompt, Unix shell… Use CommandProcessor directly from ant, hudson, javascript, etc.

Command Processor A new generalized SQL like query syntax
select * | access-rights | {propertyName, propertyName,...} | filter = 'myFilter' from type {history} {deleted} {at [label “labelName” | promotionstate “promotionStateName” | datetime “dateTimeValue” pattern “patternValue”]} {into “outputFilePath” {separator ’fieldSeparator’}} where { {attached-label = 'mylabel‘ | query = 'myquery' } {and} {folder = 'myfolder' {recurse} or folder = 'myfolderhierarchy' {recurse} or folder = . {recurse}} or ...}} order by {propertyName, propertyName,...} | orderfilter = 'myOrderFilter' type {File | Folder | ChangeRequest | Requirement | Task | Topic | ChangePackage | Trace | CustomComponent}

Command Processor A new generalized SQL like syntax for (transacted) bulk inserts insert into type {output * | {propertyName,...} | filter = 'myFilter‘ into “outputFilePath” {separator ’fieldSeparator’}} ( propertyName, propertyName, … ) values [( value, value, … ) | from ‘inputFilePath’] type {Folder | ChangeRequest | Requirement | Task | Topic | CustomComponent} Creates a Checkin Change Package

Command Processor A new generalized SQL like syntax for (transacted) bulk updates update type { output * | {propertyName,...} | filter = 'myFilter‘ into “outputFilePath” {separator ’fieldSeparator’}} set propertyName = value, … where { query = 'myquery' {and} {folder = 'myfolder' {recurse} or folder = 'myfolderhierarchy' {recurse} or folder = . {recurse}} or ...}} type {File | Folder | ChangeRequest | Requirement | Task | Topic | ChangePackage | Trace | CustomComponent} Creates a Checkin Change Package

Command Processor A new generalized SQL like syntax for (transacted) bulk deletes delete type { local } { output * | {propertyName,...} | filter = 'myFilter‘ into “outputFilePath” {separator ’fieldSeparator’}} where { query = 'myquery' {and} {folder = 'myfolder' {recurse} or folder = 'myfolderhierarchy' {recurse} or folder = . {recurse}} or ...}} type {File | Folder | ChangeRequest | Requirement | Task | Topic | CustomComponent} Creates a Checkin Change Package

Command Processor A new command for workspace and/or view synchronization sync workspace|view|both [-o] [-nivf] [-l | -u | -nel] [-vl "labelName"] [-nomove] [-r "comment" | -rf "fileName"] [[ -active | [-cr | -req | -task ] processItemPath] [-mark]] The sync{hronize} command is used to catch up with changes in the view and propagate them to the workspace (the user’s working folders on disk), and/or, to catch up with changes in the workspace and propagate them to the view. If only workspace is specified, the users working folders on disk are updated to reflect changes in the view, the view itself is unchanged. If only view is specified, then the view is updated to reflect changes in the workspace, the workspace is left unchanged. If both are specified, then changes are propagated in both directions. In any case, the post-sync state of the workspace & the view are structurally identical. Operations that occur on synchronization include checkout of out of date &/or missing files and folders; checkin of new &/or modified files & folders. (checkin operations will produce a checkin change package) –o forces an overwrite on checkin or checkout, and breaks merge conflicts -nivf turns on not in view folders, and is only relevant if the view is being updated. The rest of the parameters are only relevant if the view is being updated, and satisfy process rules

Command Processor Examples connect localhost:49201
set project = ‘StarDraw’ view = ‘Release 1.0 Maintenance’ apply-label -is -lbl Web1 files diff -is -w -vl \"New Step 2\ select * from changerequest into “c:/temp/QueryOutput.txt” separator ; select Name, Status, ‘File Time Stamp at Check-in’ from file where query = ‘Files to Check In’ select filter = ‘By Status and Responsibility’ from task where folder = ‘Sales Materials’ or folder = ‘Marketing Materials’ recurse update changerequest set synopsis = ‘foo’ where query = ‘Status = Open’ delete changerequest where query = ‘Status = Open’ disconnect

Artifact Cache A managed collection of typed artifacts & access rights
Tip caches are self refreshing. Baseline (rolled back) caches are invariant (i.e read only) w.r.t. time. Fully loaded & built up in the context of an Administrator, shared across all users, including those at lesser privileges Build up the cache using cacheViewMembers(WebCacheView, WebCacheViewMemberType[]); // manage all ViewMembers of the specified type(s) in the view Query the Cache using the api. WebCacheViewMember vm = findWebCacheViewMember(WebCacheUser, int);

Artifact Cache Manager
A managed collection of Artifact Caches. Manages a single Artifact Cache Manager per server, which contains a Tip Cache and as many historical caches as requested Register the Cache Manager for a given server Manages all Tip, i.e. Current Projects, Views, etc in the Tip Cache Manages a rolled back view (based on label, promotion state or date time) in its own (baseline) cache Discards historical caches after a specified unused expiration window Manages web ‘client’ applications that share Artifact Caches Artifact Cache Manager, Artifact Cache & the WebCache object model provide a thread safe connection pool mechanism for developing scalable multi user web applications Walk the model starting from the Administrative Context, which returns a WebCacheServer, WebCacheProjects, etc…

Web Cache Artifact Model

Web Cache Artifact Model
The web artifacts are wrappers around and peers to the core SDK artifacts. There is a 1 to 1 mapping between objects at each level. The model is complimentary. From the Context, the application developer can seamlessly switch between WebCache objects and their native peer’s and vice versa. ArtifactCacheManager.Context) The programming metaphor for web and peer objects is identical and could almost be swapped in place. All server calls are issued through the connection pool The web cache model forms the basis for the new MicroFocus web applications currently being developed (code name Topaz) But customers can use the model to develop their own web applications.

12.0+ Feature Sets New SDK namespace, fully revamped, consistent object model New command line (with rich SQL like extensions) Workflow support & Checkin Change Packages New Web Application Development Model 64 bit SDK .jar, .NET SDK assembly All SDKs are fully backward compatible with the 11.0 server. New to the Servers Custom Components Content & Map Properties Multi Select & Hierarchical Enumerations, Date Properties New built in Sprint, Story components

12.0+ Feature Sets New to 12.0+ Servers (continued) Bulk Queries for
History, Locking, Behavior, User Group Relationships Work Records, Task Dependencies, Project and View Access Rights MPX enabled Groups, Access Rights Work Records & Task Dependencies Move & Share Access Rights Split Attachments in the Vault

12.0+ Feature Sets The old (com.starbase) SDK .jar is still available to support APEs. Custom application developers are encouraged to port their applications to the new object model and namespace. A forum for StarTeam customers to answer SDK related questions & post regular SDK beta builds is now available.

StarTeam SDK 12.0+ Reprise A fully object centric new namespace
Backward compatible with 11.0 servers, forward compatible from servers Native Java & C# frameworks. Supports web application development Supports UI free back office development Supports client specific GUI development

StarTeam SDK Overview Anil Peres-da-Silva Principal Engineer, StarTeam Borland (A Micro Focus Company)

Similar presentations

Presentation on theme: "StarTeam SDK Overview Anil Peres-da-Silva Principal Engineer, StarTeam Borland (A Micro Focus Company)"— Presentation transcript:

Similar presentations

About project

Feedback

Log in

Auth with social network:

StarTeam SDK Overview Anil Peres-da-Silva Principal Engineer, StarTeam Borland (A Micro Focus Company)

Similar presentations

Presentation on theme: "StarTeam SDK Overview Anil Peres-da-Silva Principal Engineer, StarTeam Borland (A Micro Focus Company)"— Presentation transcript:

Similar presentations

About project

Feedback