|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Path
The 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
Nested Class Summary | |
---|---|
static interface |
Path.Element
Object representation of a single JCR path element. |
Field Summary | |
---|---|
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 |
Method Summary | |
---|---|
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. |
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. the number of its elements. |
Name |
getName()
Returns the name of the last path element, or null
for an identifier. |
Path.Element |
getNameElement()
Returns the name element (i.e. the last element) of this path. |
int |
getNormalizedIndex()
Returns the normalized index of the last path element. |
Path |
getNormalizedPath()
Returns the normalized path representation of this path. |
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. whether it starts with "/" or is an identifier based path. |
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. whether it is absolute and does not contain redundant elements such as "." and "..". |
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. whether it does not contain redundant elements such as "." and "..". |
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. |
Field Detail |
---|
static final int INDEX_UNDEFINED
static final int INDEX_DEFAULT
static final int ROOT_DEPTH
static final char DELIMITER
getString()
.
Method Detail |
---|
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
.
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()
getNormalizedPath()
Path getNormalizedPath() throws RepositoryException
RepositoryException
- if the path cannot be normalized.isNormalized()
Path getCanonicalPath() throws RepositoryException
RepositoryException
- if this path can not be canonicalized
(e.g. if it is relative).Path resolve(Path.Element element)
element
- path element
Path resolve(Path relative)
relative
- the path to be resolved
Path 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 IllegalArgumentException, PathNotFoundException, RepositoryException
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.
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()
getDepth()
.
getDepth()
,
getAncestorCount()
int getDepth()
getLength()
,
getAncestorCount()
boolean isEquivalentTo(Path other) throws IllegalArgumentException, RepositoryException
other
path would be equal to this
path if both of them are normalized.
other
- Another path.
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 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
.
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 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
.
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 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.
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()
String getString()
PathFactory.create(String)
.
The String representation must consist of the String representation of
its elements separated by DELIMITER
.
Path.Element.getString()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |