Project: stp

com.ibm.rational.wvcm.stp
Interface StpLocation

All Superinterfaces:
Location
All Known Subinterfaces:
CcLocation

public interface StpLocation
extends Location

An extension of the javax.wvcm Location interface that provides a programmatic representation for the location of a resource.

An StpLocation instance represents a location specification that has been parsed into its various 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. It is the namespace field that determines the scheme being used.

Locations are hierarchical, with the domain field specifying the top level of the hierarchy. Within a domain, resources are partitioned into repositories. Within a repository, resources are first partitioned into namespaces, and then uniquely identified by segmented pathnames within that namespace.

Each scheme requires certain of the above fields to be specified. If required fields are not present, the StpLocation object will have a non-OK Status. Individual field values can be queried to determine which fields aren't present.

To use this StpLocation to construct a proxy, its Status must be OK.

When a proxy is constructed, a new StpLocation may need to be constructed, so clients must not assume that the object returned by Resource.location() or any of the StpLocation factory methods defined in StpProvider is the same object passed to the proxy factory that created the proxy.

The preferred scheme for specifying an object is the object selector scheme, which has the following structure

[[<domain>.][<namespace>]:] [<object-name>][@[<repository-name>]]

The <object-name>, and <repository-name> fields are segmented names where the segments are separated by '/'s or '\'s. The permitted <namespace>s are defined by StpLocation.Namespace and the permitted <domain>s are defined by StpProvider.Domain.

The character '@' is reserved for use as the repository field delimiter as defined above. If it is to be part of the name field, it must be escaped by preceding it with a percent sign '%'. Similarly, the characters '/' and '\' are reserved in both the name and repository fields to be used as pathname segment separators. To use them as part of a segment they, too, must be escaped using a percent sign. Use two percent signs, '%%', to include a percent sign in the name or repository field. Note that escaped characters within a field are not unescaped when parsed into a StpLocation. Utility methods are provided by the StpProvider class for unescaping the fields, should a client need the unadulterated image.

Some resources can also be referenced directly or indirectly by an absolute or relative file system pathname. As an StpLocation image, such representations are called path-scheme locations, which have the following structure

[[<domain>.][<namespace>]:] [<path-name>]

The path-scheme locations are further categorized by their namespace as indicated in this enumeration...

This interface defines a predicate for each of these categories. The reader is referred to the documentation for those predicates for more information on the formation and meaning of each type of path-scheme location. Note that if a namespace is not one of the above path-scheme namespaces, it is an object selector scheme namespace.

%-escaping is not used in path-scheme locations.


Nested Class Summary
static interface StpLocation.ExtendedNamespace
          An object containing additional information associated with certain Namespace enumerators.
static class StpLocation.Namespace
          This class enumerates the namespaces that may appear in a location specification.
 
Field Summary
static String DELIMITERS
          The characters within a selector that syntactically delimit the fields and segments embedded within the selector.
static String ESCAPE_CHAR
          If one of the characters of DELIMITERS is to be part of a name segment it must be protected from its syntactic interpretation by preceding it with this escape character.
static String FIELD_DELIMITERS
          The characters within a location specification that syntactically delimit the fields of the selector.
static String SEGMENT_DELIMITERS
          The characters within a selector field that syntactically delimit the segments of a field.
 
