org.priha.path
Class Path

java.lang.Object
  extended by org.priha.path.Path
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<Path>

public final class Path
extends java.lang.Object
implements java.lang.Comparable<Path>, java.io.Serializable

Manages paths, which are a key ingredient in JCR. A Path is an immutable object, so you can't change it once you create it.

It should be noted that Path.toString() can become fairly expensive quickly, since it'll create a StringBuilder to concatenate all the Components, so it's better to avoid it, if possible. The String is cached internally, but still, it's better not to call it even once. The equals(), compareTo() and toString() methods avoid calling toString().

See Also:
Serialized Form

Nested Class Summary
static class Path.Component
          A Path component consists of a QName with an optional index (to support same name siblings).
 
Field Summary
static Path EMPTY_RELATIVE_PATH
           
static Path ROOT
          This is a static instance of the root path so that you don't have to create it every single time you use it (as it happens quite often).
 
Constructor Summary
protected Path()
          This constructor is useful only to subclasses or serialization.
  Path(NamespaceMapper ns, java.lang.String abspath)
          Create a new path from a String.
  Path(NamespaceMapper ns, java.lang.String pathStart, Path pathEnd)
           
  Path(Path.Component[] components, boolean absolute)
           
  Path(Path parentPath, Path.Component component)
           
  Path(QName[] components, boolean absolute)
          Creates a Path from a number of QName components.
  Path(QName name, boolean b)
           
 
