org.apache.jackrabbit.spi
Interface Path

All Superinterfaces:
Serializable

public interface Path
extends Serializable

The Path interface defines the qualified representation of a JCR path. It consists of Path.Element objects 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.

Note, that the implementation must implement the equals method such that two Path objects having the equal Elements must be equal.


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 denotesRoot()
          Tests whether this path represents the root path, i.e.
 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.Element[] getElements()
          Returns the elements of this path.
 int getLength()
          Returns the length of this path, i.e.
 Path.Element getNameElement()
          Returns the name element (i.e.
 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).

The String representation must consist of the String representation of its elements separated by DELIMITER.

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

INDEX_UNDEFINED

static final int INDEX_UNDEFINED
Constant representing an undefined index value

See Also:
Constant Field Values

INDEX_DEFAULT

static final int INDEX_DEFAULT
Constant representing the default (initial) index value.

See Also:
Constant Field Values

ROOT_DEPTH

static final int ROOT_DEPTH
Constant defining the depth of the root path

See Also:
Constant Field Values

DELIMITER

static final char DELIMITER
Delimiter used in order to concatenate the Path.Element objects upon getString().

See Also:
Constant Field Values
Method Detail

denotesRoot

boolean denotesRoot()
Tests whether this path represents the root path, i.e. "/".

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

isAbsolute

boolean isAbsolute()
Tests whether this path is absolute, i.e. whether it starts with "/".

Returns:
true if this path is absolute; false otherwise.

isCanonical

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

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

Path getNormalizedPath()
                       throws RepositoryException
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:
RepositoryException - if the path cannot be normalized.
See Also:
isNormalized()

getCanonicalPath

Path getCanonicalPath()
                      throws RepositoryException
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:
RepositoryException - if this path can not be canonicalized (e.g. if it is relative).

computeRelativePath

Path computeRelativePath(Path other)
                         throws RepositoryException
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:
RepositoryException - if either this or other path is not absolute.

getAncestor

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.

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

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

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

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

boolean isAncestorOf(Path other)
                     throws IllegalArgumentException,
                            RepositoryException
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:
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.
See Also:
getDepth()

isDescendantOf

boolean isDescendantOf(Path other)
                       throws IllegalArgumentException,
                              RepositoryException
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:
IllegalArgumentException - If the given path is null.
RepositoryException - if not both paths are either absolute or relative.
See Also:
getDepth()

subPath

Path subPath(int from,
             int to)
             throws IllegalArgumentException,
                    RepositoryException
Returns a new 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. A RepositoryException is thrown if this Path is not normalized.

Parameters:
from -
to -
Returns:
Throws:
IllegalArgumentException
RepositoryException - If this Path is not normalized.

getElements

Path.Element[] getElements()
Returns the elements of this path.

Returns:
the elements of this path.

getNameElement

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

Returns:
the name element of this path

getString

String getString()
Returns the String representation of this Path as it is used by PathFactory.create(String).

The String representation must consist of the String representation of its elements separated by DELIMITER.

Returns:
See Also:
Path.Element.getString()


Copyright © 2004-2008 The Apache Software Foundation. All Rights Reserved.