Method Summary
 Location child(String child)
          Returns an StpLocation whose name field is the name field of this StpLocation extended by the given child segment.
 boolean equals(Object arg0)
           
 StpLocation forClass(Class<? extends Resource> proxyClass)
          Constructs a location suitable for addressing resources of the type indicated by the supplied proxy class by filling in unspecified fields of this location using provider-defined or resource-type-dependent defaults.
 String getCanonicalPath()
          Interprets this StpLocation as a file-path-scheme location and returns the canonical pathname for the file.
 StpProvider.Domain getDomain()
          Returns the domain specified or implied by the selector.
 StpLocation.ExtendedNamespace getExtendedNamespace()
          Returns an ExtendedNamespace object that, for some namespaces, contains additional information about the namespace field beyond its Namespace value.
 File getFile()
          Returns a File object that references the path defined by this StpLocation.
 String getName()
          Returns the object name field specified for this location.
 int getNameSegmentCount()
          The number of segments in the object name.
 String[] getNameSegments(int nSegs)
          Returns the first N segments of the name field of this location specification.
 String[] getNameSegments(int firstSeg, int lastSeg)
          Returns contiguous segments of the name field of this selector.
 StpLocation.Namespace getNamespace()
          Returns the StpLocation.Namespace of this selector.
 String getRepo()
          Returns the repository field of this location specification.
 int getRepoSegmentCount()
          The number of segments in the repository name.
 String[] getRepoSegments(int nSegs)
          Returns the first N segments of the repository field of this location.
 String[] getRepoSegments(int firstSeg, int lastSeg)
          Returns contiguous segments of the repository name of this location.
 String getResourceType()
          Returns the resource type field of a location specification if it used a compound namespace.
 int hashCode()
          Uses the hash code of the composed String image
 boolean isFastSelectorScheme()
          Returns whether or not this location uses an object selector scheme with a compound FAST namespace.
 boolean isFilePathScheme()
          Returns whether or not this location is specified using the file path- scheme format.
 boolean isHistoryModeScheme()
          Returns whether or not this file-path scheme location uses the optional ClearCase history-mode naming syntax.
 boolean isObjectSelectorScheme()
          Returns whether or not this location uses either a stable, fast (efficient), or user-friendly object selector scheme.
 boolean isOidSelectorScheme()
          Returns whether or not this location uses an object selector scheme with a compound OID namespace.
 boolean isOk()
          Overall status of this StpLocation
 boolean isPathScheme()
          Returns whether or not this location is specified using a pathname format.
 boolean isRepoSelectorScheme()
          Returns whether or not this location uses an object selector scheme with a compound REPO namespace.
 boolean isRepositoryPathScheme()
          Returns whether or not this location specifies a repository using a path- scheme format.
 boolean isUrlPathScheme()
          Returns whether or not this location is specified using the URL path- scheme format.
 boolean isUserFriendlySelectorScheme()
          Returns whether or not this location uses an object selector scheme with user-friendly namespace, name, and repository fields.
 String lastSegment()
          Returns the last segment of the name field of this StpLocation.
 Location parent()
          Returns an StpLocation whose segmented name field is one segment shorter than the name field of this StpLocation provided the name field of the resulting StpLocation would be valid.
 StpLocation recomposeAsPname(boolean withPrefix, StpProvider.Domain domain)
          Constructs an StpLocation for a pname based on the image of this StpLocation.
 StpLocation recomposeWithDomain(StpProvider.Domain domain)
          Constructs a new location based on this location with a replacement for its domain field.
 StpLocation recomposeWithMods(Object namespace, String name, StpProvider.Domain domain, String repo)
          Constructs an StpLocation object based on the fields of this StpLocation with optional replacements for some of the fields.
 StpLocation recomposeWithName(String name)
          Constructs a new location based on this location with a replacement for its name field.
 StpLocation recomposeWithNamespace(StpLocation.Namespace namespace)
          Constructs new location based on this location but with a replacement for its namespace field.
 StpLocation recomposeWithRepo(String repo)
          Constructs a new location based on this location with a replacement for its repository field.
 StpLocation recomposeWithResourceType(String rType)
          Constructs an object selector with a replacement for its resource type field, forcing the namespace to REPO.
 StpException status()
          Generates an StpException object that reports the state of this StpLocation.
 StpProvider stpProvider()
          Returns the StpProvider object that created this StpLocation object
 void throwIfNotOk()
          Throws an INVALID_OBJECT_SELECTOR StpException if this StpLocation does not reflect a syntactically complete and correct location specification.
 String toString()
          Reconstitutes the location specification from its component fields.
 String toStringWithoutDomain()
          As above, but returns a location string without the domain prefix.
 
Methods inherited from interface javax.wvcm.Location
string
 

Field Detail

DELIMITERS

static final String DELIMITERS
The characters within a selector that syntactically delimit the fields and segments embedded within the selector.

See Also:
Constant Field Values

ESCAPE_CHAR

static final String ESCAPE_CHAR
If one of the characters of DELIMITERS is to be part of a name segment it must be protected from its syntactic interpretation by preceding it with this escape character. The escape character must also be escaped if it is to be part of a name segment.

See Also:
Constant Field Values