Method Summary
 int compareTo(Path o)
           
 int depth()
          Returns the depth of this path.
 boolean equals(java.lang.Object obj)
          Two paths are equal if their string representations are equal.
 Path getAncestorPath(int depth)
          Returns the Path up to ancestor "depth".
 Path.Component getComponent(int idx)
          Gets one path component.
 Path.Component[] getElements()
           
 Path.Component getLastComponent()
          Returns the name of the last component of the path (i.e.
 Path.Component getParentName()
          Returns the name of the parent (not the path).
 Path getParentPath()
          Returns a valid path pointing at the parent of this path.
 Path getSubpath(int startidx)
          Returns a subpath starting from index "startidx".
 Path getSubpath(int startidx, int endidx)
          Gets a valid subpath starting from startidx and ending at endidx.
 int hashCode()
           
 boolean isAbsolute()
           
 boolean isParentOf(Path p)
          Returns true, if this path is a parent of the given Path.
 boolean isRoot()
          Returns true, if this Path represents the root.
 Path resolve(NamespaceMapper ns, java.lang.String relPath)
          Resolves a relative Path against this Path.
 Path resolve(Path.Component component)
          Adds a new component to the path (since Components are not paths), and returns a new Path.
 Path resolve(QName component)
          Adds a component to the path (since Components are not paths), and returns a new Path.
 java.lang.String toString()
          Returns the Path in String format.
 java.lang.String toString(NamespaceMapper ns)
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

ROOT

public static final Path ROOT
This is a static instance of the root path so that you don't have to create it every single time you use it (as it happens quite often).

Using this is faster than using Path p = new Path("/").


EMPTY_RELATIVE_PATH

public static final Path EMPTY_RELATIVE_PATH
Constructor Detail

Path

protected Path()
This constructor is useful only to subclasses or serialization.


Path

public Path(QName[] components,
            boolean absolute)
Creates a Path from a number of QName components. The index of all the components is assumed to be 1.

Parameters:
components - A list of components
absolute - true, if this path should be absolute; false if relative.

Path

public Path(Path.Component[] components,
            boolean absolute)

Path

public Path(NamespaceMapper ns,
            java.lang.String abspath)
     throws javax.jcr.NamespaceException,
            javax.jcr.RepositoryException
Create a new path from a String. E.g. Path p = new Path("/foo/bar/glob");

Parameters:
abspath - A path.
Throws:
javax.jcr.RepositoryException
javax.jcr.NamespaceException

Path

public Path(NamespaceMapper ns,
            java.lang.String pathStart,
            Path pathEnd)
     throws javax.jcr.NamespaceException,
            javax.jcr.RepositoryException
Throws:
javax.jcr.NamespaceException
javax.jcr.RepositoryException

Path

public Path(QName name,
            boolean b)

Path

public Path(Path parentPath,
            Path.Component component)
Method Detail

isAbsolute

public final boolean isAbsolute()

getComponent

public final Path.Component getComponent(int idx)
Gets one path component.

Parameters:
idx - Which component to get. The top-most component is at index zero.
Returns:
The component.

getLastComponent

public final Path.Component getLastComponent()
Returns the name of the last component of the path (i.e. the name)

Returns:
The name. If this is the root, returns "" (empty string).

isRoot

public final boolean isRoot()
Returns true, if this Path represents the root.

Returns:
True, if this Path is the root.

depth

public final int depth()
Returns the depth of this path. Root is zero.

Returns:
The depth of the path.

getParentName

public final Path.Component getParentName()
                                   throws InvalidPathException
Returns the name of the parent (not the path).

Returns:
String describing the name of the parent.
Throws:
InvalidPathException - If you try to get the parent of the root node.

getParentPath

public final Path getParentPath()
                         throws InvalidPathException
Returns a valid path pointing at the parent of this path.

Returns:
A new Path object.
Throws:
InvalidPathException - If this Path is the root node.

getSubpath

public final Path getSubpath(int startidx)
                      throws InvalidPathException
Returns a subpath starting from index "startidx". Start from zero to get a clone of this Path.

Parameters:
startidx - Where to start the path from. Zero is root.
Returns:
A valid Path.
Throws:
InvalidPathException - If startidx < 0 or startidx > path depth.

getSubpath

public final Path getSubpath(int startidx,
                             int endidx)
                      throws InvalidPathException
Gets a valid subpath starting from startidx and ending at endidx.

Parameters:
startidx - Which component to start from.
endidx - Which component is the last one to include.
Returns:
A valid Path
Throws:
InvalidPathException - If the index values are invalid.

toString

public final java.lang.String toString()
Returns the Path in String format. Note that the first time toString() is called, it is a rather expensive operation.

Overrides:
toString in class java.lang.Object

toString

public final java.lang.String toString(NamespaceMapper ns)
                                throws javax.jcr.NamespaceException,
                                       javax.jcr.RepositoryException
Throws:
javax.jcr.NamespaceException
javax.jcr.RepositoryException

resolve

public final Path resolve(QName component)
Adds a component to the path (since Components are not paths), and returns a new Path.

Parameters:
component - QName to add at the end of the Path.
Returns:
A new Path with the component added.

resolve

public final Path resolve(Path.Component component)
Adds a new component to the path (since Components are not paths), and returns a new Path.

Parameters:
component - A Compoment to add at the end of the Path.
Returns:
A new Path.

resolve

public final Path resolve(NamespaceMapper ns,
                          java.lang.String relPath)
                   throws javax.jcr.NamespaceException,
                          javax.jcr.RepositoryException
Resolves a relative Path against this Path.

Parameters:
relPath - String describing relative path.
Returns:
A valid Path.
Throws:
javax.jcr.RepositoryException
javax.jcr.NamespaceException

getAncestorPath

public final Path getAncestorPath(int depth)
                           throws InvalidPathException
Returns the Path up to ancestor "depth".

Parameters:
depth -
Returns:
Throws:
InvalidPathException

isParentOf

public final boolean isParentOf(Path p)
Returns true, if this path is a parent of the given Path. Root is the parent of all other paths.

Parameters:
path -
Returns:

equals

public final boolean equals(java.lang.Object obj)
Two paths are equal if their string representations are equal.

Overrides:
equals in class java.lang.Object

hashCode

public final int hashCode()
Overrides:
hashCode in class java.lang.Object

compareTo

public final int compareTo(Path o)
Specified by:
compareTo in interface java.lang.Comparable<Path>

getElements

public final Path.Component[] getElements()