A rationale for the com.starteam SDK namespace

over 9 years ago

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 and introduces the new com.starteam namespace.

The SDK is several years old and has evolved over time. Our policy had always been to not break backward compatibility in our public interfaces with earlier releases at any cost, even if we used styles or principles that were philosophically or practically incorrect. We had reached a point where we were unable to introduce new functionality, constrained by the existing public signatures. Hence, and since the 12.0 release, we addressed 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 the 12.0 release, we broke 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 do not expect to see many signature changes after 12.0, but we reserve the right to do that in the interest of ensuring the consistency and the correctness of the object model. Now at 14.0, we clearly will not have another sweeping refactoring of the SDK.

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. Our current strategy for surfacing C# is via a Java-J# cross compilation bridge. In other words, our C# assembly effectively wraps a J# assembly.

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 SDK install location. This jar will allow existing APEs to continue to work within the StarTeam Cross-Platform Client. However, the bridge jar and its corresponding com.starbase.starteam namespace does not surface any of the new functionality introduced in StarTeam 2009 (11.0)  Servers. We do not guarantee that the bridge jar will support any other existing applications.

The following table lists the new namespaces against their equivalent old namespace counterparts, where applicable.
Note that the equivalent C# names are captialized and do not start with com.

New Namespace (Old/Deprecated Namespace)
com.starteam (com.starbase.starteam,com.starbase.starteam.names,com.starbase.starteam.vts,com.starbase.starteam.vts.comm,

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.diff (com.starbase.diff)

Event objects & listener interfaces are aggregated into the com.starteam.events namespace, while SDK Exceptions have moved into 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. (This architecture actually mimics the server object model).

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 Component Model hierarchy has been formalized. Application developers need only focus on components in the com.starteam and the com.starteam.viewcomparemerge namespaces.

New since the 12.0  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 very accurate representation of the server model.

Each component has a Type. The Type hierarchy faithfully follows the component hierarchy. Types are implemented as public static classes on their components. For instance, File is an Item and File.Type is an Item.Type.

Each Type comprises a collection of Propeties described in an object hierarchy. For instance, a Boolean Property is an Enumerated Property is a 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:

are replaced by a strongly typed, public static ChangeRequest.Severity class.

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 now Folder.refreshItems(Item.Type. PropertyCollection, int)

All Objects and methods deprecated over the years have been removed. The 12.0 releases of the SDK support only the 11.0 (2009) 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.

Additionally, source code mappings from old namespace api’s to equivalent api’s in the new namespace are published in the supporting bridge .zip file, downloadable from this forum. The code is made available as is to help facilitate porting existing applications from the old namespace to the new one. The bridge .jar provided as part of the java runtime installation is the compiled version of this source code. It may be downloaded from here


Finally, for those client application tied to COM dependency (e.g. PowerBuilder) on the Microsoft Source Code Control Interface (MSSCCI), we continue to produce a 32 bit COM.dll with each build. This .dll exposes the old com.starbase.starteam interfaces as COM objects, for compatibility with our MSSCCI implementation. This .dll is installed with the 32 bit SDK installer.


Comment List
Related Discussions