FIELD_DELIMITERS

static final String FIELD_DELIMITERS
The characters within a location specification that syntactically delimit the fields of the selector.

See Also:
Constant Field Values

SEGMENT_DELIMITERS

static final String SEGMENT_DELIMITERS
The characters within a selector field that syntactically delimit the segments of a field.

See Also:
Constant Field Values
Method Detail

child

Location child(String child)
Returns an StpLocation whose name field is the name field of this StpLocation extended by the given child segment. All other fields are the same as the fields of this StpLocation. For repository-path-scheme locations, the repo field is extended rather than the name field.

Unlike most of the other methods of this class, the child() method encodes the new child segment according to the requirements of the scheme. Thus, this method may be used to add only one segment at a time to the StpLocation. In any scheme, any embedded segment delimiters in the child segment will be encoded to make them part of the segment.

Even if this method successfully returns an StpLocation, there is no guarantee that the returned location is a valid resource location. The returned location may be invalid even if the original location was valid. Some resources simply do not have parents even though their location suggests that they do.

For example, field:Defect/Headline@7.0.0.0/SAMPL is the location for the description of the Headline field of the Defect record type in the sample ClearQuest database. However, its parent location, field:Defect@7.0.0.0/SAMPL, is not a valid location. While this may seem to address the Defect record type resource, it does not. The location for the Defect record type resource is, in fact, record:Defect@7.0.0.0/SAMPL, which is in a different namespace from the parent of the field description resource.

In general, clients are discouraged from manipulating locations to traverse the object model. They should use the properties defined for this purpose instead. If, for example, the client wants to traverse from a field description to the record type of that field, then it should use the RECORD_TYPE property of the field rather than taking the parent and changing the namespace. Note that if the field location is a stable-selector scheme location, simply changing the namespace of the parent will not work.

Specified by:
child in interface Location
Parameters:
child - The new segment to be appended to the name field of this StpLocation. To be consistent with the Location.child method, it is assumed that the String is not yet encoded. It will be encoded as a single segment before adding it to the name field.
Returns:
A new StpLocation with an extended name field.

equals

boolean equals(Object arg0)
Overrides:
equals in class Object
See Also:
Object.equals(java.lang.Object)

forClass

StpLocation forClass(Class<? extends Resource> proxyClass)
                     throws WvcmException
Constructs a location suitable for addressing resources of the type indicated by the supplied proxy class by filling in unspecified fields of this location using provider-defined or resource-type-dependent defaults.

Note, when an StpLocation object is passed to a Provider proxy factory method this forClass is implicitly invoked using the Class of the proxy returned by the proxy factory method. Similarly, when an StpLocation is passed to a method of a proxy, that method implicitly invokes forClass using a proxy class deduced from the host proxy and the operation.

Clients need to use this method only if they want to complete/verify a location used in some other context or more tightly than can be determined from the proxy context.

Parameters:
proxyClass - The Class object for the proxy interface for which this location is to be completed.
Returns:
An StpLocation suitable for use with a proxy of the given class. The result will be this location if it is already suitable and a new StpLocation if not; will never be null.
Throws:
WvcmException - if it is not possible to complete the location from available defaults or if the completed location is inappropriate in some other (obvious) way, such as having a domain or namespace inconsistent with the given class.

getCanonicalPath

String getCanonicalPath()
                        throws StpException
Interprets this StpLocation as a file-path-scheme location and returns the canonical pathname for the file. If this StpLocation is not a file-path-scheme location, the original location specification used to construct this StpLocation is used as the pathname to be canonicalized.

