Package com.orchestranetworks.schema

# Class Path

java.lang.Object
com.orchestranetworks.schema.Path

All Implemented Interfaces:
  `Comparable<Path>`

public abstract class Path extends Object implements Comparable<Path>
A path is used for locating a node in a tree structure. It consists of a sequence of steps.

In string notation, the steps are separated by "`/`" slashes. The syntax supported is in fact a small subset of XPath:

- A path that begins with "`/`" is an absolute location, otherwise, it is a relative location.
- Special steps are "`.`" (the self node) and "`..`" (the parent node).

### Examples

- The path `/domain/customer/lastName` is an absolute location.
- The path `../customer/lastName` is a relative location that starts at the parent of the current node.
- The paths `./customer/lastName` and `customer/lastName` are both relative locations that start at the current (self) node and are equivalent.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final Path`
  `PARENT`
  Corresponds to the path "`..`".
  `static final Path`
  `ROOT`
  Corresponds to the path "`/`".
  `static final Path`
  `SELF`
  Corresponds to the path "`.`".

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract Path`
  `add(Path aPath)`
  Concatenates this path instance with the path specified.
  `abstract Path`
  `add(Step aStep)`
  `abstract Path`
  `add(String aKey)`
  `abstract Path`
  `addIndex(int index)`
  Returns a path such that the last step is indexed with the specified number.
  `abstract Path`
  `addIndexedPath(Path aPath, int index)`
  Concatenates this path instance with the specified indexed path.
  `abstract Path`
  `addIndexedStep(Step aStep, int index)`
  Concatenates this path instance with the specified indexed step.
  `abstract String`
  `format()`
  Returns the canonical string representation of this instance.
  `abstract Step`
  `getFirstStep()`
  Returns the first step of this path, `null` for the root path.
  `abstract Step`
  `getLastStep()`
  Returns the last step of this path, `null` for the root path.
  `abstract Path`
  `getPathWithoutLastStep()`
  Returns this path without its last step.
  `abstract int`
  `getSize()`
  Returns the number of steps in this path.
  `abstract Step`
  `getStep(int i)`
  Returns the step at the specified position in this path.
  `abstract Step[]`
  `getSteps()`
  Returns the array of steps for this path.
  `abstract Path`
  `getSubPath(int beginIndex)`
  Returns a new path that is a subpath of this path.
  `abstract Path`
  `getSubPath(int beginIndex, int endIndex)`
  Returns a new path that is a subpath of this path.
  `final boolean`
  `isIndexed()`
  Returns `true` if this `Path` identifies a node in an aggregated list.
  `abstract boolean`
  `isRelative()`
  Returns `true` if this path begins with '.' (self) or '..' (parent).
  `abstract boolean`
  `isRoot()`
  Returns `true` if this is the root path (whose canonical notation is "`/`").
  `abstract boolean`
  `isSelf()`
  Returns `true` if this is the self path (whose canonical notation is "`.`").
  `static Path`
  `parse(String pathString)`
  Returns the path based on the string specified.
  `abstract Path`
  `resolveWith(Path aPath)`
  Resolves the path specified against this instance by considering that this instance is the "current location".
  `boolean`
  `startsWith(Path aPath)`
  Tests whether this path starts with the specified prefix.
  `abstract boolean`
  `startsWith(Path aPath, int offset)`
  Tests whether this path starts with the specified prefix beginning at specified index.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface java.lang.Comparable

  `compareTo`

- ## Field Details

  - ### ROOT

    public static final Path ROOT
    Corresponds to the path "`/`".

  - ### SELF

    public static final Path SELF
    Corresponds to the path "`.`".

  - ### PARENT

    public static final Path PARENT
    Corresponds to the path "`..`".

