The
Path
interface defines the qualified representation of a JCR path. It consists of an ordered list of {@link Path.Element} objectsand is immutable.
A {@link Path.Element} is either {@link Path.Element#denotesName() named}or one of the following special elements:
- the {@link Element#denotesCurrent() current} element (Notation: "."),
- the {@link Element#denotesParent() parent} element (Notation: ".."),
- the {@link Element#denotesRoot() root} element (Notation: {}), which canonly 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 {@link Path#getLength() length} of a path is the number of its elements.
Depth: The {@link Path#getDepth() depth} of a path is
- 0 for the root path,
- 0 for the path consisting of the current element only,
- -1 for the path consisting of the parent element only,
- 1 for the path consisting of any other single element,
- depth(P) + depth(Q) for the path P/Q.
The depth of a valid absolute path equals the length of its normalization minus 1.
Absolute vs. Relative A path can be absolute or relative:
A path {@link #isAbsolute() is absolute} if its first element is the rootelement. A path is relative if it is not absolute.
- An absolute path is valid if its depth is greater or equals 0. A relative path is always valid.
- Two absolute paths are equivalent if "they refer to the same item in the hierarchy".
- Two relative paths P and Q are equivalent if for every absolute path R such that R/P and R/Q are valid, R/P and R/Q are equivalent.
Normalization: A path P {@link Path#isNormalized() is normalized} if P has minimal lengthamongst 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 contains no current nor parent element. The normalization of a path is unique.
Equalivalence: Path P is {@link Path#isEquivalentTo(Path) 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 {@link Path#isCanonical() 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 {@link Path#isAncestorOf(Path) ancestor} of path Q if
- P is a direct ancestor of Q or
- P is a direct ancestor of some path S which is an ancestor of Q.
Path P is an {@link Path#isDescendantOf(Path) descendant} of path Q if
- Path P is a descendant of path Q if Q is an ancestor of P.