org.jboss.dna.graph.property
Interface Path

All Superinterfaces:
Comparable<Path>, Iterable<Path.Segment>, Readable, Serializable
All Known Implementing Classes:
AbstractPath, BasicPath, ChildPath, RootPath

@Immutable
public interface Path
extends Comparable<Path>, Iterable<Path.Segment>, Serializable, Readable

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:

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 finding a common ancestor.

Author:
Randall Hauch, John Verhaeg

Nested Class Summary
static interface Path.Segment
          Representation of the segments that occur within a path.
 
Field Summary
static TextDecoder DEFAULT_DECODER
          The default text decoder to be used when none is otherwise specified.
static TextEncoder DEFAULT_ENCODER
          The default text encoder to be used when none is otherwise specified.
static int DEFAULT_INDEX
          The default index for a Path.Segment.
static char DELIMITER
          The delimiter character used to separate segments within a path.
static String DELIMITER_STR
          String form of the delimiter used to separate segments within a path.
static TextDecoder JSR283_DECODER
          The text decoder that decodes according to JSR-283.
static TextEncoder JSR283_ENCODER
          The text encoder that encodes according to JSR-283.
static TextDecoder NO_OP_DECODER
          The text decoder that does nothing.
static TextEncoder NO_OP_ENCODER
          The text encoder that does nothing.
static String PARENT
          String representation of the segment that references a parent.
static Name PARENT_NAME
          Singleton instance of the name referencing a parent, provided as a convenience.
static Path.Segment PARENT_SEGMENT
          Singleton instance of the path segment referencing a parent, provided as a convenience.
static String SELF
          String representation of the segment that references the same segment.
static Name SELF_NAME
          Singleton instance of the name referencing a self, provided as a convenience.
static Path.Segment SELF_SEGMENT
          Singleton instance of the path segment referencing a parent, provided as a convenience.
static TextDecoder URL_DECODER
          The text decoder that decodes text according to the rules of RFC 2396.
static TextEncoder URL_ENCODER
          The text encoder that encodes text according to the rules of RFC 2396.
 
Method Summary
 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.
 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()
          
 Iterator<Path> pathsFromRoot()
          Return an iterator that walks the paths from the root path down to this path.
 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).
 
Methods inherited from interface java.lang.Comparable
compareTo
 
Methods inherited from interface org.jboss.dna.graph.property.Readable
getString, getString, getString, getString, getString
 

Field Detail

NO_OP_ENCODER

static final TextEncoder NO_OP_ENCODER
The text encoder that does nothing.


JSR283_ENCODER

static final TextEncoder JSR283_ENCODER
The text encoder that encodes according to JSR-283.


URL_ENCODER

static final TextEncoder URL_ENCODER
The text encoder that encodes text according to the rules of RFC 2396.


NO_OP_DECODER

static final TextDecoder NO_OP_DECODER
The text decoder that does nothing.


JSR283_DECODER

static final TextDecoder JSR283_DECODER
The text decoder that decodes according to JSR-283.


URL_DECODER

static final TextDecoder URL_DECODER
The text decoder that decodes text according to the rules of RFC 2396.


DEFAULT_ENCODER

static final TextEncoder DEFAULT_ENCODER
The default text encoder to be used when none is otherwise specified. This is currently the JSR-283 encoder.


DEFAULT_DECODER

static final TextDecoder DEFAULT_DECODER
The default text decoder to be used when none is otherwise specified. This is currently the JSR-283 encoder.


DELIMITER

static final char DELIMITER
The delimiter character used to separate segments within a path.

See Also:
Constant Field Values

DELIMITER_STR

static final String DELIMITER_STR
String form of the delimiter used to separate segments within a path.


PARENT

static final String PARENT
String representation of the segment that references a parent.

See Also:
Constant Field Values

SELF

static final String SELF
String representation of the segment that references the same segment.

See Also:
Constant Field Values

DEFAULT_INDEX

static final int DEFAULT_INDEX
The default index for a Path.Segment.

