|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
@Immutable public interface Path
An object representation of a node path within a repository.
A path consists of zero or more segments that can contain any characters, although the string representation may require some
characters to be encoded. For example, if a path contains a segment with a forward slash, then this forward slash must be
escaped when writing the whole path to a string (since a forward slash is used as the delimiter
between
segments).
Because of this encoding and decoding issue, there is no standard representation of a path as a string. Instead, this class
uses text encoders
to escape certain characters when writing to a string or unescaping the string
representation. These encoders and used only with individual segments, and therefore are not used to encode the
delimiter
. Three standard encoders are provided, although others can certainly be used:
Jsr283Encoder
- an encoder and decoder that is compliant with JSR-283 by converting the reserved characters (namely '*', '/', ':', '[', ']'
and '|') to their unicode equivalent.
UrlEncoder
- an encoder and decoder that is useful for converting text to be used within a URL, as
defined by Section 2.3 of RFC 2396. This encoder does encode many characters
(including '`', '@', '#', '$', '^', '&', '{', '[', '}', ']', '|', ':', ';', '\', '"', '<', ',', '>', '?', '/', and ' '), while
others are not encoded (including '-', '_', '.', '!', '~', '*', '\', ''', '(', and ')'). Note that only the '*' character is
the only character reserved by JSR-283 that is not encoded by the URL encoder.NoOpEncoder
- an encoder
implementation that does nothing.
This class simplifies working with paths and using a Path
is often more efficient that processing and
manipulating the equivalent String
. This class can easily iterate
over the segments, return
the number of segments
, compare
with other paths, resolve
relative paths, return the ancestor (or parent)
, determine whether one path is an
ancestor
or decendent
of another path, and
finding a common ancestor
.
Nested Class Summary | |
---|---|
static interface |
Path.Segment
Representation of the segments that occur within a path. |
Field Summary | |
---|---|
static TextDecoder |
DEFAULT_DECODER
The default text decoder to be used when none is otherwise specified. |
static TextEncoder |
DEFAULT_ENCODER
The default text encoder to be used when none is otherwise specified. |
static char |
DELIMITER
The delimiter character used to separate segments within a path. |
static String |
DELIMITER_STR
String form of the delimiter used to separate segments within a path. |
static TextDecoder |
JSR283_DECODER
The text decoder that decodes according to JSR-283. |
static TextEncoder |
JSR283_ENCODER
The text encoder that encodes according to JSR-283. |
static int |
NO_INDEX
The index that will be returned for a Path.Segment that has no index . |
static TextDecoder |
NO_OP_DECODER
The text decoder that does nothing. |
static TextEncoder |
NO_OP_ENCODER
The text encoder that does nothing. |
static String |
PARENT
String representation of the segment that references a parent. |
static Name |
PARENT_NAME
Singleton instance of the name referencing a parent, provided as a convenience. |
static Path.Segment |
PARENT_SEGMENT
Singleton instance of the path segment referencing a parent, provided as a convenience. |
static String |
SELF
String representation of the segment that references the same segment. |
static Name |
SELF_NAME
Singleton instance of the name referencing a self, provided as a convenience. |
static Path.Segment |
SELF_SEGMENT
Singleton instance of the path segment referencing a parent, provided as a convenience. |
static TextDecoder |
URL_DECODER
The text decoder that decodes text according to the rules of RFC 2396. |
static TextEncoder |
URL_ENCODER
The text encoder that encodes text according to the rules of RFC 2396. |
Method Summary | |
---|---|
Path |
getAncestor(int degree)
Return the path to the ancestor of the supplied degree. |
Path |
getCanonicalPath()
Get the canonical form of this path. |
Path |
getCommonAncestor(Path that)
Find the lowest common ancestor of this path and the supplied path. |
Path.Segment |
getLastSegment()
Get the last segment in this path. |
Path |
getNormalizedPath()
Get a normalized path with as many ".." segments and all "." resolved. |
Path |
getParent()
Return the path to the parent, or this path if it is the root . |
Path.Segment |
getSegment(int index)
Get the segment at the supplied index. |
Path.Segment[] |
getSegmentsArray()
Obtain a copy of the segments in this path. |
List<Path.Segment> |
getSegmentsList()
Get an unmodifiable list of the path segments. |
String |
getString()
Get the string form of the path. |
String |
getString(NamespaceRegistry namespaceRegistry)
Get the string form of the path, using the supplied namespace registry to convert the names' namespace URIs to prefixes. |
String |
getString(NamespaceRegistry namespaceRegistry,
TextEncoder encoder)
Get the encoded string form of the path, using the supplied namespace registry to convert the names' namespace URIs to prefixes and the supplied encoder to encode characters in each of the path segments. |
String |
getString(NamespaceRegistry namespaceRegistry,
TextEncoder encoder,
TextEncoder delimiterEncoder)
Get the encoded string form of the path, using the supplied namespace registry to convert the names' namespace URIs to prefixes and the supplied encoder to encode characters in each of the path segments. |
String |
getString(TextEncoder encoder)
Get the encoded string form of the path, using the supplied encoder to encode characters in each of the path segments. |
boolean |
hasSameAncestor(Path that)
Determine whether this path and the supplied path have the same immediate ancestor. |
boolean |
isAbsolute()
Return whether this path is an absolute path. |
boolean |
isAncestorOf(Path decendant)
Determine whether this path is an ancestor of the supplied path. |
boolean |
isAtOrAbove(Path other)
Determine whether this path is the same as to or a ancestor of the
supplied path. |
boolean |
isAtOrBelow(Path other)
Determine whether this path is the same as to or a decendant of the
supplied path. |
boolean |
isDecendantOf(Path ancestor)
Determine whether this path is an decendant of the supplied path. |
boolean |
isNormalized()
Return whether this path is normalized and contains no "." segments and as few ".." segments as possible. |
boolean |
isRoot()
Return whether this path represents the root path. |
boolean |
isSameAs(Path other)
Determine whether this path represents the same as the supplied path. |
Iterator<Path.Segment> |
iterator()
|
Path |
relativeTo(Path startingPath)
Get a relative path from the supplied path to this path. |
Path |
resolve(Path relativePath)
Get the absolute path by resolving the supplied relative (non-absolute) path against this absolute path. |
Path |
resolveAgainst(Path absolutePath)
Get the absolute path by resolving this relative (non-absolute) path against the supplied absolute path. |
int |
size()
Return the number of segments in this path. |
Path |
subpath(int beginIndex)
Return a new path consisting of the segments starting at beginIndex index (inclusive). |
Path |
subpath(int beginIndex,
int endIndex)
Return a new path consisting of the segments between the beginIndex index (inclusive) and the endIndex
index (exclusive). |
Methods inherited from interface java.lang.Comparable |
---|
compareTo |
Field Detail |
---|
static final TextEncoder NO_OP_ENCODER
static final TextEncoder JSR283_ENCODER
static final TextEncoder URL_ENCODER
static final TextDecoder NO_OP_DECODER
static final TextDecoder JSR283_DECODER
static final TextDecoder URL_DECODER
static final TextEncoder DEFAULT_ENCODER
JSR-283
encoder
.
static final TextDecoder DEFAULT_DECODER
JSR-283
encoder
.
static final char DELIMITER
static final String DELIMITER_STR
static final String PARENT
static final String SELF
static final int NO_INDEX
Path.Segment
that has no index
.
static final Name SELF_NAME
static final Name PARENT_NAME
static final Path.Segment SELF_SEGMENT
static final Path.Segment PARENT_SEGMENT
Method Detail |
---|
int size()
boolean isRoot()
boolean isSameAs(Path other)
this.compareTo(other) == 0
.
other
- the other path to compare with this path; may be null
boolean isAtOrAbove(Path other)
same as
to or a ancestor of
the
supplied path. This method is equivalent to (but may be more efficient than) calling isSame(other) ||
isAncestor(other)
, and is a convenience method that is identical to calling other.isAtOrBelow(this)
.
other
- the other path to compare with this path; may be null
boolean isAtOrBelow(Path other)
same as
to or a decendant of
the
supplied path. This method is equivalent to (but may be more efficient than) calling isSame(other) ||
isAncestor(other)
.
other
- the other path to compare with this path; may be null
boolean isAncestorOf(Path decendant)
decendant
- the path that may be the decendant; may be null
boolean isDecendantOf(Path ancestor)
ancestor
- the path that may be the ancestor; may be null
boolean isAbsolute()
absolute
. An absolute path
starts with a "/".
boolean isNormalized()
Path getNormalizedPath()
InvalidPathException
- if the normalized form would result in a path with negative length (e.g., "/a/../../..")Path getCanonicalPath()
absolute
and isNormalized()
.
InvalidPathException
- if the path is not absolute and cannot be canonicalizedPath relativeTo(Path startingPath)
startingPath
- the path specifying the starting point for the new relative path; may not be null
IllegalArgumentException
- if the supplied path is null
PathNotFoundException
- if both this path and the supplied path are not absolutePath resolve(Path relativePath)
relativePath
- the relative path that is to be resolved against this path
IllegalArgumentException
- if the supplied path is null
InvalidPathException
- if the this path is not absolute or if the supplied path is not relative.Path resolveAgainst(Path absolutePath)
absolutePath
- the absolute path to which this relative path should be resolve
IllegalArgumentException
- if the supplied path is null
InvalidPathException
- if the supplied path is not absolute or if this path is not relative.Path getParent()
root
. This is an efficient operation that does
not require copying any data.
Path getAncestor(int degree)
x
is the path that is x
levels up along the path. For example, degree = 0
returns this path, while degree = 1
returns the parent of this path, degree = 2
returns the grandparent of this path, and so on. Note that the
result may be unexpected if this path is not normalized
, as a non-normalized path contains ".." and
"." segments.
degree
-
IllegalArgumentException
- if the degree is negative
InvalidPathException
- if the degree is greater than the length
of this pathboolean hasSameAncestor(Path that)
that
- the other path
IllegalArgumentException
- if the supplied path is nullPath getCommonAncestor(Path that)
that
- the other path
IllegalArgumentException
- if the supplied path is nullPath.Segment getLastSegment()
Path.Segment getSegment(int index)
index
- the index
IndexOutOfBoundsException
- if the index is out of boundsPath subpath(int beginIndex)
beginIndex
index (inclusive). This is equivalent to
calling path.subpath(beginIndex,path.size()-1)
.
beginIndex
- the beginning index, inclusive.
IndexOutOfBoundsException
- if the beginIndex
is negative or larger than the length of this
Path
objectPath subpath(int beginIndex, int endIndex)
beginIndex
index (inclusive) and the endIndex
index (exclusive).
beginIndex
- the beginning index, inclusive.endIndex
- the ending index, exclusive.
IndexOutOfBoundsException
- if the beginIndex
is negative, or endIndex
is larger than
the length of this Path
object, or beginIndex
is larger than endIndex
.Iterator<Path.Segment> iterator()
iterator
in interface Iterable<Path.Segment>
Path.Segment[] getSegmentsArray()
List<Path.Segment> getSegmentsList()
String getString()
default encoder
is used to encode characters in each of the
path segments.
getString(TextEncoder)
String getString(TextEncoder encoder)
encoder
- the encoder to use, or null if the default encoder
should be used
getString()
String getString(NamespaceRegistry namespaceRegistry)
default encoder
is used to encode characters in each of the path segments. The second encoder
is used to encode (or convert) the delimiter between the namespace prefix
and the
local part
.
namespaceRegistry
- the namespace registry that should be used to obtain the prefix for the
namespace URIs
in the segment names
IllegalArgumentException
- if the namespace registry is nullgetString(NamespaceRegistry,TextEncoder)
,
getString(NamespaceRegistry, TextEncoder, TextEncoder)
String getString(NamespaceRegistry namespaceRegistry, TextEncoder encoder)
namespaceRegistry
- the namespace registry that should be used to obtain the prefix for the
namespace URIs
in the segment names
encoder
- the encoder to use for encoding the local part
and
namespace prefix
of each segment
, or null if the
default encoder
should be used
IllegalArgumentException
- if the namespace registry is nullgetString(NamespaceRegistry)
,
getString(NamespaceRegistry, TextEncoder, TextEncoder)
String getString(NamespaceRegistry namespaceRegistry, TextEncoder encoder, TextEncoder delimiterEncoder)
namespaceRegistry
- the namespace registry that should be used to obtain the prefix for the
namespace URIs
in the segment names
encoder
- the encoder to use for encoding the local part
and
namespace prefix
of each segment
, or null if the
default encoder
should be useddelimiterEncoder
- the encoder to use for encoding the delimiter between the local part
and namespace prefix
of each segment
, and for encoding
the path delimiter, or null if the standard delimiters should be used
getString(NamespaceRegistry)
,
getString(NamespaceRegistry, TextEncoder)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |