org.jboss.dna.common.jcr
Class Path

java.lang.Object
  org.jboss.dna.common.jcr.Path

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<Path>, java.lang.Iterable<Path.Segment>

@Immutable
public class Path
extends java.lang.Object
implements java.lang.Cloneable, java.lang.Comparable<Path>, java.lang.Iterable<Path.Segment>, java.io.Serializable

An object representation of a node path within a repository.

A path consists of zero or more segments that can contain any characters, although the string representation may require some characters to be encoded. For example, if a path contains a segment with a forward slash, then this forward slash must be escaped when writing the whole path to a string (since a forward slash is used as the delimiter between segments).

Because of this encoding and decoding issue, there is no standard representation of a path as a string. Instead, this class uses text encoders to escape certain characters when writing to a string or unescaping the string representation. These encoders and used only with individual segments, and therefore are not used to encode the delimiter. Three standard encoders are provided, although others can certainly be used:

• Jsr283Encoder - an encoder and decoder that is compliant with JSR-283 by converting the reserved characters (namely '*', '/', ':', '[', ']' and '|') to their unicode equivalent.
• UrlEncoder - an encoder and decoder that is useful for converting text to be used within a URL, as defined by Section 2.3 of RFC 2396. This encoder does encode many characters (including '`', '@', '#', '$', '^', '&', '{', '[', '}', ']', '|', ':', ';', '\', '"', '<', ',', '>', '?', '/', and ' '), while others are not encoded (including '-', '_', '.', '!', '~', '*', '\', ''', '(', and ')'). Note that only the '*' character is the only character reserved by JSR-283 that is not encoded by the URL encoder.
• NoOpEncoder - an encoder implementation that does nothing.

This class simplifies working with paths and using a Path is often more efficient that processing and manipulating the equivalent String. This class can easily iterate over the segments, return the number of segments, compare with other paths, resolve relative paths, return the ancestor (or parent), determine whether one path is an ancestor or decendent of another path, and creating subpaths.

Author:

Randall Hauch

See Also:

Serialized Form

Nested Class Summary

static class

Path.Segment A segment of a path.

Field Summary

static TextEncoder	DEFAULT_ENCODER
static char	DELIMITER
static java.lang.String	DELIMITER_STR
static TextEncoder	JSR283_ENCODER
static TextEncoder	NO_OP_ENCODER
static java.lang.String	PARENT
static Path	ROOT
static java.lang.String	SELF
static TextEncoder	URL_ENCODER

Constructor Summary

Path(java.lang.String path)
Create a path by parsing the supplied absolute or relative path.

Path(java.lang.String path, TextEncoder encoder)
Create a path by parsing the supplied absolute or relative path.

Method Summary

Path	append(java.lang.String... segments) Create a path by appending a single segment without decoding any of the characters.
Path	append(java.lang.String segment) Create a path by appending a single segment without decoding any of the characters.
Path	append(java.lang.String[] segments, TextEncoder encoder) Create a path by appending multiple segment.
Path	append(java.lang.String segment, TextEncoder encoder) Create a path by appending a single segment.
Path	clone()
int	compareTo(Path that)
boolean	endsWith(java.lang.String segment) Determine whether the last segment matches that supplied.
boolean	endsWith(java.lang.String segment, TextEncoder encoder) Determine whether the last segment matches that supplied.
boolean	equals(java.lang.Object obj)
Path	getAncestor() Return the path to the parent, or this path if it is the root.
Path	getAncestor(int degree) Return the path to the ancestor of the supplied degree.
Path	getCanonicalPath() Get the canonical form of this path.
Path	getCommonAncestor(Path that)
Path.Segment	getLastSegment() Get the last segment in this path.
Path	getNormalizedPath() Get a normalized path with as many ".." segments and all "." resolved.
Path.Segment	getSegment(int index) Get the segment at the supplied index.
java.lang.String	getString() Get the string form of the path.
java.lang.String	getString(TextEncoder encoder) Get the encoded string form of the path, using the supplied encoder to encode characters in each of the path segments.
int	hashCode()
boolean	hasSameAncestor(Path that)
boolean	isAbsolute() Return whether this path is an absolute path.
boolean	isAncestorOf(Path decendant) Determine whether this path is an ancestor of the supplied path.
boolean	isDecendantOf(Path ancestor) Determine whether this path is an decendant of the supplied path.
boolean	isNormalized() Return whether this path is normalized and contains no "." segments and as few ".." segments as possible.
boolean	isRoot() Return whether this path represents the root path.
boolean	isSame(Path other) Determine whether this path represents the same as the supplied path.
java.util.Iterator<Path.Segment>	iterator()
Path	relativeTo(Path startingPath) Get a relative path from the supplied path to this path.
Path	resolve(Path relativePath) Get the absolute path by resolving the supplied relative (non-absolute) path against this absolute path.
Path	resolve(java.lang.String relativePath) Get the absolute path by resolving the supplied relative (non-absolute) path against this absolute path.
Path	resolve(java.lang.String relativePath, TextEncoder encoder) Get the absolute path by resolving the supplied relative (non-absolute) path against this absolute path.
Path	resolveAgainst(Path absolutePath) Get the absolute path by resolving this relative (non-absolute) path against the supplied absolute path.
Path	resolveAgainst(java.lang.String absolutePath) Get the absolute path by resolving this relative (non-absolute) path against the supplied absolute path.
Path	resolveAgainst(java.lang.String absolutePath, TextEncoder encoder) Get the absolute path by resolving this relative (non-absolute) path against the supplied absolute path.
int	size() Return the number of segments in this path.
Path.Segment[]	toArray() Obtain a copy of the segments in this path.
java.util.List<Path.Segment>	toList() Get an unmodifiable list of the path segments.
java.lang.String	toString()
java.lang.String[]	toStringArray() Obtain a copy of the segments in this path.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

NO_OP_ENCODER

public static final TextEncoder NO_OP_ENCODER

JSR283_ENCODER

public static final TextEncoder JSR283_ENCODER

URL_ENCODER

public static final TextEncoder URL_ENCODER

DEFAULT_ENCODER

public static final TextEncoder DEFAULT_ENCODER

DELIMITER

public static final char DELIMITER

See Also:

Constant Field Values

DELIMITER_STR

public static final java.lang.String DELIMITER_STR

PARENT

public static final java.lang.String PARENT

See Also:

Constant Field Values

SELF

public static final java.lang.String SELF

See Also:

Constant Field Values

ROOT

public static final Path ROOT

Constructor Detail

Path

public Path(java.lang.String path)
     throws InvalidPathException

Create a path by parsing the supplied absolute or relative path. Successive delimiters are treated as a single delimiter.

Parameters:

path - the string containing the path with delimiters separating the different path segments

Throws:

InvalidPathException - if the path is null, empty, or invalid

Path

public Path(java.lang.String path,
            TextEncoder encoder)
     throws InvalidPathException

Create a path by parsing the supplied absolute or relative path. Successive delimiters are treated as a single delimiter.

Parameters:

path - the string containing the path with delimiters separating the different path segments

encoder - the encoder that should be used to convert escaped characters

Throws:

InvalidPathException - if the path is null, empty, or invalid

Method Detail

size

public int size()

Return the number of segments in this path.

Returns:

the number of path segments

isRoot

public boolean isRoot()

Return whether this path represents the root path.

Returns:

true if this path is the root path, or false otherwise

isSame

public boolean isSame(Path other)

Determine whether this path represents the same as the supplied path. This is equivalent to calling this.compareTo(other) == 0 .

Parameters:

other - the other path to compare with this path

Returns:

true if the paths are equivalent, or false otherwise

isAncestorOf

public boolean isAncestorOf(Path decendant)

Determine whether this path is an ancestor of the supplied path. A path is considered an ancestor of another path if the the ancestor path appears in its entirety at the beginning of the decendant path, and where the decendant path contains at least one additional segment.

Parameters:

decendant - the path that may be the decendant

Returns:

true if this path is an ancestor of the supplied path, or false otherwise

isDecendantOf

public boolean isDecendantOf(Path ancestor)

Determine whether this path is an decendant of the supplied path. A path is considered a decendant of another path if the the decendant path starts exactly with the entire ancestor path but contains at least one additional segment.

Parameters:

ancestor - the path that may be the ancestor

Returns:

true if this path is an decendant of the supplied path, or false otherwise

isAbsolute

public boolean isAbsolute()

Return whether this path is an absolute path. A path is either relative or absolute. An absolute path starts with a "/".

Returns:

true if the path is absolute, or false otherwise

isNormalized

public boolean isNormalized()

Return whether this path is normalized and contains no "." segments and as few ".." segments as possible. For example, the path "../a" is normalized, while "/a/b/c/../d" is not normalized.

Returns:

true if this path is normalized, or false otherwise

getNormalizedPath

public Path getNormalizedPath()

Get a normalized path with as many ".." segments and all "." resolved.

Returns:

the normalized path, or this object if this path is already normalized

Throws:

InvalidPathException - if the normalized form would result in a path with negative length (e.g., "/a/../../..")

getCanonicalPath

public Path getCanonicalPath()

Get the canonical form of this path. A canonical path has is absolute and isNormalized().

Returns:

the canonical path, or this object if it is already in its canonical form

Throws:

InvalidPathException - if the path is not absolute and cannot be canonicalized

relativeTo

public Path relativeTo(Path startingPath)

Get a relative path from the supplied path to this path.

Parameters:

startingPath - the path specifying the starting point for the new relative path; may not be null

Returns:

the relative path

Throws:

java.lang.IllegalArgumentException - if the supplied path is null

PathNotFoundException - if both this path and the supplied path are not absolute

resolve

public Path resolve(Path relativePath)

Get the absolute path by resolving the supplied relative (non-absolute) path against this absolute path.

Parameters:

relativePath - the relative path that is to be resolved against this path

Returns:

the absolute and normalized path resolved from this path and the supplied absolute path

Throws:

java.lang.IllegalArgumentException - if the supplied path is null

InvalidPathException - if the this path is not absolute or if the supplied path is not relative.

See Also:

resolve(String), resolve(String, TextEncoder)

resolve

public Path resolve(java.lang.String relativePath)

Get the absolute path by resolving the supplied relative (non-absolute) path against this absolute path.

Parameters:

relativePath - the relative path that is to be resolved against this path

Returns:

the absolute path resolved from this path and the supplied absolute path

Throws:

java.lang.IllegalArgumentException - if the supplied path is null

InvalidPathException - if the this path is not absolute or if the supplied path is not relative.

See Also:

resolve(String), resolve(String, TextEncoder)

resolve

public Path resolve(java.lang.String relativePath,
                    TextEncoder encoder)

Get the absolute path by resolving the supplied relative (non-absolute) path against this absolute path.

Parameters:

relativePath - the relative path that is to be resolved against this path

encoder - the encoder to use, or null if the default encoder should be used

Returns:

the absolute path resolved from this path and the supplied absolute path

Throws:

java.lang.IllegalArgumentException - if the supplied path is null

InvalidPathException - if the this path is not absolute or if the supplied path is not relative.

See Also:

resolve(String), resolve(String, TextEncoder)

resolveAgainst

public Path resolveAgainst(Path absolutePath)

Get the absolute path by resolving this relative (non-absolute) path against the supplied absolute path.

Parameters:

absolutePath - the absolute path to which this relative path should be resolve

Returns:

the absolute path resolved from this path and the supplied absolute path

Throws:

java.lang.IllegalArgumentException - if the supplied path is null

InvalidPathException - if the supplied path is not absolute or if this path is not relative.

See Also:

resolveAgainst(String), resolveAgainst(String, TextEncoder)

resolveAgainst

public Path resolveAgainst(java.lang.String absolutePath)

Get the absolute path by resolving this relative (non-absolute) path against the supplied absolute path.

Parameters:

absolutePath - the absolute path to which this relative path should be resolve

Returns:

the absolute path resolved from this path and the supplied absolute path

Throws:

java.lang.IllegalArgumentException - if the supplied path is null

InvalidPathException - if the supplied path is not absolute or if this path is not relative.

See Also:

resolveAgainst(Path), resolveAgainst(String, TextEncoder)

resolveAgainst

public Path resolveAgainst(java.lang.String absolutePath,
                           TextEncoder encoder)

Get the absolute path by resolving this relative (non-absolute) path against the supplied absolute path.

Parameters:

absolutePath - the absolute path to which this relative path should be resolve

encoder - the encoder to use, or null if the default encoder should be used

Returns:

the absolute path resolved from this path and the supplied absolute path

Throws:

java.lang.IllegalArgumentException - if the supplied path is null

InvalidPathException - if the supplied path is not absolute or if this path is not relative.

See Also:

resolveAgainst(Path), resolveAgainst(String)

getAncestor

public Path getAncestor()

Return the path to the parent, or this path if it is the root. This is an efficient operation that does not require copying any data.

Returns:

the parent path, or this path if it is already the root

getAncestor

public Path getAncestor(int degree)

Return the path to the ancestor of the supplied degree. An ancestor of degree x is the path that is x levels up along the path. For example, degree = 0 returns this path, while degree = 1 returns the parent of this path, degree = 2 returns the grandparent of this path, and so on. Note that the result may be unexpected if this path is not normalized, as a non-normalized path contains ".." and "." segments.

Parameters:

degree -

Returns:

the ancestor of the supplied degree

Throws:

java.lang.IllegalArgumentException - if the degree is negative

PathNotFoundException - if the degree is greater than the length of this path

hasSameAncestor

public boolean hasSameAncestor(Path that)

getCommonAncestor

public Path getCommonAncestor(Path that)

endsWith

public boolean endsWith(java.lang.String segment)

Determine whether the last segment matches that supplied.

Parameters:

segment - the value for the last segment; if null, false is returned

Returns:

the last segment, or null if the path is empty

endsWith

public boolean endsWith(java.lang.String segment,
                        TextEncoder encoder)

Determine whether the last segment matches that supplied.

Parameters:

segment - the value for the last segment; if null, false is returned

encoder - the encoder to use, or null if the default encoder should be used

Returns:

the last segment, or null if the path is empty

getLastSegment

public Path.Segment getLastSegment()

Get the last segment in this path.

Returns:

the last segment, or null if the path is empty

getSegment

public Path.Segment getSegment(int index)

Get the segment at the supplied index.

Parameters:

index - the index

Returns:

the segment

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of bounds

append

public Path append(java.lang.String segment)

Create a path by appending a single segment without decoding any of the characters. Any segment that is null will be ignored. This is equivalent to calling append(segment,null).

Parameters:

segment - the segment to append to this path

Returns:

the new path

append

public Path append(java.lang.String... segments)

Create a path by appending a single segment without decoding any of the characters. Any segment that is null will be ignored. This is equivalent to calling append(segment,null).

Parameters:

segments - the segments to append to the path

Returns:

the new path

append

public Path append(java.lang.String segment,
                   TextEncoder encoder)

Create a path by appending a single segment. Any segment that is null will be ignored. Whitespaces are not removed, but are decoded according to the supplied encoder.

Parameters:

segment - the segment to append to this path

encoder - the encoder to use, or null if the default encoder should be used

Returns:

the new path

Throws:

InvalidPathException - if the segment is empty or blank

append

public Path append(java.lang.String[] segments,
                   TextEncoder encoder)

Create a path by appending multiple segment. Any segment that is null will be ignored. Whitespaces are not removed, but are decoded according to the supplied encoder.

Parameters:

segments - the segments to append to this path

encoder - the encoder to use, or null if the default encoder should be used

Returns:

the new path

Throws:

InvalidPathException - if a segment is empty or blank

iterator

public java.util.Iterator<Path.Segment> iterator()

Specified by:

iterator in interface java.lang.Iterable<Path.Segment>

toArray

public Path.Segment[] toArray()

Obtain a copy of the segments in this path. None of the segments are encoded.

Returns:

the array of segments as a copy

toStringArray

public java.lang.String[] toStringArray()

Obtain a copy of the segments in this path. None of the segments are encoded.

Returns:

the array of segments as a copy

toList

public java.util.List<Path.Segment> toList()

Get an unmodifiable list of the path segments.

Returns:

the unmodifiable list of path segments; never null

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

compareTo

public int compareTo(Path that)

Specified by:

compareTo in interface java.lang.Comparable<Path>

clone

public Path clone()

Overrides:

clone in class java.lang.Object

getString

public java.lang.String getString()

Get the string form of the path. The default encoder is used to encode characters in each of the path segments.

Returns:

the encoded string

See Also:

getString(TextEncoder)

getString

public java.lang.String getString(TextEncoder encoder)

Get the encoded string form of the path, using the supplied encoder to encode characters in each of the path segments.

Parameters:

encoder - the encoder to use, or null if the default encoder should be used

Returns:

the encoded string

See Also:

getString()

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object