For a location in the FILE namespace, this method constructs a URI from the given file-scheme URL and then constructs a java.io.File from that URI. Whether or not this succeeds depends on the JVM. (IBM's JVM 1.4.2, for example, requires that the authority portion be empty.)

Returns:
The canonicalized pathname for this resource. Will never be null.
Throws:
StpException - if IO errors are encountered while determining the canonical path or converting the file-scheme URL to a File.
See Also:
File.getCanonicalPath()

getDomain

StpProvider.Domain getDomain()
Returns the domain specified or implied by the selector. In URL-path-scheme locations this field is optional and will be NONE if no domain information is available. In the other formats, the value NONE denotes the default domain.

Returns:
Returns the StpProvider.Domain. Will never be null, but may be NONE or INVALID.

getExtendedNamespace

StpLocation.ExtendedNamespace getExtendedNamespace()
Returns an ExtendedNamespace object that, for some namespaces, contains additional information about the namespace field beyond its Namespace value.

Returns:
For a REPO, FAST, or OID namespace, the ExtendedNamespace specifies the resource type segment that is associated with it; for an INVALID namespace, the ExtendedNamespace object specifies the misspelled namespace field; for other namespaces, no additional information is available. Will not be null.

getFile

File getFile()
             throws java.net.MalformedURLException,
                    StpException
Returns a File object that references the path defined by this StpLocation. If this StpLocation is not a file-path-scheme location, the original location specification used to construct this StpLocation is used as the pathname from which the java.io.File object is constructed.

For a location in the FILE namespace, this method constructs a URI from the given URL and then constructs a java.io.File from that URI. Whether or not this succeeds depends on the JVM. (IBM's JVM 1.4.2, for example, requires that the authority portion be undefined.)

Returns:
A File object for the path defined by this StpLocation; Will never be null.
Throws:
java.net.MalformedURLException - if the selector is a file scheme URL for which a File cannot be constructed.
StpException
IllegalStateException - If isFilePathScheme() is false.

getName

String getName()
Returns the object name field specified for this location. This field is relevant and meaningful in all schemes except the repository-path scheme. In a repository-path scheme, it will be an empty Sting. The encoding of the returned String is unchanged from the original input.

Returns:
An empty string for a repository-path-scheme location; otherwise the object name field of an object selector or the pathname of a path-scheme location. Will be never be null, but may be empty.

getNameSegmentCount

int getNameSegmentCount()
The number of segments in the object name.

Returns:
The length of the Sting array returned by getNameSegments(Integer.MAX_VALUE).

getNameSegments

String[] getNameSegments(int nSegs)
Returns the first N segments of the name field of this location specification. If the requested number of segments is greater than the number in the name field, the entire name is returned; if zero or less, an empty array is returned.

Constructs a String array containing the segments of the given field. The elements of the array are the character sequences that preceded each segment delimiter plus the character sequence at the end of the field not followed by a delimiter as long as it is not empty. Thus, the array is empty if the field is empty; otherwise, the array has N+1 segments, where N is the number of segment delimiters in the field not counting the last delimiter if it appears at the end of the field.

The following examples illustrate the way a field is segmented.

  "" ==> {}
  "fob/bar" ==> {"fob", "bar"}
  "fob/" ==> {"fob"}
  "fob" ==> {"fob"}
  "/fob" ==> {"", "fob"}
  "/" ==> {""}
  "//" ==> {"", ""}
  "fob//bar" ==> {"fob", "", "bar"}
  "http://server" ==> {"http:", "", "server"}
  "http://" ==> {"http:", ""}
  "file:///" ==> {"file", "", ""}
 
Note that a trailing segment delimiter is "lost" only if it follows a non-empty segment. Consequently, when reconstructing the field from the array, segment delimiters should be inserted between each array element and a trailing delimiter should be added only if the last segment is empty.

Note: The returned segments are encoded just as they were on input to the constructor. Any escape characters present in the field on input remain in each returned segment. Only the unescaped segment delimiters have been removed from the input field.

Parameters:
nSegs - the number of segments to return
Returns:
a String array containing the first nSegs segments of the name field of this StpLocation.

getNameSegments

String[] getNameSegments(int firstSeg,
                         int lastSeg)
Returns contiguous segments of the name field of this selector. Segments returned are in the intersection of the specified range and the actual range of name segments. The first segment is at index zero.

Note: The returned segments are encoded just as they were on input to the constructor. Any escape characters present in the field on input remain in each returned segment. Only the unescaped segment delimiters have been removed from the input field.

Parameters:
firstSeg - the first segment to include
lastSeg - the last segment to include
Returns:
the requested segments of the object name. Will never be null, but may be empty if the specified range includes none of the segments of the name field.

getNamespace

StpLocation.Namespace getNamespace()
Returns the StpLocation.Namespace of this selector.

The special Namespace.INVALID indicates that the namespace field was present but spelled different from any namespace known to the library.

The special Namespace.DEFAULT indicates that the namespace field was present but empty, indicating that the default namespace ought to be used.

The special Namespace.NONE indicates that the namespace field was not present (i.e. there was no ':' in the specification before the first occurrence of a character not allowed in a scheme prefix), making it quite likely that this is a file selector.

Namespace.HTTP, Namespace.HTTPS, and Namespace.FILE indicate that the selector used the URI/URL syntax, the entirety of which is present in the name property.

Namespace.PNAME indicates that the selector used the PNAME namespace prefix. The file pathname following the PNAME prefix is the value of the name field.

See the complete list of possible namespaces in the Namespace enum specification.

Returns:
The namespace used in this location specification as a Namespace object. This will never be null.

getRepo

String getRepo()
Returns the repository field of this location specification. This field is irrelevant and empty in any path scheme location that does not have a repository field. Conversely, if this location specification specified a repository, it will be in this field.

Returns:
An empty string if there was no repository field found in the location specification; otherwise the image of the repository field (without a repository field delimiter).

getRepoSegmentCount

int getRepoSegmentCount()
The number of segments in the repository name.

Returns:
The length of the String array returned by getRepoSegments(Integer.MAX_VALUE).

getRepoSegments

String[] getRepoSegments(int nSegs)
Returns the first N segments of the repository field of this location. If the requested number of segments is greater than the number in the repository name, the entire repository name is returned; if zero or less, an empty array is returned.

Note: The returned segments are encoded just as they were on input to the constructor. Any escape characters present in the field on input remain in each returned segment. Only the unescaped segment delimiters have been removed from the input field.

Parameters:
nSegs - the number of segments to return
Returns:
a String containing the first nSegs segments of the repository name.
See Also:
for a description of how segments are parsed and counted.

getRepoSegments

String[] getRepoSegments(int firstSeg,
                         int lastSeg)
Returns contiguous segments of the repository name of this location. Segments returned are in the intersection of the specified range and the actual range of name segments. The first segment is at index zero.

Note: The returned segments are encoded just as they were on input to the constructor. Any escape characters present in the field on input remain in each returned segment. Only the unescaped segment delimiters have been removed from the input field.

Parameters:
firstSeg - the first segment to include
lastSeg - the last segment to include
Returns:
the requested segments of the repository name. Will never be null, but may be empty if the specified range includes none of the segments of the name.

getResourceType

String getResourceType()
Returns the resource type field of a location specification if it used a compound namespace.

Returns:
The resource type segment of this StpLocation. This field is defined only for compound namespace locations (i.e. those that use Namespace.REPO, Namespace.FAST, or Namespace.OID). It will be an empty string otherwise.

hashCode

int hashCode()
Uses the hash code of the composed String image

Overrides:
hashCode in class Object
See Also:
Object.hashCode()

isFastSelectorScheme

boolean isFastSelectorScheme()
Returns whether or not this location uses an object selector scheme with a compound FAST namespace. Its name and repository fields are densely encoded for greater stability and more efficient retrieval.

Returns:
true if the location uses the FAST namespace; false otherwise.

isFilePathScheme

boolean isFilePathScheme()
Returns whether or not this location is specified using the file path- scheme format. In this format, the resource location is specified in the name field of this StpLocation as a segmented pathname (using native file system encoding conventions) to a file system object, perhaps extended by a ClearCase history-mode selector. The variant of the file path location format used in the specification of this StpLocation is indicated by the value of getNamespace().

Note that this and the other predicates are purely syntactic. The user may have intended to name a file, but if it so happens that its name looks exactly like a valid object selector, it will be parsed and classified as an object selector. isObjectSelectorScheme() will be true not isFilePathScheme(). Clients wishing to interpret a location as a file path location, may always use the getFile() or getCanonicalPath() methods to investigate that option further. If this StpLocation isn't in the FILE or PNAME namespace, these methods will use the original input in its entirety as the intended pathname.

Similarly, recomposeWithNamespace(Namespace.PNAME) will "do the right thing" and force the original input into an explicit file path selector. Note, however, that in this case, the image of that StpLocation will include the "pname:" prefix.

Returns:
true if this selector is most likely a pathname to a file system object, false if there is a more likely interpretation.

isHistoryModeScheme

boolean isHistoryModeScheme()
Returns whether or not this file-path scheme location uses the optional ClearCase history-mode naming syntax.

Returns:
true if the name segment of this location contains history-mode naming syntax.

isObjectSelectorScheme

boolean isObjectSelectorScheme()
Returns whether or not this location uses either a stable, fast (efficient), or user-friendly object selector scheme. Locations using the object selector format have a pre-defined namespace and separate name and repository fields.

Returns:
true if this location uses the object selector format; false otherwise, in which case it uses either a path scheme.

isOidSelectorScheme

boolean isOidSelectorScheme()
Returns whether or not this location uses an object selector scheme with a compound OID namespace. Its name and repository fields are densely encoded for greater stability and more efficient retrieval.

Returns:
true if the location uses the OID namespace; false otherwise.

isOk

boolean isOk()
Overall status of this StpLocation

Returns:
true if all required fields were found in the given location specification.

isPathScheme

boolean isPathScheme()
Returns whether or not this location is specified using a pathname format. Such locations specify a location as a segmented pathname following an explicit scheme prefix:

[domain .] namespace : segmented-path.

The segmented-path is the value of either the name field or the repo field of this StpLocation and the other field is not used and empty. The segmented path is stored in the name field unless the predicate isRepositoryPathScheme() is also true.

Included in this scheme classification are the location specifications that are not complete enough to classify more precisely; i.e. it includes the locations with the following special Namespace values.

Returns:
true if this is a path-scheme location; false otherwise

isRepoSelectorScheme

boolean isRepoSelectorScheme()
Returns whether or not this location uses an object selector scheme with a compound REPO namespace. Its name and repository fields are densely encoded for greater stability and more efficient retrieval.

Returns:
true if the location uses the REPO namespace; false otherwise.

isRepositoryPathScheme

boolean isRepositoryPathScheme()
Returns whether or not this location specifies a repository using a path- scheme format. Such locations have a repository field specified as a segmented pathname (un-encoded). A repository path-scheme is a specialized form of path-scheme in which the path is found in the repo field of the StpLocation object. For all other forms of path-location the path is found in the name field of the StpLocation object.

Returns:
true if this is a repository path-location; false otherwise

isUrlPathScheme

boolean isUrlPathScheme()
Returns whether or not this location is specified using the URL path- scheme format. Such locations are formatted as standards-conforming URLs (URL-encoded). The entire URL, including the scheme-prefix of the URL, such as "http:" or "file:" is included in the name field of the StpLocation object. An optional domain field is permitted before the scheme-prefix, but it is not included in the name field. A URL path scheme is a specialized form of path scheme. The URL could designate a server, a repository, or a resource inside or outside of a repository. The URL is stored in the repo field if isRepositoryPathScheme() is true; otherwise it is stored in the name field.

Returns:
true if this is a URL path-location; false otherwise

isUserFriendlySelectorScheme

boolean isUserFriendlySelectorScheme()
Returns whether or not this location uses an object selector scheme with user-friendly namespace, name, and repository fields.

Returns:
true if this is an object name selector; false otherwise.

lastSegment

String lastSegment()
Returns the last segment of the name field of this StpLocation. (Returns the last segment of the repo field for repository-path-scheme locations.) Any encoding used within the last segment is removed before returning a value. Thus it's the case that loc.equals(loc.parent().child(loc.lastSegment())) as long as loc.parent() is not null.

At the root of the namespace (parent() returns <null>), returns either the name of the root or the empty string if the root is unnamed. These examples illustrate the edge cases

      StpLocation        | lastSegment | parent        
      -------------------+-------------+------------- 
      /food              |   food      | /   
      /                  |  <empty>    | <null>       
      pname:/food        |   food      | pname:/
      http://server/path |   path      | http://server
      file://author/path |   path      | file://author
      http://server      |  <empty>    | <null>
      file://author      |  <empty>    | <null>
      pname:path         |   path      | <null>
      pname:/            |  <empty>    | <null>
      pname:\            |  <empty>    | <null>
      record:food@cq:s/u |   food      | record:@cq:s/u
      record:@cq:s/u     |  <empty>    | <null>
 

Specified by:
lastSegment in interface Location
Returns:
A String containing the last segment of the name field of this StpLocation stripped of all encodings. Will never be null, but may be empty if the last segment is unnamed.

parent

Location parent()
Returns an StpLocation whose segmented name field is one segment shorter than the name field of this StpLocation provided the name field of the resulting StpLocation would be valid. All other fields of the StpLocation are left unchanged.

NOTE: For repository-path scheme locations this method operates on the segmented repo field rather than the name field. But in all other respects the behavior is the same.

For object-selector scheme locations, an empty name field is valid, but for path-scheme locations, the name/repo field is valid only if it contains at least one segment of the original path (even if that segment is empty). These examples illustrate the edge cases

      StpLocation        |    Parent        
      -------------------+---------------
      /food              | /        
      vob:/food          | vob:/      
      http://server/path | http://server 
      file://author/path | file://author 
      http://server      | <null> 
      file://author      | <null> 
      pname:path         | <null>      
      file:/             | <null>      
 

Specified by:
parent in interface Location
Returns:
A new StpLocation instance; will be null if the name field of this StpLocation has no segments that can be removed.

recomposeAsPname

StpLocation recomposeAsPname(boolean withPrefix,
                             StpProvider.Domain domain)
                             throws StpException
Constructs an StpLocation for a pname based on the image of this StpLocation. The StpLocation can be constructed with or without a pname prefix and can be assigned a StpProvider.Domain.

In most cases, the entire image of this StpLocation (as returned by toString()) becomes the value of the name field of the returned StpLocation even if that image includes a namespace and/or a domain prefix. The domain prefix can be elided from the name field of the new location by using null for the domain argument to this method.

To convert any ill-formed selector to an implied pname, the following logic might be used

 if (!myLoc.isOk()) {
      // Convert to an implied pname so that it prints as it was
      // entered, but is treated internally as an OK file path selector
      myLoc = myLoc.recomposeAsPname(false, MY_DOMAIN);
 }
 

To convert any input not already formatted as a file-path-scheme location to an explicit pname, the following logic might be used

 if (!(myLoc.isFilePathScheme() && myLoc.isOk())) {
      myLoc = myLoc.recomposeAsPname(true, MY_DOMAIN);
 }
 

To convert all input to an implied pname, the following logic might be used

  if (myLoc.getNamespace() == Namespace.PNAME) {
      // Keep the original "pname:" prefix out of the implied pname
      // Preserve any domain data from the input. 
      myLoc = myLoc.recomposeWithNamespace(Namespace.PNAME_IMPLIED);
  } else if (myLoc.getNamespace() == Namespace.FILE) {
      // Remove any domain info from the "file:" prefix, but push the
      // rest of the "file:" prefix into the pname.
      myLoc = myLoc.recomposeAsPname(false, null);
  } else {
      // All other input not using an explicit pname: or file: prefix is
      // treated as a raw pname.
      myLoc = myLoc.recomposeAsPname(false, MY_DOMAIN);
  }
  
  // Set the domain type if not already specified.
  if (myLoc.getDomain() == Domain.NONE)
      myLoc = recomposeWithType(MY_DOMAIN);
 

Parameters:
withPrefix - if true, the namespace of the returned StpLocation will be Namespace.PNAME; if false, the namespace will be Namespace.PNAME_IMPLIED.
domain - The StpProvider.Domain of the returned StpLocation. If null the StpProvider.Domain of the current StpLocation will be used and the image of that domain will be elided from the pname.
Returns:
An StpLocation reconfigured as a Pname instance, explicit or implied as requested
Throws:
StpException

recomposeWithDomain

StpLocation recomposeWithDomain(StpProvider.Domain domain)
                                throws StpException
Constructs a new location based on this location with a replacement for its domain field.

Parameters:
domain - The new domain for the selector. If null, the current value of getDomain() is used.
Returns:
An StpLocation composed from the current namespace, name, and repo fields and the specified domain argument.
Throws:
StpException - Thrown if the given selector String is not in the correct form. StpReasonCode=INVALID_OBJECT_SELECTOR

recomposeWithMods

StpLocation recomposeWithMods(Object namespace,
                              String name,
                              StpProvider.Domain domain,
                              String repo)
                              throws StpException
Constructs an StpLocation object based on the fields of this StpLocation with optional replacements for some of the fields. A null argument generally means to use the corresponding field of this StpLocation in the new StpLocation.

NOTE: This method does not change the host StpLocation object. But constructs and returns a new instance of StpLocation.

Parameters:
namespace - The namespace for the new location expressed either as an ExtendedNamespace object, a Namespace enumeration or as a String containing the resource type of a REPO namespace. If namespace is Namespace.NONE no namespace prefix is generated for the selector. If namespace is null, the current value of getExtendedNamespace() is used.
name - The name field of the new selector. If null, the current value of getName() is used.
domain - The StpProvider.Domain for the new selector. If null, the current value of getDomain() is used.
repo - The repository field for the new selector. If null, the current value of getRepo() is used. Must be null for path-path scheme locations that are not repository-path-schemes. If empty, no repository field will be generated for the selector.
Returns:
A new StpLocation composed from the current namespace, name, type and repo fields, optionally overwritten by the given arguments.
Throws:
StpException - Thrown if the given selector String is not in the correct form. StpReasonCode=INVALID_OBJECT_SELECTOR

recomposeWithName

StpLocation recomposeWithName(String name)
                              throws StpException
Constructs a new location based on this location with a replacement for its name field.

Parameters:
name - The new selector name field. If null, the current value of name() is used.
Returns:
The selector composed from the current namespace, domain and repo fields and the specified name argument.
Throws:
StpException - Thrown if the given selector String is not in the correct form. StpReasonCode=INVALID_OBJECT_SELECTOR

recomposeWithNamespace

StpLocation recomposeWithNamespace(StpLocation.Namespace namespace)
                                   throws StpException
Constructs new location based on this location but with a replacement for its namespace field.

Parameters:
namespace - The namespace for the new StpLocation. If namespace is Namespace.NONE, no namespace prefix is generated for the selector. If namespace is null, the current value of Namespace is used, effectively cloning this StpLocation object.
Returns:
An StpLocation composed from the current name, domain and repo fields and the specified namespace argument.
Throws:
StpException - if the given selector String is not in the correct form. StpReasonCode=INVALID_OBJECT_SELECTOR

recomposeWithRepo

StpLocation recomposeWithRepo(String repo)
                              throws StpException
Constructs a new location based on this location with a replacement for its repository field.

Parameters:
repo - The new repository field for the location. If null, the current value of getRepo() is used. If empty, no repository field will be generated for the location.
Returns:
An StpLocation composed from the current namespace, name, and domain fields and the specified repo argument.
Throws:
StpException - Thrown if the given selector String is not in the correct form. StpReasonCode=INVALID_OBJECT_SELECTOR

recomposeWithResourceType

StpLocation recomposeWithResourceType(String rType)
                                      throws StpException
Constructs an object selector with a replacement for its resource type field, forcing the namespace to REPO.

Parameters:
rType - The resource type for the new location. If null, the current value of getResourceType() is used.
Returns:
A stable-selector scheme StpLocation composed from the current name, repo and domain fields and the specified resource type.
Throws:
StpException - Thrown if the given selector String is not in the correct form. StpReasonCode=INVALID_OBJECT_SELECTOR

status

StpException status()
Generates an StpException object that reports the state of this StpLocation.

Returns:
An StpException whose message reports the state of this StpLocation. Will be null if this StpLocation is valid.

stpProvider

StpProvider stpProvider()
Returns the StpProvider object that created this StpLocation object

Returns:
The StpProvider object that instantiated this instance of StpLocation

throwIfNotOk

void throwIfNotOk()
                  throws StpException
Throws an INVALID_OBJECT_SELECTOR StpException if this StpLocation does not reflect a syntactically complete and correct location specification.

Throws:
StpException - if any required fields are missing from the StpLocation specification.

toString

String toString()
Reconstitutes the location specification from its component fields.

Overrides:
toString in class Object
Returns:
For a valid StpLocation, a syntactically correct location specification string composed from the current values for the namespace, name, domain, and repo fields; otherwise the location specification as passed to the constructor.
See Also:
Object.toString()

toStringWithoutDomain

String toStringWithoutDomain()
As above, but returns a location string without the domain prefix.


Generated Thu 17-Apr-2014 03:22 PM

Copyright © IBM 2014. All rights reserved.