public interface Path
extends java.io.Serializable
Path
interface defines the SPI level representation of
a JCR path. It consists of an ordered list of Path.Element
objects
and is immutable.
A Path.Element
is either named
or one of the following special elements:
current
element (Notation: "."),parent
element (Notation: ".."),root
element (Notation: {}), which can
only occur as the first element in a path, oridentifier
element, which can
only occur as the first element in a path.
A Path
is defined to have the following characteristics:
Equality:
Two paths are equal if they consist of the same elements.
Length:
The length
of a path is the number of its elements.
Depth:
The depth
of a path is
The depth of a normalized absolute path equals its length minus 1.
Absolute vs. Relative
A path can be absolute or relative:
A path is absolute
if its first element is the root
or an identifier element. A path is relative if it is not absolute.
Normalization:
A path P is normalized
if P has minimal length
amongst the set of all paths Q which are equivalent to P.
This means that '.' and '..' elements are resolved as much as possible.
An absolute path it is normalized if it is not identifier-based and
contains no current or parent elements. The normalization of a path
is unique.
Equivalence:
Path P is equivalent
to path Q (in the above sense)
if the normalization of P is equal to the normalization of Q. This is
an equivalence relation (i.e. reflexive, transitive,
and symmetric).
Canonical Paths:
A path is canonical
if its absolute and normalized.
Hierarchical Relationship:
The ancestor relationship is a strict partial order (i.e. irreflexive, transitive,
and asymmetric). Path P is a direct ancestor of path Q if P is equivalent to Q/..
Path P is an ancestor
of path Q if
Path P is an descendant
of path Q if
Modifier and Type | Interface and Description |
---|---|
static interface |
Path.Element
Object representation of a single JCR path element.
|
Modifier and Type | Field and Description |
---|---|
static char |
DELIMITER
Delimiter used in order to concatenate the Path.Element objects
upon
getString() . |
static int |
INDEX_DEFAULT
Constant representing the default (initial) index value.
|
static int |
INDEX_UNDEFINED
Constant representing an undefined index value
|
static int |
ROOT_DEPTH
Constant defining the depth of the root path
|
Modifier and Type | Method and Description |
---|---|
Path |
computeRelativePath(Path other)
Computes the relative path from
this absolute path to
other . |
boolean |
denotesCurrent()
Checks if the last path element is the current element (".").
|
boolean |
denotesIdentifier()
Test if this path consists of a single identifier element.
|
boolean |
denotesName()
Checks if the last path element is a named and optionally indexed
element.
|
boolean |
denotesParent()
Checks if the last path element is the parent element ("..").
|
boolean |
denotesRoot()
Tests whether this is the root path, i.e.
|
Path |
getAncestor(int degree)
Normalizes this path and returns the ancestor path of the specified
relative degree.
|
int |
getAncestorCount()
Returns the number of ancestors of this path.
|
Path |
getCanonicalPath()
Returns the canonical path representation of this path.
|
int |
getDepth()
Returns the depth of this path.
|
Path.Element[] |
getElements()
Returns the elements of this path.
|
Path |
getFirstElements()
Returns a path that consists of all but the last element of this path.
|
java.lang.String |
getIdentifier()
Returns the identifier of a single identifier element.
|
int |
getIndex()
Returns the index of the last path element, or
INDEX_UNDEFINED
if the index is not defined or not applicable. |
Path |
getLastElement()
Returns a path that consists of only the last element of this path.
|
int |
getLength()
Returns the length of this path, i.e.
|
Name |
getName()
Returns the name of the last path element, or
null
for an identifier. |
Path.Element |
getNameElement()
Returns the name element (i.e.
|
int |
getNormalizedIndex()
Returns the normalized index of the last path element.
|
Path |
getNormalizedPath()
Returns the normalized path representation of this path.
|
java.lang.String |
getString()
Returns the String representation of this Path as it is used
by
PathFactory.create(String) . |
boolean |
isAbsolute()
Tests whether this path is absolute, i.e.
|
boolean |
isAncestorOf(Path other)
Determines if this path is an ancestor of the specified path,
based on their (absolute or relative) hierarchy level as returned by
. |
boolean |
isCanonical()
Tests whether this path is canonical, i.e.
|
boolean |
isDescendantOf(Path other)
Determines if this path is a descendant of the specified path,
based on their (absolute or relative) hierarchy level as returned by
. |
boolean |
isEquivalentTo(Path other)
Determines if the the
other path would be equal to this
path if both of them are normalized. |
boolean |
isIdentifierBased()
Test if this path represents an unresolved identifier-based path.
|
boolean |
isNormalized()
Tests whether this path is normalized, i.e.
|
Path |
resolve(Path.Element element)
Resolves the given path element against this path.
|
Path |
resolve(Path relative)
Resolves the given path against this path.
|
Path |
subPath(int from,
int to)
Returns a new
Path consisting of those Path.Element objects
between the given from , inclusive, and the given to ,
exclusive. |
static final int INDEX_UNDEFINED
static final int INDEX_DEFAULT
static final int ROOT_DEPTH
static final char DELIMITER
getString()
.Name getName()
null
for an identifier. The names of the special root, current and parent
elements are "", "." and ".." in the default namespace.null
int getIndex()
INDEX_UNDEFINED
if the index is not defined or not applicable. The index of an
identifier or the special root, current or parent element is always
undefined.INDEX_UNDEFINED
int getNormalizedIndex()
INDEX_DEFAULT
.java.lang.String getIdentifier()
null
boolean denotesRoot()
true
if this is the root path,
false
otherwise.boolean denotesIdentifier()
true
if this path is an identifierboolean denotesParent()
true
if the last path element is the parent element,
false
otherwiseboolean denotesCurrent()
true
if the last path element is the current element,
false
otherwiseboolean denotesName()
true
if the last path element is a named element,
false
otherwiseboolean isIdentifierBased()
true
if this path represents an unresolved
identifier-based path.boolean isAbsolute()
boolean isCanonical()
isAbsolute()
boolean isNormalized()
Note that a normalized path can still contain ".." elements if they are not redundant, e.g. "../../a/b/c" would be a normalized relative path, whereas "../a/../../a/b/c" wouldn't (although they're semantically equivalent).
getNormalizedPath()
Path getNormalizedPath() throws RepositoryException
If the path cannot be normalized (e.g. if an absolute path is normalized that would result in a 'negative' path) a RepositoryException is thrown.
RepositoryException
- if the path cannot be normalized.isNormalized()
Path getCanonicalPath() throws RepositoryException
If the path is relative or cannot be normalized a RepositoryException is thrown.
RepositoryException
- if this path can not be canonicalized
(e.g. if it is relative).Path resolve(Path.Element element)
element
- path elementPath resolve(Path relative)
relative
- the path to be resolvedPath computeRelativePath(Path other) throws RepositoryException
this
absolute path to
other
.other
- an absolute path.this
path to other
path.RepositoryException
- if either this
or
other
path is not absolute.Path getAncestor(int degree) throws java.lang.IllegalArgumentException, PathNotFoundException, RepositoryException
An ancestor of relative degree x is the path that is x levels up along the path.
If this path is relative the implementation may not be able to determine
if the ancestor at degree
exists. Such an implementation
should properly build the ancestor (i.e. parent of .. is ../..) and
leave if it the caller to throw PathNotFoundException
.
degree
- the relative degree of the requested ancestor.java.lang.IllegalArgumentException
- if degree
is negative.PathNotFoundException
- if the implementation is able to determine
that there is no ancestor of the specified degree. In case of this
being an absolute path, this would be the case if degree
is
greater that the depth
of this path.RepositoryException
- If the implementation is not able to determine
the ancestor of the specified degree for some other reason.int getAncestorCount()
getDepth()
in case of a absolute path.
For relative path the number of ancestors cannot be determined and
-1 should be returned.getDepth()
,
getLength()
,
isCanonical()
int getLength()
Also note that the special elements "." and ".." are not treated
specially, e.g. both "/a/./.." and "/a/b/c" have a length of 4
but this value does not necessarily reflect the true hierarchy level as
returned by
.getDepth()
getDepth()
,
getAncestorCount()
int getDepth()
Note that the returned value might be negative if this path is not canonical, e.g. the depth of "../../a" is -1.
getLength()
,
getAncestorCount()
boolean isEquivalentTo(Path other) throws java.lang.IllegalArgumentException, RepositoryException
other
path would be equal to this
path if both of them are normalized.other
- Another path.java.lang.IllegalArgumentException
- if the given path is null
or if not both paths are either absolute or relative.RepositoryException
- if any of the path cannot be normalized.boolean isAncestorOf(Path other) throws java.lang.IllegalArgumentException, RepositoryException
getDepth()
. In case of undefined ancestor/descendant
relationship that might occur with relative paths, the return value
should be false
.true
if other
is a descendant;
otherwise false
.java.lang.IllegalArgumentException
- if the given path is null
or if not both paths are either absolute or relative.RepositoryException
- if any of the path cannot be normalized.getDepth()
boolean isDescendantOf(Path other) throws java.lang.IllegalArgumentException, RepositoryException
getDepth()
. In case of undefined ancestor/descendant
relationship that might occur with relative paths, the return value
should be false
.true
if other
is an ancestor;
otherwise false
.java.lang.IllegalArgumentException
- if the given path is null
or if not both paths are either absolute or relative.RepositoryException
- if any of the path cannot be normalized.isAncestorOf(Path)
Path subPath(int from, int to) throws java.lang.IllegalArgumentException
Path
consisting of those Path.Element objects
between the given from
, inclusive, and the given to
,
exclusive. An IllegalArgumentException
is thrown if from
is greater or equal than to
or if any of both params is
out of the possible range.from
- index of the element to start with and low endpoint
(inclusive) within the list of elements to use for the sub-path.to
- index of the element outside of the range i.e. high endpoint
(exclusive) within the list of elements to use for the sub-path.Path
consisting of those Path.Element objects
between the given from
, inclusive, and the given
to
, exclusive.java.lang.IllegalArgumentException
- if from
is greater or equal than to
or if any of both params is
out of the possible range.Path.Element[] getElements()
Path.Element getNameElement()
Path getLastElement()
getFirstElements()
Path getFirstElements()
null
if this path contains just a single element.null
getLastElement()
java.lang.String getString()
PathFactory.create(String)
.
The String representation must consist of the String representation of
its elements separated by DELIMITER
.
Path.Element.getString()
"Copyright © 2010 - 2020 Adobe Systems Incorporated. All Rights Reserved"