org.apache.jackrabbit.name
Class Path

java.lang.Object
  org.apache.jackrabbit.name.Path

public final class Path

extends Object

The Path utility class provides misc. methods to resolve and nornalize JCR-style item paths.

Each path consistnes of path elements and is immutable. It has the following properties:

isAbsolute():
A path is absolute if the first path element denotes the root element '/'.

isNormalized():
A path is normalized if all '.' and '..' path elements are resolved as much as possible. If the path is absolute it is normalized if it contains no such elements. For example the path '../../a' is normalized where as '../../b/../a/.' is not. Normalized paths never have '.' elements. Absolute normalized paths have no and relative normalized paths have no or only leading '..' elements.

isCanonical():
A path is canonical if its absolute and normalized.

String representations

The JCR path format is specified by JSR 170 as follows:

  path ::= properpath ['/']
  properpath ::= abspath | relpath
  abspath ::= '/' relpath
  relpath ::= pathelement | relpath '/' pathelement
  pathelement ::= name | name '[' number ']' | '..' | '.'
  number ::= (* An integer > 0 *)
  name ::= simplename | prefixedname
  simplename ::= onecharsimplename |
                 twocharsimplename |
                 threeormorecharname
  prefixedname ::= prefix ':' localname
  localname ::= onecharlocalname |
                twocharlocalname |
                threeormorecharname
  onecharsimplename ::= (* Any Unicode character except:
                     '.', '/', ':', '[', ']', '*',
                     ''', '"', '|' or any whitespace
                     character *)
  twocharsimplename ::= '.' onecharsimplename |
                        onecharsimplename '.' |
                        onecharsimplename onecharsimplename
  onecharlocalname ::= nonspace
  twocharlocalname ::= nonspace nonspace
  threeormorecharname ::= nonspace string nonspace
  prefix ::= (* Any valid XML Name *)
  string ::= char | string char
  char ::= nonspace | ' '
  nonspace ::= (* Any Unicode character except:
                  '/', ':', '[', ']', '*',
                  ''', '"', '|' or any whitespace
                  character *)
 

Nested Class Summary

static class	Path.CurrentElement
static class	Path.ParentElement
static class	Path.PathBuilder Internal helper class used to build a path from pre-parsed path elements.
static class	Path.PathElement Object representation of a single JCR path element.
static class	Path.RootElement

Field Summary

static Path

ROOT the root path

Method Summary

