Location objects

Each resource has a location that uniquely identifies it to the server. The ClearCase® CM server API StpLocation object represents the location of a resource and is required to construct a proxy for the resource. An StpLocation object is constructed by the Provider from a string representation of the location. The syntax for specifying resource locations in this string representation is defined by the API in the Javadoc information for StpLocation. The string argument to the Provider.location(...), StpProvider.stpLocation(...), and StpPovider.buildProxy(...) operations must conform to the syntax specified in StpLocation. The API location string syntax is an extension of the ClearCase object-selector syntax.

For example, the location string for a resource file or directory on a client machine is the file pathname. This format is used in the following code fragment to check out a file named sample_file.txt.

//  Given a CcProvider object, m_provider, which must first be instantiated,
//  create a Location object from a unique file pathname.
//  Use "C:\\sample_view\\sample_dir\\sample_file.txt" on Windows,
//  or "/sample_view/sample_dir/sample_file.txt" on Linux and UNIX.
StpLocation fileLoc = m_provider.stpLocation("C:\\sample_view\\sample_dir\\sample_file.txt");
//  Create the ControllableResource proxy for the client - a versioned file
//  is a ControllableResource
CcControllableResource my_ctresource = m_provider.ccControllableResource(fileLoc);

//  Use the proxy to work with the controllable resource.
//  For example, check out the file:
my_ctresource.doCheckout();

As this example illustrates, the provider.stpLocation() method returns a StpLocation object that corresponds to a location specification. The StpLocation object (fileLoc) is subsequently passed to Provider.ccControllableResource() to construct a proxy for the resource at that location.

The following example specifies the location of a server-side resource (for example, an activity in a VOB):

StpLocation activityLoc = provider.stpLocation("cc.activity:my_fix_a_bug@/vobs/projects");
CcActivity act = provider.ccProvider().ccActivity(activityLoc);

The StpLocation interface also provides methods for parsing and composing strings that contain location specifications. An StpLocation object is available from each proxy, which corresponds to the location of the object referenced by that proxy. StpLocation is extended to indicate the Provider from which an StpLocation object originated. For more information about StpLocation objects and location specification syntax, see Location syntax. For additional examples of using a location string and setting properties, see, Writing properties.