Performance Considerations

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:

typeName

The name of the item type (for example, File) whose properties are to be retrieved.

propertyNames

A collection of the property names 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.

depth

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.

For an application that needs finer control over the retrieval of properties, the SDK provides an ItemList class, which allows both the collection of items and the collection of properties to be specified explicitly. It also allows properties to be retrieved in a background thread. For more information, consult the StarTeam API Reference.

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

Back      Home     Next