See Also:
Constant Field Values

SELF_NAME

static final Name SELF_NAME
Singleton instance of the name referencing a self, provided as a convenience.


PARENT_NAME

static final Name PARENT_NAME
Singleton instance of the name referencing a parent, provided as a convenience.


SELF_SEGMENT

static final Path.Segment SELF_SEGMENT
Singleton instance of the path segment referencing a parent, provided as a convenience.


PARENT_SEGMENT

static final Path.Segment PARENT_SEGMENT
Singleton instance of the path segment referencing a parent, provided as a convenience.

Method Detail

size

int size()
Return the number of segments in this path.

Returns:
the number of path segments

isRoot

boolean isRoot()
Return whether this path represents the root path.

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

isSameAs

boolean isSameAs(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; may be null
Returns:
true if the paths are equivalent, or false otherwise

isAtOrAbove

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

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

isAtOrBelow

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

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

isAncestorOf

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; may be null
Returns:
true if this path is an ancestor of the supplied path, or false otherwise

isDecendantOf

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; may be null
Returns:
true if this path is an decendant of the supplied path, or false otherwise

isAbsolute

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

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

Path getNormalizedPath()
Get a normalized path with as many ".." segments and all "." resolved. The relative path ".", however, will return itself as the normalized path, since it cannot be resolved any further.

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

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

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:
IllegalArgumentException - if the supplied path is null
PathNotFoundException - if both this path and the supplied path are not absolute

resolve

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:
IllegalArgumentException - if the supplied path is null
InvalidPathException - if the this path is not absolute or if the supplied path is not relative.

resolveAgainst

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:
IllegalArgumentException - if the supplied path is null
InvalidPathException - if the supplied path is not absolute or if this path is not relative.

getParent

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.

Returns:
the parent path, or this null if it is already the root

getAncestor

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:
IllegalArgumentException - if the degree is negative
InvalidPathException - if the degree is greater than the length of this path

hasSameAncestor

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.

Parameters:
that - the other path
Returns:
true if this path and the supplied path have the same immediate ancestor.
Throws:
IllegalArgumentException - if the supplied path is null

getCommonAncestor

Path getCommonAncestor(Path that)
Find the lowest common ancestor of this path and the supplied path.

Parameters:
that - the other path
Returns:
the lowest common ancestor, which may be the root path if there is no other.
Throws:
IllegalArgumentException - if the supplied path is null

getLastSegment

Path.Segment getLastSegment()
Get the last segment in this path.

Returns:
the last segment, or null if the path is empty

getSegment

Path.Segment getSegment(int index)
Get the segment at the supplied index.

Parameters:
index - the index
Returns:
the segment
Throws:
IndexOutOfBoundsException - if the index is out of bounds

subpath

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

Parameters:
beginIndex - the beginning index, inclusive.
Returns:
the specified subpath
Throws:
IndexOutOfBoundsException - if the beginIndex is negative or larger than the length of this Path object

subpath

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

Parameters:
beginIndex - the beginning index, inclusive.
endIndex - the ending index, exclusive.
Returns:
the specified subpath
Throws:
IndexOutOfBoundsException - if the beginIndex is negative, or endIndex is larger than the length of this Path object, or beginIndex is larger than endIndex.

iterator

Iterator<Path.Segment> iterator()

Specified by:
iterator in interface Iterable<Path.Segment>

pathsFromRoot

Iterator<Path> pathsFromRoot()
Return an iterator that walks the paths from the root path down to this path. This method always returns at least one path (the root returns an iterator containing itself).

Returns:
the path iterator; never null

getSegmentsArray

Path.Segment[] getSegmentsArray()
Obtain a copy of the segments in this path. None of the segments are encoded.

Returns:
the array of segments as a copy

getSegmentsList

List<Path.Segment> getSegmentsList()
Get an unmodifiable list of the path segments.

Returns:
the unmodifiable list of path segments; never null


Copyright © 2008-Present JBoss a division of Red Hat. All Rights Reserved.