Location syntax

Each Resource has a location, which uniquely identifies the resource at a specific point in time. For a file-based resource, the location is expressed as a file path name. For a server-side resource, the location contains the information needed to find the object (for example a database ID in a VOB).

The location of the resource is required when reading or writing resource content or when reading or writing properties on a server.

Location objects:
  • Can be mapped to and constructed from strings.
  • Support hierarchical operations (such as parent, child, and lastSegment).
  • Are composed of name segments as in a typical file path name and establish a hierarchical structure to the namespace for resources in a repository.

The StpLocation object represents a resource address; as such, it can be used to construct a resource proxy (by using one of the resource proxy factory methods of Provider). As a general rule, the Resource proxy constructed from a Location must be the same type as the resource addressed by the Location. However, the type of resource addressed by a Location cannot always be determined from the address specification alone. As a result, this rule cannot always be enforced at the time the proxy is constructed.

All resources have a stable form of location that can be used to store resource identities on the client between client sessions. This stable location might not be the location used to create the resource. The server creates this stable location for the user at resource creation time; this location is always available as an unchanging property of the resource. The StpLocation object provides methods for obtaining the string representation for a location and for parsing that string back into a location.

An StpLocation instance represents a location specification that has been parsed into its component fields. A number of different formats, or schemes, are used to express the location of various resources as a string. These schemes consist of one or more of the following fields: domain, repository name, namespace, and object name. The namespace field determines which scheme is being used.

The StpLocation interface provides methods for parsing a location specification into its constituent parts. Using the available methods, HCL VersionVault CM API clients can examine location specifications provided by the user to determine if they are appropriate for the context in which they are being used. Based on this analysis, a client can provide the parts of the location specification that the user omits if the context defines those missing parts unambiguously.

The StpProvider.stpLocation() method facilitates this process by filling in a missing location string scheme from its Namespace parameter and filling in a missing repository from the default repository identified to the Provider by the client. (See the StpProvider.setDefaultRepository method in the Javadoc information.)

For operations that require a user-specified file-system artifact, a file-system pathname into a workspace file area is sufficient. For operations that require a user-specified object of another type (such as an activity, project, or record) use a syntax that specifies the general, fully-specified form of a location string that identifies an object by name: 
<domain>.<namespace>:<object-name>@<repository-name>
In the following example, the default domain is implied:
"stream:mystream@projects"
  • <domain > distinguishes different repository types, implementations, or providers, of similar objects.
  • <namespace> identifies a namespace in which <object-name> is recognized. In the HCL VersionVault CM API, several different kinds of objects can appear in the same namespace. For example, the record namespace can include database sets, databases, record types, records, fields, and attachments. A resource can also appear in multiple namespaces. For example, Repositories appear in each namespace that contains a resource within the repository. Therefore, a user database appears in the record, action, and query namespaces. The namespace used to name a folder controls the meaning of doReadMemberList because the locations for the members of a folder must be simple extensions of the name of the folder, which must be in the same namespace as the folder.
Software that understands location specifications might allow various fields to be omitted. For example:
  • <domain> can be omitted if the type can be inferred, or if a default type is set.
  • <namespace> prefix can be omitted if the namespace of objects is understood by the context, or if a default namespace is available.
  • <object-name> is omitted when referring to a repository itself, or to the root of a namespace.
  • <repository-name> can be omitted if a default repository is used.

The StpProvider interface includes methods for building an StpLocation in formats such as USER_FRIENDLY_LOCATION and STABLE_LOCATION with userFriendlySelector and stableSelector methods. The StpResource interface includes getStableLocation and getUserFriendlyLocation methods that return the values for the STABLE_LOCATION and USER_FRIENDLY_LOCATION properties defined by the proxy. If the client needs a location in a specific format it should request the resource property that corresponds to that format and not use StpLocation.stpLocation().