Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.modeshape.graph.property
Interface Path

All Superinterfaces:
  Comparable<Path>, Iterable<Path.Segment>, Readable, Serializable

All Known Implementing Classes:
  AbstractPath, BasicPath, ChildPath, IdentifierPath, 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:

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

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 char` | `IDENTIFIER_LEADING_TERMINAL` The character used to begin an identifier segment within a path.
`static char` | `IDENTIFIER_TRAILING_TERMINAL` The character used to end an identifier segment 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
`boolean` | `endsWith(Name nameOfLastSegment)` Determine if the path's `getLastSegment()` has the supplied name and no `SNS index`.
`boolean` | `endsWith(Name nameOfLastSegment, int snsIndex)` Determine if the path's `getLastSegment()` has the supplied name and `SNS index`.
`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` | `isIdentifier()` Returns whether this path represents an identifier path.
`boolean` | `isNormalized()` Return whether this path is normalized and contains no unnecessary "." 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` | `relativeToRoot()` Obtain a path that is relative to the root node.
`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.modeshape.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

### IDENTIFIER_LEADING_TERMINAL

    static final char IDENTIFIER_LEADING_TERMINAL

  The character used to begin an identifier segment within a path.

  See Also:
    Constant Field Values

### IDENTIFIER_TRAILING_TERMINAL

    static final char IDENTIFIER_TRAILING_TERMINAL

  The character used to end an identifier segment 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

### isIdentifier

    boolean isIdentifier()

  Returns whether this path represents an identifier path. An identifier path is absolute, and contains a single `identifier Segment` that contains an identifier in the name.

  Returns:
    true if this path is an identifier 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 unnecessary "." 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

### relativeToRoot

    Path relativeToRoot()

  Obtain a path that is relative to the root node. This is equivalent to calling `relativeTo(Path)` with the root path.

  Returns:
    the relative path from the root node; never null

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

### endsWith

    boolean endsWith(Name nameOfLastSegment)

  Determine if the path's `getLastSegment()` has the supplied name and no `SNS index`.

  Parameters:
    `nameOfLastSegment` - the name
  Returns:
    return true if the supplied name is the name in the path's last segment (and there is no SNS index), or false otherwise

### endsWith

    boolean endsWith(Name nameOfLastSegment,
                     int snsIndex)

  Determine if the path's `getLastSegment()` has the supplied name and `SNS index`.

  Parameters:
    `nameOfLastSegment` - the name
    `snsIndex` - the SNS index
  Returns:
    return true if the path's last segment has the supplied name and SNS, or false otherwise

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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