|
Project: stp | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface StpLocation
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...
%-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 |
---|
static final String DELIMITERS
static final String ESCAPE_CHAR
static final String FIELD_DELIMITERS
static final String SEGMENT_DELIMITERS
Method Detail |
---|
Location child(String child)
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.
child
in interface Location
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.
boolean equals(Object arg0)
equals
in class Object
Object.equals(java.lang.Object)
StpLocation forClass(Class<? extends Resource> proxyClass) throws WvcmException
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.
proxyClass
- The Class object for the proxy interface for which this
location is to be completed.
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.String getCanonicalPath() throws StpException
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.)
StpException
- if IO errors are encountered while determining the
canonical path or converting the file-scheme URL to a File.File.getCanonicalPath()
StpProvider.Domain getDomain()
NONE
or INVALID
.StpLocation.ExtendedNamespace getExtendedNamespace()
File getFile() throws java.net.MalformedURLException, StpException
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.)
java.net.MalformedURLException
- if the selector is a file scheme URL for
which a File cannot be constructed.
StpException
IllegalStateException
- If isFilePathScheme()
is false.String getName()
int getNameSegmentCount()
getNameSegments(Integer.MAX_VALUE)
.String[] getNameSegments(int nSegs)
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.
nSegs
- the number of segments to return
String[] getNameSegments(int firstSeg, int lastSeg)
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.
firstSeg
- the first segment to includelastSeg
- the last segment to include
StpLocation.Namespace getNamespace()
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.
String getRepo()
int getRepoSegmentCount()
getRepoSegments(Integer.MAX_VALUE)
.String[] getRepoSegments(int nSegs)
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.
nSegs
- the number of segments to return
for a description of how segments are parsed
and counted.
String[] getRepoSegments(int firstSeg, int lastSeg)
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.
firstSeg
- the first segment to includelastSeg
- the last segment to include
String getResourceType()
int hashCode()
hashCode
in class Object
Object.hashCode()
boolean isFastSelectorScheme()
boolean isFilePathScheme()
getFile()
or canonical path via
getCanonicalPath()
will first use the java.net.URI class to
parse the file URL.
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.
true
if this selector is most likely a
pathname to a file system object, false
if
there is a more likely interpretation.boolean isHistoryModeScheme()
boolean isObjectSelectorScheme()
boolean isOidSelectorScheme()
boolean isOk()
boolean isPathScheme()
[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.
boolean isRepoSelectorScheme()
boolean isRepositoryPathScheme()
boolean isUrlPathScheme()
isRepositoryPathScheme()
is
true; otherwise it is stored in the name field.
boolean isUserFriendlySelectorScheme()
String lastSegment()
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>
lastSegment
in interface Location
Location parent()
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>
parent
in interface Location
StpLocation recomposeAsPname(boolean withPrefix, StpProvider.Domain domain) throws StpException
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);
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.
StpException
StpLocation recomposeWithDomain(StpProvider.Domain domain) throws StpException
domain
- The new domain for the selector. If null, the
current value of getDomain() is used.
StpException
- Thrown if the given selector String is not in the
correct form. StpReasonCode=INVALID_OBJECT_SELECTORStpLocation recomposeWithMods(Object namespace, String name, StpProvider.Domain domain, String repo) throws StpException
NOTE: This method does not change the host StpLocation object. But constructs and returns a new instance of StpLocation.
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.
StpException
- Thrown if the given selector String is not in the
correct form. StpReasonCode=INVALID_OBJECT_SELECTORStpLocation recomposeWithName(String name) throws StpException
name
- The new selector name field. If null, the current value of
name() is used.
StpException
- Thrown if the given selector String is not in the
correct form. StpReasonCode=INVALID_OBJECT_SELECTORStpLocation recomposeWithNamespace(StpLocation.Namespace namespace) throws StpException
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.
StpException
- if the given selector String is not in the
correct form. StpReasonCode=INVALID_OBJECT_SELECTORStpLocation recomposeWithRepo(String repo) throws StpException
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.
StpException
- Thrown if the given selector String is not in the
correct form. StpReasonCode=INVALID_OBJECT_SELECTORStpLocation recomposeWithResourceType(String rType) throws StpException
rType
- The resource type for the new location. If null, the
current value of getResourceType() is used.
StpException
- Thrown if the given selector String is not in the
correct form. StpReasonCode=INVALID_OBJECT_SELECTORStpException status()
StpProvider stpProvider()
void throwIfNotOk() throws StpException
StpException
- if any required fields are missing from the
StpLocation specification.String toString()
toString
in class Object
Object.toString()
String toStringWithoutDomain()
|
Generated Tue 13-Sep-2011 04:07 PM | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |