org.apache.jackrabbit.name
Class Path

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

All Implemented Interfaces:

Serializable

Deprecated. Use the Path and PathFactory interfaces from the org.apache.jackrabbit.spi package of the jackrabbit-spi component. A default implementation is available as the org.apache.jackrabbit.spi.commons.name.PathFactoryImpl class in the jackrabbit-spi-commons component.

public final class Path
extends Object
implements Serializable

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

See Also:

Serialized Form

Nested Class Summary

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

Field Summary

static Path.PathElement	CURRENT_ELEMENT Deprecated. the 'current' element. i.e. '.'
static int	INDEX_DEFAULT Deprecated. Constant representing the default (initial) index value.
static int	INDEX_UNDEFINED Deprecated. Constant representing an undefined index value
static Path.PathElement	PARENT_ELEMENT Deprecated. the 'parent' element. i.e. '..'
static Path	ROOT Deprecated. the root path
static int	ROOT_DEPTH Deprecated. Constant defining the depth of the root path
static Path.PathElement	ROOT_ELEMENT Deprecated. the 'root' element. i.e

Method Summary

static void	checkFormat(String jcrPath) Deprecated. Use PathFormat.checkFormat(String) instead.
Path	computeRelativePath(Path other) Deprecated. Computes the relative path from this absolute path to other.
static Path	create(Path parent, Path relPath, boolean normalize) Deprecated. 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) Deprecated. 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) Deprecated. 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) Deprecated. Use PathFormat.parse(Path, String, NamespaceResolver) instead.
static Path	create(QName name, int index) Deprecated. Creates a relative path based on a QName and an index.
static Path	create(String jcrPath, NamespaceResolver resolver, boolean normalize) Deprecated. Use PathFormat#parse(String, NamespaceResolver)} instead.
boolean	denotesRoot() Deprecated. Tests whether this path represents the root path, i.e. "/".
boolean	equals(Object obj) Deprecated. Compares the specified object with this path for equality.
Path	getAncestor(int degree) Deprecated. Returns the ancestor path of the specified relative degree.
int	getAncestorCount() Deprecated. Returns the number of ancestors of this path.
Path	getCanonicalPath() Deprecated. Returns the canonical path representation of this path.
int	getDepth() Deprecated. Returns the depth of this path.
Path.PathElement	getElement(int i) Deprecated. Returns the ith element of this path.
Path.PathElement[]	getElements() Deprecated. Returns the elements of this path.
int	getLength() Deprecated. Returns the length of this path, i.e. the number of its elements.
Path.PathElement	getNameElement() Deprecated. Returns the name element (i.e. the last element) of this path.
Path	getNormalizedPath() Deprecated. Returns the normalized path representation of this path.
int	hashCode() Deprecated. Returns a hash code value for this path.
boolean	isAbsolute() Deprecated. Tests whether this path is absolute, i.e. whether it starts with "/".
boolean	isAncestorOf(Path other) Deprecated. 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() Deprecated. 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) Deprecated. 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() Deprecated. Tests whether this path is normalized, i.e. whether it does not contain redundant elements such as "." and "..".
String	toJCRPath(NamespaceResolver resolver) Deprecated. Use PathFormat.format(Path, NamespaceResolver) instead.
String	toString() Deprecated. Returns the internal string representation of this Path.
static Path	valueOf(String s) Deprecated. 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_ELEMENT

public static final Path.PathElement ROOT_ELEMENT

Deprecated.

the 'root' element. i.e. '/'

CURRENT_ELEMENT

public static final Path.PathElement CURRENT_ELEMENT

Deprecated.

the 'current' element. i.e. '.'

PARENT_ELEMENT

public static final Path.PathElement PARENT_ELEMENT

Deprecated.

the 'parent' element. i.e. '..'

ROOT

public static final Path ROOT

Deprecated.

the root path

INDEX_UNDEFINED

public static final int INDEX_UNDEFINED

Deprecated.

Constant representing an undefined index value

See Also:

Constant Field Values

INDEX_DEFAULT

public static final int INDEX_DEFAULT

Deprecated.

Constant representing the default (initial) index value.

See Also:

Constant Field Values

ROOT_DEPTH

public static final int ROOT_DEPTH

Deprecated.

Constant defining the depth of the root path

See Also:

Constant Field Values

Method Detail

create

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

Deprecated. Use PathFormat#parse(String, NamespaceResolver)} instead.

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 -

Throws:

MalformedPathException

create

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

Deprecated. Use PathFormat.parse(Path, String, NamespaceResolver) instead.

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 -

Throws:

MalformedPathException

create

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

Deprecated.

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 -

Throws:

MalformedPathException - if relPath is absolute

create

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

Deprecated.

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 - the parent path

name - the name of the new path element.

normalize -

Returns:

the new path.

Throws:

MalformedPathException

create

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

Deprecated.

Creates a new Path out of the given parent path and the give name and index.

Parameters:

parent - the paren tpath.

name - the name of the new path element.

index - the index of the new path element.

normalize -

Returns:

the new path.

Throws:

MalformedPathException

create

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

Deprecated.

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

Deprecated. Use PathFormat.checkFormat(String) instead.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Returns:

the name element of this path

getElements

public Path.PathElement[] getElements()

Deprecated.

Returns the elements of this path.

Returns:

the elements of this path.

getElement

public Path.PathElement getElement(int i)

Deprecated.

Returns the i^th element of this path.

Parameters:

i - element index.

Returns:

the i^th element of this path.

Throws:

ArrayIndexOutOfBoundsException - if this path does not have an element at index i.

toJCRPath

public String toJCRPath(NamespaceResolver resolver)
                 throws NoPrefixDeclaredException

Deprecated. Use PathFormat.format(Path, NamespaceResolver) instead.

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

Deprecated.

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.

Overrides:

toString in class Object

Returns:

the internal string representation of this Path.

valueOf

public static Path valueOf(String s)
                    throws IllegalArgumentException

Deprecated.

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

Deprecated.

Returns a hash code value for this path.

Overrides:

hashCode in class Object

Returns:

a hash code value for this path.

See Also:

Object.hashCode()

equals

public boolean equals(Object obj)

Deprecated.

Compares the specified object with this path for equality.

Overrides:

equals in class Object

Parameters:

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

Returns:

true if the specified object is equal to this path.