org.jboss.dna.graph.properties.basic
Class BasicPath

java.lang.Object
  org.jboss.dna.graph.properties.basic.BasicPath

All Implemented Interfaces:

Serializable, Comparable<Path>, Iterable<Path.Segment>, Path

@Immutable
public class BasicPath
extends Object
implements Path

A basic implementation of Path.

Author:

Randall Hauch, John Verhaeg

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface org.jboss.dna.graph.properties.Path

Path.Segment

Field Summary

static Path	EMPTY_RELATIVE
static Path	ROOT
static Path	SELF_PATH

Fields inherited from interface org.jboss.dna.graph.properties.Path

DEFAULT_DECODER, DEFAULT_ENCODER, DELIMITER, DELIMITER_STR, JSR283_DECODER, JSR283_ENCODER, NO_INDEX, NO_OP_DECODER, NO_OP_ENCODER, PARENT, PARENT_NAME, PARENT_SEGMENT, SELF, SELF_NAME, SELF_SEGMENT, URL_DECODER, URL_ENCODER

Constructor Summary

BasicPath(List<Path.Segment> segments, boolean absolute)

Method Summary

int	compareTo(Path that)
boolean	equals(Object obj)
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) Find the lowest common ancestor of this path and the supplied path.
Path.Segment	getLastSegment() Get the last segment in this path.
Path	getNormalizedPath() Get a normalized path with as many ".." segments and all "." resolved.
Path	getParent() Return the path to the parent, or this path if it is the root.
Path.Segment	getSegment(int index) Get the segment at the supplied index.
Path.Segment[]	getSegmentsArray() Obtain a copy of the segments in this path.
List<Path.Segment>	getSegmentsList() Get an unmodifiable list of the path segments.
String	getString() Get the string form of the path.
String	getString(NamespaceRegistry namespaceRegistry) Get the string form of the path, using the supplied namespace registry to convert the names' namespace URIs to prefixes.
String	getString(NamespaceRegistry namespaceRegistry, TextEncoder encoder) Get the encoded string form of the path, using the supplied namespace registry to convert the names' namespace URIs to prefixes and the supplied encoder to encode characters in each of the path segments.
String	getString(NamespaceRegistry namespaceRegistry, TextEncoder encoder, TextEncoder delimiterEncoder) Get the encoded string form of the path, using the supplied namespace registry to convert the names' namespace URIs to prefixes and the supplied encoder to encode characters in each of the path segments.
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) Determine whether this path and the supplied path have the same immediate ancestor.
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	isAtOrAbove(Path other) Determine whether this path is the same as to or a ancestor of the supplied path.
boolean	isAtOrBelow(Path other) Determine whether this path is the same as to or a decendant 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	isSameAs(Path other) Determine whether this path represents the same as the supplied path.
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	resolveAgainst(Path absolutePath) 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	subpath(int beginIndex) Return a new path consisting of the segments starting at beginIndex index (inclusive).
Path	subpath(int beginIndex, int endIndex) Return a new path consisting of the segments between the beginIndex index (inclusive) and the endIndex index (exclusive).
String	toString()

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

ROOT

public static final Path ROOT

EMPTY_RELATIVE

public static final Path EMPTY_RELATIVE

SELF_PATH

public static final Path SELF_PATH

Constructor Detail

BasicPath

public BasicPath(List<Path.Segment> segments,
                 boolean absolute)

Parameters:

segments - the segments

absolute - true if this path is absolute, or false otherwise

Method Detail

getParent

public Path getParent()

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.

Specified by:

getParent in interface Path

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.

Specified by:

getAncestor in interface Path

Returns:

the ancestor of the supplied degree

getCanonicalPath

public Path getCanonicalPath()

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

Specified by:

getCanonicalPath in interface Path

Returns:

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

getCommonAncestor

public Path getCommonAncestor(Path that)

Find the lowest common ancestor of this path and the supplied path.

Specified by:

getCommonAncestor in interface Path

Parameters:

that - the other path

Returns:

the lowest common ancestor, which may be the root path if there is no other.

getLastSegment

public Path.Segment getLastSegment()

Get the last segment in this path.

Specified by:

getLastSegment in interface Path

Returns:

the last segment, or null if the path is empty

getNormalizedPath

public Path getNormalizedPath()

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

Specified by:

getNormalizedPath in interface Path

Returns:

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

getSegment

public Path.Segment getSegment(int index)

Get the segment at the supplied index.

Specified by:

getSegment in interface Path

Parameters:

index - the index

Returns:

the segment

getSegmentsArray

public Path.Segment[] getSegmentsArray()

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

Specified by:

getSegmentsArray in interface Path

Returns:

the array of segments as a copy

getSegmentsList

public List<Path.Segment> getSegmentsList()

Get an unmodifiable list of the path segments.

Specified by:

getSegmentsList in interface Path

Returns:

the unmodifiable list of path segments; never null

getString

public String getString()

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

Specified by:

getString in interface Path

Returns:

the encoded string

See Also:

Path.getString(TextEncoder)

getString

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

Specified by:

getString in interface Path

Parameters:

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

Returns:

the encoded string

See Also:

Path.getString()

getString

public String getString(NamespaceRegistry namespaceRegistry)

Get the string form of the path, using the supplied namespace registry to convert the names' namespace URIs to prefixes. The default encoder is used to encode characters in each of the path segments. The second encoder is used to encode (or convert) the delimiter between the namespace prefix and the local part.

Specified by:

getString in interface Path

Parameters:

namespaceRegistry - the namespace registry that should be used to obtain the prefix for the namespace URIs in the segment names

