com.starteam – The new StarTeam SDK namespace
Introduction:
The StarTeam SDK is the only portal to the StarTeam Server. It is developed in Java and cross-compiled into C#. The SDK offers a rich object model that encapsulates the command structures used to communicate with the server. An SDK Object consists of properties and methods that expose only primitive data types (string, int, long, bool, byte, char, double, float), other SDK Objects and arrays. The arrays represent collections of primitive data types or other SDK objects. In some cases, the SDK also provides specialized collections, native SDK objects that support iteration. This document describes the changes made in the StarTeam 2011 SDK release andintroduces the new com.starteam namespace.
The SDK is several years old and has evolved over time. Our policy had been not to break backward compatibility in our public interfaces with earlier releases at any cost, even if we use styles or principles that are philosophically or practically incorrect. With this release, we address all the interface issues that have plagued rich SDK application development, including our own clients. We have eliminated all public interfaces that use strings or integers as proxies for objects. For instance, we have removed the TypeNames, PropertyNames, PropertyEnums & Permission classes (objects whose entire interface described public static integer or string constants). In their place, we expose objects that are specialized Types, Properties and Permissions, instances that reside within their respective collections. The impact of this change is far reaching. We have eliminated all methods of the form hasTypeForName(String name), hasPropertyForPID(int pid), getValue(String propertyname), hasValues(String[] propertyNames), getContainerLevelACL(String permission), setResponsibility(int userid), etc.
In their place, we have introduced equivalent strong typed methods like getValue(Property p), getContainerLevelACL(Permission p), setResponsibility(User u), etc. Additionally, we adhere to strict naming conventions.For instance, we have replaced server.typeForName(String) with server.getTypes().find(String).
In this release, we have broken backward compatibility in earnest, hoping that the gains in terms of usability, correctness, and simplicity of the new model outweigh the one time cost of porting custom applications.
We have dropped the old namespaces from the SDK as well as support for J# and COM. All .NET client applications need to be ported to C#. Our Java & C# APIs are very similar to each other, the key difference being that Java get/set accessors are replaced by true C# properties.
In order to provide backward compatibility to customers who have written custom Alternate Property Editors (APEs) using the com.starbase.starteam namespace, a bridge jar is provided in the 2011 SDK install location. This jar will allow existingAPEs to continue to work within the StarTeam 2011 Cross-Platform Client. The bridge jar and its corresponding com.starbase.starteam namespace will not surface any of the new functionality introduced in the 2009 StarTeam Server and beyond. We do not guarantee that the bridge jar will support any other existing applications.
Changes:
The following table lists the new namespaces against their equivalent old namespace counterparts, where applicable.
Note: The SDK is implemented using Java 1.2 compliant api’s, for cross compilation to C#. Features like Generics, Enums etc are not used in the SDK, since they do not cross compile over to J#.
However, we develop our own client applications in J2SE6.x, taking full advantage of all the new Java language features available. In a future release, we would like to use richer Java constructs,which would enable us to enforce information hiding compiler use. We will not have to rely upon convention, only if that were not to compromise our .NET offering.
New Namespace / Old Namespacecom.starteam / com.starbase.starteam
com.starteam.util / com.borland.starteam.util
com.starbase.util
com.starteam.xml / com.borland.starteam.xml
com.starteam.viewcomparemerge / com.starbase.starteam.viewcomparemerge
com.starteam.events
com.starteam.exceptions
com.starteam.diff / com.starbase.diff
com.starbase.starteam.names
com.starbase.starteam.vts
com.starbase.starteam.vts.comm
com.starbase.starteam.vts.commands
com.starbase.starteam.vts.pickle
Event objects & listener interfaces areaggregated into the com.starteam.events namespace, while SDK Exceptions have movedinto the com.starteam.exceptions namespace.
We have eliminated the Adapter classes. Development environments like Eclipse automatically generate stub implementations of interfaces, thereby making the adapters redundant.
We have converted classes that comprised nothing but integer or string constants into type safe objects, with each constant replaced by a static instance of the underlying class. Similarly, we have converted clustered groups of Enumerations from PropertyEnums.java into type safe objects, with transformations to and from EnumeratedValues.
We have moved most of the implementation of the Item class into base classes, namely, ViewMember, VersionedObject, LiveObject, TrackedObject & BaseObject.
The SDK collection classes all implement the Collection<E> interface in Java, the IList interface in C#
The collection classes are type safe. For instance, you cannot add a Server object to a ViewMemberCollection or vice versa.
The StartTeam object model comprises components like File, Change Requests etc. A Type that comprises a set of properties describes each component.
The following screen shots show the Component Model hierarchy. Application developers need only focus on components in the com.starteam and the com.starteam.viewcomparemerge namespaces. New to this release are ChangePackages, Changes and Traces. A ChangePackage is a collection of Changes resulting from a Transactional Commit of a VCM Session (Promote, Rebase or Replicate) or a multi-file Checkin. A Trace describes a bi-directional relationship between two components. Traces can be cross-server, cross-project or cross-view. Traces replace Links and subsume their entire functionality. A RecycleBin is a View that also surfaces deleted items. VCMFolder & MergePreview are client side simulations of Folders & Views used to describe a VCM session, specifically the differences between the selected source & target views. The SDK object model is a veryaccurate representation of the server model.
Each component has a Type. The Type hierarchy faithfully follows the component hierarchy. Typesareimplemented as public static classes on their components. For instance, File is an Item and File.Type is an Item.Type. The following screen shot depicts the Type hierarchy.
Each Type comprises a collection of Propeties. The following screen shot depicts the core Property Hierarchy. In addition, a Boolean Property is an Enumerated Property. Each Type has its own property collection. Type specific properties derive from these base property types and are exposed as public static classes on the Type itself.
For instance, the TraceType Property is an EnumeratedProperty, exposed as a public static class on the Trace.Type class. By contrast, common properties are members of base class types. For instance, the ShareState Property is a public static class on ViewMember.Type
Strongly typed objects replace all groups of clustered integer constants.
As an example:
PropertyEnums.CR_SEVERITY_HIGH
PropertyEnums.CR_SEVERITY_MEDIUM
PropertyEnums.CR_SEVERITY_LOW
are replaced by a strongly typed, public static Severity class member of the ChangeRequest object
public static final class Severity {
/**
* The ID of the corresponding EnumeratedValue, as defined in SeverityProperty.
* @return The ID of this Severity value.
*/
public int getID() {…}
public static final Severity LOW = new Severity(0);
public static final Severity MEDIUM = new Severity(1);
public static final Severity HIGH = new Severity(2);
public static final Severity[] ALL = { LOW, MEDIUM, HIGH };
/**
* Gets the Severity value corresponding to the given EnumeratedValue.
* @param value One of the EnumeratedValues of a SeverityProperty.
* @return The corresponding Severity value, or null.
*/
public static Severity fromValue(EnumeratedValue value) {...}
/**
* Gets the Severity value corresponding to the given ID.
* @param id A Severity ID.
* @return The corresponding Severity value, or null.
*/
public static Severity fromID(int id) {…}
public boolean equals(Object o) {...}
public int hashCode() {...}
}
All these transformations from integer constants to strongly typed objects follow the same model and expose identical APIs.
Strongly typed objects replace all access by integer or string proxies.
For example, all public methods in the SDK that took typeName or typeID as parameters instead require the Type. This is also true for the Property, Filter, Query, User, Group, Label, Project, View & PromotionState types.
Types are narrowed where appropriate, which also enforces compile time type checking.
For instance, Folder.refreshItems(String typeName, String[] propertyNames, int depth) is nowFolder.refreshItems(Item.Type. PropertyCollection, int)
All Objects and methods deprecated over the years have been removed. This release of the SDK supports only the 11.0 server and beyond. All pre 11.0 checks have been dropped from the SupportedFeatures.java class.
StarTeamClientOptions is supported only in xml format.
Transformation from the old .ini format (obsolete since the 8.0 version) to .xml format has been dropped.
An object by object comparison of changes is available in the supporting document api-changes-since-11.0-release.html
Source mappings from old namespace api’s to equivalent api’s in the new namespace are available in the supporting bridge .zip file bridge.src.zip This code is being made available to help facilitate porting existing applications from the old namespace to the new one.The bridge .jar provided as part of this installation is the compiled version of this source code.