- ## Method Details

  - ### parse

    public static Path parse(String pathString)
    Returns the path based on the string specified.

    This method also performs path simplification whenever possible, if the path includes "`.`" or "`..`".

  - ### add

    public abstract Path add(String aKey)
    See Also:
      - `add(Path)`

  - ### add

    public abstract Path add(Path aPath)
    Concatenates this path instance with the path specified. This method also performs path simplification if the specified path begins with "`.`" or "`..`".

    Examples:

    `this` | `aPath` | result
    /a/b/c | /d/e | /a/b/c/d/e
    /a/b/c | . | /a/b/c
    /a/b/c | ./d/e | /a/b/c/d/e
    /a/b/c | ../d/e | /a/b/d/e
    /a/b/c | .. | /a/b
    /a/b/c | ../.. | /a
    /a/b/c | ../../.. | /
    /a/b/c | ../../../.. | ..
    /a/b/c | ../../../../d/e | ../d/e
    /a/b/c | ../../.. | /
    . | /a/b/c | ./a/b/c
    . | .. | ..

    See Also:
      - `resolveWith(Path)`

  - ### add

    public abstract Path add(Step aStep)
    See Also:
      - `add(Path)`

  - ### addIndex

    public abstract Path addIndex(int index)

    Returns a path such that the last step is indexed with the specified number.

    For example, if this instance is `/customer/address` and it receives `addIndex(2)`, then the resulting path is `/customer/address[2]`.

    This notation is only allowed on aggregated lists, not on tables. Contrary to the XPath specification, the index starts at 0 instead of 1.

    Throws:
      `IllegalStateException` - if the last step of this path is already indexed.
      `IllegalArgumentException` - if `index` is negative.
    See Also:
      - `addIndexedPath(Path, int)`
      - `addIndexedStep(Step, int)`

  - ### addIndexedStep

    public abstract Path addIndexedStep(Step aStep, int index)
    Concatenates this path instance with the specified indexed step.

    For example, if this instance is `/customer` and it receives `addIndexedStep(Step('address'),2)`, then the resulting path is `/customer/address[2]`.

    This notation is only allowed on aggregated lists, not on tables. Contrary to the XPath specification, index starts at 0 instead of 1.

    This method is equivalent to `add(aStep).addIndex(index)`.``

    @throws IllegalStateException if `aStep` is already indexed.
    Throws:
      `IllegalArgumentException` - if `index` is negative.
    See Also:
      - `isIndexed()`
      - `addIndex(int)`
      - `addIndexedPath(Path, int)`

  - ### addIndexedPath

    public abstract Path addIndexedPath(Path aPath, int index)

    Concatenates this path instance with the specified indexed path.

    For example, if this instance is `/item` and it receives `addIndexedPath(Path('/customer/address'),2)`, then the resulting path is `/item/customer/address[2]`.

    This notation is only allowed on aggregated lists, not on tables. Contrary to the XPath specification, index starts at 0 instead of 1.

    This method is equivalent to `add(aPath).addIndex(index)`.``

    @throws IllegalStateException if the last step of `aPath` is already indexed.
    Throws:
      `IllegalArgumentException` - if `index` is negative.
    See Also:
      - `isIndexed()`
      - `addIndexedStep(Step, int)`
      - `addIndex(int)`

  - ### getFirstStep

    public abstract Step getFirstStep()
    Returns the first step of this path, `null` for the root path.

  - ### resolveWith

    public abstract Path resolveWith(Path aPath)
    Resolves the path specified against this instance by considering that this instance is the "current location".
    Returns:
      if `aPath` is absolute then it returns `aPath` (no relative resolution); if `aPath` is relative then it returns `this.add(aPath)`
    See Also:
      - `add(Path)`

  - ### getStep

    public abstract Step getStep(int i)
    Returns the step at the specified position in this path.

  - ### getSteps

    public abstract Step[] getSteps()
    Returns the array of steps for this path.

  - ### getLastStep

    public abstract Step getLastStep()
    Returns the last step of this path, `null` for the root path.

  - ### getPathWithoutLastStep

    public abstract Path getPathWithoutLastStep()
    Returns this path without its last step.

    Examples and special cases:

    - for `/a/b/c`, it returns `/a/b`
    - for `/`, it returns `null`
    - for `.`, it returns `/`
    - for `..`, it returns `/`

  - ### getSubPath

    public abstract Path getSubPath(int beginIndex)
    Returns a new path that is a subpath of this path. The subpath begins at the specified key and continues to the end of this path.

  - ### getSubPath

    public abstract Path getSubPath(int beginIndex, int endIndex)
    Returns a new path that is a subpath of this path. The subpath begins at the specified `beginIndex` key and continues to the key at index `endIndex - 1`. Thus, the size of the subpath is `endIndex - beginIndex`.

  - ### startsWith

    public boolean startsWith(Path aPath)
    Tests whether this path starts with the specified prefix.

  - ### startsWith

    public abstract boolean startsWith(Path aPath, int offset)
    Tests whether this path starts with the specified prefix beginning at specified index.

  - ### getSize

    public abstract int getSize()
    Returns the number of steps in this path.

    A relative notation with `SELF` always counts `SELF` as the first step. For example, for the notation `a/b/c`, this method returns '4' since the path is interpreted as `./a/b/c`.

  - ### isIndexed

    public final boolean isIndexed()
    Returns `true` if this `Path` identifies a node in an aggregated list. For example, the path `element/item[0]/label` or `element/item/label[0]` identifies a node under an aggregated list.
    See Also:
      - `Step.isIndexed()`
      - `Step.getIndex()`

  - ### isRelative

    public abstract boolean isRelative()
    Returns `true` if this path begins with '.' (self) or '..' (parent).

  - ### isRoot

    public abstract boolean isRoot()
    Returns `true` if this is the root path (whose canonical notation is "`/`").

  - ### isSelf

    public abstract boolean isSelf()
    Returns `true` if this is the self path (whose canonical notation is "`.`").

  - ### format

    public abstract String format()
    Returns the canonical string representation of this instance.

    Examples: `/a/b/c` is an absolute path notation, `./a/b/c` is the notation for a relative path starting with the self node, `../a/b/c` is the notation for a relative path starting with the parent node.

    See Also:
      - `parse(String)`