The StarTeam SDK Object Model
The StarTeam SDK Object Model
The StarTeam SDK APIs are object-oriented. This means that the interfaces are exposed as a network of objects with properties and methods. The specific object types that are defined, and the various relationships among the objects, are together referred to as the StarTeam SDK object model.
There are several hundred objects in the StarTeam object model. However, the number of objects that you are likely to use in developing a typical custom application is much smaller. Furthermore, if you are familiar with the StarTeam product, the object model will be easy to learn, because the objects represent things that you already understand: Server, Project, View, Folder, File, and so on.
Some of the specifics regarding how the various objects, properties, and methods are exposed in the StarTeam APIs depend on whether you are using the Java interfaces or the C# interfaces. However, the basic StarTeam object model is the same across both flavors of the API. Once you learn the object model and are comfortable developing StarTeam applications in one programming environment, the concepts you have learned can be re-used in other environments as well.
Servers, Projects, Views and Folders
The most fundamental objects in the StarTeam object model are those that represent a StarTeam Server and the associated Projects, Views, and Folders. These objects will be used by almost every StarTeam application.
The Server object is the root object of the StarTeam object model. Conceptually, it represents a StarTeam Server (repository). Every other object is accessible, either directly or indirectly, via the Server object.
Most StarTeam applications will begin by constructing a Server object. Exactly how this is done depends on whether you are using the Java or C# APIs. This will be discussed in more detail later. For the purpose of this section, assume that you have managed to obtain a Server object, and you are ready to use it.
In order to use the Server object, you must first establish a connection to a specific StarTeam Server, and log on as a specific user. This is done using the logOn() method of the Server object.
All subsequent operations on the Server object (or on the objects that are accessible from the Server object) will be performed in the security context of the logged-on user. The security context determines access rights. For example, some methods require Administrator privileges and will generate an error if the logged-on user is not a StarTeam administrator.
The Project object represents a project that is available on the StarTeam server. Once you have logged in to a server, you can access the set of projects that are available, using the Projects property of the Server object.
The value of the Projects property is a collection of Project objects. Collections are common in the StarTeam object model. The precise representation of a collection depends on which flavor of the StarTeam APIs you are using. However, all versions allow you to iterate through the members of the collection, search for a specific member, and so on.
The View object represents a view of a StarTeam project. Each Project object has a Views property, whose value is a collection of View objects representing views that have been defined for that project. The default view can be accessed directly via the DefaultView property of the Project object.
In StarTeam, a view can be derived from, or based on, a parent view. Each View object has a DerivedViews property, whose value is a collection of View objects for the views that were derived from this one. Each view also has a ParentView property, whose value is the view from which it was derived. The DerivedViews and ParentView properties of the View objects can be used to traverse the View hierarchy of a project, whereas the Views property of the Project object presents the views as a flat list.
The Folder object represents a StarTeam folder. Each View object has a RootFolder property, whose value is the Folder object representing the root folder of the view. Each folder has a SubFolders property, whose value is a collection of the subfolders of this one, and a ParentFolder property, whose value is the parent folder. The SubFolders and ParentFolder properties can be used to traverse the folder hierarchy of a StarTeam view.
Folders can contain Items of various types, such as Files, Change Requests, and so on. Items of a particular type, and contained within a specific folder, are retrieved using the getItems() method of the Folder object. Items are discussed in more detail in the following section.
Items are the objects that represent the main data elements in the StarTeam repository, including Files, Change Requests, Topics, etc. Not all item types are necessarily available on every server, and some servers may support custom item types.
The StarTeam object model defines both a general Item class and derived classes for File, ChangeRequest, Topic, and Task. Items in general have a certain set of properties and methods. Each derived class inherits the properties and methods of the Item class, and adds specialized properties and methods that are specific to the derived class. In fact, the Item class itself is derived from a more general class known as TypedResource.
A general class that provides methods for retrieving arbitrary named properties of objects. The getValue() method retrieves the value of a named property, and the setValue() method sets the value of a named property.
Represents a data item stored in a folder within a StarTeam project. Items inherit the properties and methods of the TypedResource class, and define additional convenience methods for retrieving named properties that are available for all items.
For example, all items have a parent folder, which can be accessed directly via the ParentFolder property of the Item class, or indirectly by way of the getValue() method of the TypedResource class (by specifying the appropriate property).
The Item class also provides properties and methods to access the History of an item, the Attachments associated with an item, and so on.
Inherits all properties and methods of the Item class, and adds properties and methods that are specific to Files, such as getStatus() and updateStatus().
Provides convenience methods for manipulating ChangeRequest properties such as Status, Synopsis, Description, and so on.
Provides access to a task’s EstimatedStart date, EstimatedFinish date, Duration, and so on.
The hierarchical Item object model has several advantages. For custom StarTeam applications that are designed specifically to manipulate one item type (for example, a ChangeRequest), the application is free to use APIs that are specially tailored for that item type (for example, Status, Synopsis, and Description properties). On the other hand, an application may be designed to work with any type of item in the repository by using the more general, but possibly less convenient, Item-level interfaces.
This generalization is also important because StarTeam allows the administrator to customize the repository. This includes the ability to add custom fields to any item type, add or rename values to enumerated fields, and so on. In fact, it is possible for third parties to add custom item types to the repository that were not anticipated at the time the StarTeam API was developed. By using the generalized Item-level interfaces, the StarTeam SDK is capable of manipulating data that has been customized in application-specific ways.
You may have noticed that the Folder class derives from the Item class. One implication of this is that developers of custom StarTeam applications can add custom fields to a Folder object, and manipulate them via the StarTeam API
Types and Properties
In order to make the Item-level interfaces truly useful in the context of a customized repository, the StarTeam SDK needs a way to introspect on the repository schema. That is, it must be possible to discover the item types available on a given server, the properties available for a given item type, the data type or list of possible values for a given property, and so on.
Represents a specific object type available on the server. The Server object has a Types property, whose value is a collection of the available Type objects. This includes non-Item object types (such as Project, View, and so on), as well as custom item types that might be provided by third parties.
Represents a property that is defined for a given object type. Each Type object has a Properties property, whose value is a collection of the Property objects for the properties defined for that Type. This includes the default Item properties (that is, those described in the PropertyNames object), as well as custom properties that have been added to the repository by the StarTeam administrator.
The Type and Property objects are valuable to any StarTeam application that is general enough to support repository customizations. For example, any application that lists the items in a folder, and displays the values of all properties that are available for those items, would need to examine the Type and Property objects to determine what information is available in the repository.
The Property object itself has properties and methods (in the SDK) that can be used to obtain information about the property (in the StarTeam repository). For example, the Name property of the Property object retrieves the internal property name as used in the repository schema. The DisplayName property provides a corresponding user-friendly name, as might be displayed in an application’s user interface.
To retrieve the Type object corresponding to a specific object type, use the getTypes() method of the Server object. To retrieve the Property object corresponding to a specific named property, use the getProperties() method of the Type object. So, for example, to get the Property object corresponding to the Status property of a ChangeRequest object, you might use the following:
ChangeRequest.Type type = server.getTypes().CHANGE_REQUEST
prop = type.getProperties().find(ChangeRequest.Type.StatusProperty.NAME)
The component object has a convenience PorpertyCollection that may be used to achieve the same result. So, if you have a specific ChangeRequest object available, you could use the following:
prop = cr.getProperties().STATUS
Some properties have a value that is an enumerated type. (Such properties are instances of an EnumeratedProperty.) StarTeam administrators can customize the display names of each enumerated value, and, in some cases, add new enumerated values.
To get the list of possible values for an enumerated type, use the getAllValues method of the (Enumerated)Property object. The method returns a collection of EnumeratedValue's, each of which is a code/name pair representing one of the possible values. To get a user-friendly display string for the enumerated value code, use the getEnumDisplayName() method of the Property object. So, for example, to retrieve the Status property of a Change Request, and convert the resulting code to a user-friendly display string, you could use the following:
prop = cr.getProperties().STATUS
status = prop.getEnumDisplayName(cr.getStatus().getID())
Many applications that use the StarTeam SDK will be manipulating thousands of items across many folders. In such applications, significant performance gains can be achieved by following a few simple guidelines.
Internally, the StarTeam SDK uses a simple caching mechanism to improve performance. Whenever an application retrieves some property of an item (for example, the Status property of a ChangeRequest), the SDK checks to see if the value of the property for that item has been cached. If so, the value of the property can be returned to the caller without making any requests to the StarTeam server.
If, however, the value of the property has not yet been cached, then the SDK must first request the property from the server, then cache the result and return it to the caller. Making any request to the StarTeam server is a relatively expensive operation. In fact, it is expensive enough that if the SDK must retrieve the value of a property from the server, it retrieves the values of all properties for that item in a single request, and caches them all.
As long as the application is working with a small number of items, this behavior should be sufficient to achieve adequate performance. If, however, the application is displaying the values of one or more properties for thousands of items, the SDK will make thousands of requests to the server (one request for each item), and performance will suffer as a result.
For such situations, the SDK provides a mechanism to retrieve the properties of many items at the same time. The Folder object has a populateNow() method, which takes the following parameters:
The item type (for example, File) whose properties are to be retrieved.
A collection of the properties that are to be retrieved. If the application uses a small set of properties, they may be listed explicitly here. Alternatively, the application may pass null, which retrieves all properties.
Allows subfolders to be populated recursively. A depth of zero populates all items in the folder, but none in any subfolders. A depth of 1 populates all items in the folder, and all items in the folder's immediate subfolders. A depth of -1 populates the folder and all subfolders at any depth.
An application developer may also retrieve the properties of all items of a given type in the view, using an equivalent api
Caching items and properties improves performance at the cost of higher memory usage. In addition, changes made to the StarTeam repository after the information has been cached will not be apparent to the application. For example, another user may have added an item or changed the value of a property.
To clear a folder's item cache, use the discardItems() method of the Folder object. The next request for a property of an item in that folder will result in a call to the server. If the application still needs the items in a folder, but wants to refresh the collection with the latest set of items and properties available in the repository, call discardItems() followed by populateNow().