Returns:

the encoded string

See Also:

Path.getString(NamespaceRegistry,TextEncoder), Path.getString(NamespaceRegistry, TextEncoder, TextEncoder)

getString

public String getString(NamespaceRegistry namespaceRegistry,
                        TextEncoder encoder)

Get the encoded string form of the path, using the supplied namespace registry to convert the names' namespace URIs to prefixes and the supplied encoder to encode characters in each of the path segments.

Specified by:

getString in interface Path

Parameters:

namespaceRegistry - the namespace registry that should be used to obtain the prefix for the namespace URIs in the segment names

encoder - the encoder to use for encoding the local part and namespace prefix of each segment, or null if the default encoder should be used

Returns:

the encoded string

See Also:

Path.getString(NamespaceRegistry), Path.getString(NamespaceRegistry, TextEncoder, TextEncoder)

getString

public String getString(NamespaceRegistry namespaceRegistry,
                        TextEncoder encoder,
                        TextEncoder delimiterEncoder)

Get the encoded string form of the path, using the supplied namespace registry to convert the names' namespace URIs to prefixes and the supplied encoder to encode characters in each of the path segments.

Specified by:

getString in interface Path

Parameters:

namespaceRegistry - the namespace registry that should be used to obtain the prefix for the namespace URIs in the segment names

encoder - the encoder to use for encoding the local part and namespace prefix of each segment, or null if the default encoder should be used

delimiterEncoder - the encoder to use for encoding the delimiter between the local part and namespace prefix of each segment, and for encoding the path delimiter, or null if the standard delimiters should be used

Returns:

the encoded string

See Also:

Path.getString(org.jboss.dna.graph.properties.NamespaceRegistry, org.jboss.dna.common.text.TextEncoder, org.jboss.dna.common.text.TextEncoder)

hasSameAncestor

public boolean hasSameAncestor(Path that)

Determine whether this path and the supplied path have the same immediate ancestor. In other words, this method determines whether the node represented by this path is a sibling of the node represented by the supplied path.

Specified by:

hasSameAncestor in interface Path

Parameters:

that - the other path

Returns:

true if this path and the supplied path have the same immediate ancestor.

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

Specified by:

isAbsolute in interface Path

Returns:

true if the path is absolute, 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.

Specified by:

isAncestorOf in interface Path

Parameters:

decendant - the path that may be the decendant; may be null

Returns:

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

isAtOrBelow

public boolean isAtOrBelow(Path other)

Determine whether this path is the same as to or a decendant of the supplied path. This method is equivalent to (but may be more efficient than) calling isSame(other) || isAncestor(other).

Specified by:

isAtOrBelow in interface Path

Parameters:

other - the other path to compare with this path; may be null

Returns:

true if the paths are equivalent or if this path is considered a decendant of the other path, or false otherwise

See Also:

Path.isAtOrBelow(org.jboss.dna.graph.properties.Path)

isAtOrAbove

public boolean isAtOrAbove(Path other)

Determine whether this path is the same as to or a ancestor of the supplied path. This method is equivalent to (but may be more efficient than) calling isSame(other) || isAncestor(other), and is a convenience method that is identical to calling other.isAtOrBelow(this).

Specified by:

isAtOrAbove in interface Path

Parameters:

other - the other path to compare with this path; may be null

Returns:

true if the paths are equivalent or if this path is considered an ancestor of the other path, or false otherwise

See Also:

Path.isAtOrAbove(org.jboss.dna.graph.properties.Path)

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.

Specified by:

isDecendantOf in interface Path

Parameters:

ancestor - the path that may be the ancestor; may be null

Returns:

true if this path is an decendant of the supplied path, 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.

Specified by:

isNormalized in interface Path

Returns:

true if this path is normalized, or false otherwise

isRoot

public boolean isRoot()

Return whether this path represents the root path.

Specified by:

isRoot in interface Path

Returns:

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

isSameAs

public boolean isSameAs(Path other)

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

Specified by:

isSameAs in interface Path

Parameters:

other - the other path to compare with this path; may be null

Returns:

true if the paths are equivalent, or false otherwise

iterator

public Iterator<Path.Segment> iterator()

Specified by:

iterator in interface Iterable<Path.Segment>

Specified by:

iterator in interface Path

relativeTo

public Path relativeTo(Path startingPath)

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

Specified by:

relativeTo in interface Path

Parameters:

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

Returns:

the relative path

resolve

public Path resolve(Path relativePath)

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

Specified by:

resolve in interface 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

resolveAgainst

public Path resolveAgainst(Path absolutePath)

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

Specified by:

resolveAgainst in interface 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

size

public int size()

Return the number of segments in this path.

Specified by:

size in interface Path

Returns:

the number of path segments

subpath

public Path subpath(int beginIndex)

Return a new path consisting of the segments starting at beginIndex index (inclusive). This is equivalent to calling path.subpath(beginIndex,path.size()-1).

Specified by:

subpath in interface Path

Parameters:

beginIndex - the beginning index, inclusive.

Returns:

the specified subpath

subpath

public Path subpath(int beginIndex,
                    int endIndex)

Return a new path consisting of the segments between the beginIndex index (inclusive) and the endIndex index (exclusive).

Specified by:

subpath in interface Path

Parameters:

beginIndex - the beginning index, inclusive.

endIndex - the ending index, exclusive.

Returns:

the specified subpath

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

compareTo

public int compareTo(Path that)

Specified by:

compareTo in interface Comparable<Path>

toString

public String toString()

Overrides:

toString in class Object