static void	checkFormat(String jcrPath) Checks if jcrPath is a valid JCR-style absolute or relative path.
Path	computeRelativePath(Path other) Computes the relative path from this absolute path to other.
static Path	create(Path parent, Path relPath, boolean normalize) Creates a new Path out of the given parent path string and the given relative path string.
static Path	create(Path parent, QName name, boolean normalize) Creates a new Path out of the given parent path string and the give name.
static Path	create(Path parent, QName name, int index, boolean normalize) Creates a new Path out of the given parent path and the give name and index.
static Path	create(Path parent, String relJCRPath, NamespaceResolver resolver, boolean canonicalize) Creates a new Path out of the given parent path and a relative path string.
static Path	create(QName name, int index) Creates a relative path based on a QName and an index.
static Path	create(String jcrPath, NamespaceResolver resolver, boolean normalize) Creates a new Path from the given jcrPath string.
boolean	denotesRoot() Tests whether this path represents the root path, i.e.
boolean	equals(Object obj) Compares the specified object with this path for equality.
Path	getAncestor(int degree) 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.PathElement[]	getElements() Returns the elements of this path.
int	getLength() Returns the length of this path, i.e.
Path.PathElement	getNameElement() Returns the name element (i.e.
Path	getNormalizedPath() Returns the normalized path representation of this path.
int	hashCode() Returns a hash code value for this path.
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 getDepth().
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 getDepth().
boolean	isNormalized() Tests whether this path is normalized, i.e.
String	toJCRPath(NamespaceResolver resolver) Returns a string representation of this Path in the JCR path format.
String	toString() Returns the internal string representation of this Path.
static Path	valueOf(String s) Returns a Path holding the value of the specified string.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ROOT

public static final Path ROOT

the root path

Method Detail

create

public static Path create(String jcrPath,
                          NamespaceResolver resolver,
                          boolean normalize)
                   throws MalformedPathException

Creates a new Path from the given jcrPath string. If normalize is true, the returned path will be normalized (or canonicalized if absolute).

Parameters:

jcrPath -

resolver -

normalize -

Returns:

Throws:

MalformedPathException

create

public static Path create(Path parent,
                          String relJCRPath,
                          NamespaceResolver resolver,
                          boolean canonicalize)
                   throws MalformedPathException

Creates a new Path out of the given parent path and a relative path string. If canonicalize is true, the returned path will be canonicalized.

Parameters:

parent -

relJCRPath -

resolver -

canonicalize -

Returns:

Throws:

MalformedPathException

create

public static Path create(Path parent,
                          Path relPath,
                          boolean normalize)
                   throws MalformedPathException

Creates a new Path out of the given parent path string and the given relative path string. If normalize is true, the returned path will be normalized (or canonicalized, if the parent path is absolute).

Parameters:

parent -

relPath -

normalize -

Returns:

Throws:

MalformedPathException

create

public static Path create(Path parent,
                          QName name,
                          boolean normalize)
                   throws MalformedPathException

Creates a new Path out of the given parent path string and the give name. If normalize is true, the returned path will be normalized (or canonicalized, if the parent path is absolute).

Parameters:

parent -

name -

normalize -

Returns:

Throws:

MalformedPathException

create

public static Path create(Path parent,
                          QName name,
                          int index,
                          boolean normalize)
                   throws MalformedPathException

Creates a new Path out of the given parent path and the give name and index. If normalize is true, the returned path will be normalized (or canonicalized, if the parent path is absolute).

Parameters:

parent -

name -

index -

normalize -

Returns:

Throws:

MalformedPathException

create

public static Path create(QName name,
                          int index)
                   throws IllegalArgumentException

Creates a relative path based on a QName and an index.

Parameters:

name - single QName for this relative path.

index - index of the sinlge name element.

Returns:

the relative path created from name.

Throws:

IllegalArgumentException - if index is negative.

checkFormat

public static void checkFormat(String jcrPath)
                        throws MalformedPathException

Checks if jcrPath is a valid JCR-style absolute or relative path.

Parameters:

jcrPath - the path to be checked

Throws:

MalformedPathException - If jcrPath is not a valid JCR-style path.

denotesRoot

public boolean denotesRoot()

Tests whether this path represents the root path, i.e. "/".

Returns:

true if this path represents the root path; false otherwise.

isAbsolute

public boolean isAbsolute()

Tests whether this path is absolute, i.e. whether it starts with "/".

Returns:

true if this path is absolute; false otherwise.

isCanonical

public boolean isCanonical()

Tests whether this path is canonical, i.e. whether it is absolute and does not contain redundant elements such as "." and "..".

Returns:

true if this path is canonical; false otherwise.

See Also:

isAbsolute()

isNormalized

public boolean isNormalized()

Tests whether this path is normalized, i.e. whether it does not contain redundant elements such as "." and "..".

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).

Returns:

true if this path is normalized; false otherwise.

See Also:

getNormalizedPath()

getNormalizedPath

public Path getNormalizedPath()
                       throws MalformedPathException

Returns the normalized path representation of this path. This typically involves removing/resolving redundant elements such as "." and ".." from the path, e.g. "/a/./b/.." will be normalized to "/a", "../../a/b/c/.." will be normalized to "../../a/b", and so on.

If the normalized path results in an empty path (eg: 'a/..') or if an absolute path is normalized that would result in a 'negative' path (eg: /a/../../) a MalformedPathException is thrown.

Returns:

a normalized path representation of this path

Throws:

MalformedPathException - if the path cannot be normalized.

See Also:

isNormalized()

getCanonicalPath

public Path getCanonicalPath()
                      throws MalformedPathException

Returns the canonical path representation of this path. This typically involves removing/resolving redundant elements such as "." and ".." from the path.

Returns:

a canonical path representation of this path

Throws:

MalformedPathException - if this path can not be canonicalized (e.g. if it is relative)

computeRelativePath

public Path computeRelativePath(Path other)
                         throws MalformedPathException

Computes the relative path from this absolute path to other.

Parameters:

other - an absolute path

Returns:

the relative path from this path to other path

Throws:

MalformedPathException - if either this or other path is not absolute

getAncestor

public Path getAncestor(int degree)
                 throws IllegalArgumentException,
                        PathNotFoundException

Returns the ancestor path of the specified relative degree.

An ancestor of relative degree x is the path that is x levels up along the path.

• degree = 0 returns this path.
• degree = 1 returns the parent of this path.
• degree = 2 returns the grandparent of this path.
• And so on to degree = n, where n is the depth of this path, which returns the root path.

Note that there migth be an unexpected result if this path is not normalized, e.g. the ancestor of degree = 1 of the path "../.." would be ".." although this is not the parent of "../..".

Parameters:

degree - the relative degree of the requested ancestor.

Returns:

the ancestor path of the specified degree.

Throws:

PathNotFoundException - if there is no ancestor of the specified degree

IllegalArgumentException - if degree is negative

getAncestorCount

public int getAncestorCount()

Returns the number of ancestors of this path. This is the equivalent of getDepth() - 1.

Note that the returned value might be negative if this path is not canonical, e.g. the depth of "../../a" is -1, its ancestor count is therefore -2.

Returns:

the number of ancestors of this path

See Also:

getDepth(), getLength(), isCanonical()

getLength

public int getLength()

Returns the length of this path, i.e. the number of its elements. Note that the root element "/" counts as a separate element, e.g. the length of "/a/b/c" is 4 whereas the length of "a/b/c" is 3.

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().

Returns:

the length of this path

See Also:

getDepth(), getAncestorCount()

getDepth

public int getDepth()

Returns the depth of this path. The depth reflects the absolute or relative hierarchy level this path is representing, depending on whether this path is an absolute or a relative path. The depth also takes '.' and '..' elements into account.

Note that the returned value might be negative if this path is not canonical, e.g. the depth of "../../a" is -1.

Returns:

the depth this path

See Also:

getLength(), getAncestorCount()

isAncestorOf

public boolean isAncestorOf(Path other)
                     throws MalformedPathException

Determines if this path is an ancestor of the specified path, based on their (absolute or relative) hierarchy level as returned by getDepth().

Returns:

true if other is a descendant; otherwise false

Throws:

MalformedPathException - if not both paths are either absolute or relative.

See Also:

getDepth()

isDescendantOf

public boolean isDescendantOf(Path other)
                       throws MalformedPathException

Determines if this path is a descendant of the specified path, based on their (absolute or relative) hierarchy level as returned by getDepth().

Returns:

true if other is an ancestor; otherwise false

Throws:

MalformedPathException - if not both paths are either absolute or relative.

See Also:

getDepth()

getNameElement

public Path.PathElement getNameElement()

Returns the name element (i.e. the last element) of this path.

Returns:

the name element of this path

getElements

public Path.PathElement[] getElements()

Returns the elements of this path.

Returns:

the elements of this path.

toJCRPath

public String toJCRPath(NamespaceResolver resolver)
                 throws NoPrefixDeclaredException

Returns a string representation of this Path in the JCR path format.

Parameters:

resolver - namespace resolver

Returns:

JCR path

Throws:

NoPrefixDeclaredException - if a namespace can not be resolved

toString

public String toString()

Returns the internal string representation of this Path.

Note that the returned string is not a valid JCR path, i.e. the namespace URI's of the individual path elements are not replaced with their mapped prefixes. Call toJCRPath(NamespaceResolver) for a JCR path representation.

Returns:

the internal string representation of this Path.

valueOf

public static Path valueOf(String s)
                    throws IllegalArgumentException

Returns a Path holding the value of the specified string. The string must be in the format returned by the Path.toString() method.

Parameters:

s - a String containing the Path representation to be parsed.

Returns:

the Path represented by the argument

Throws:

IllegalArgumentException - if the specified string can not be parsed as a Path.

See Also:

toString()

hashCode

public int hashCode()

Returns a hash code value for this path.

Returns:

a hash code value for this path.

See Also:

Object.hashCode()

equals

public boolean equals(Object obj)

Compares the specified object with this path for equality.

Parameters:

obj - the object to be compared for equality with this path.

Returns:

true if the specified object is equal to this path.