org.nodal.nav
Interface Path

All Known Subinterfaces:

DocumentPath, FragmentPath

public interface Path

A descriptor for navigating between Nodes in a repository.

If the parent of this Path is null, then either the operator() is absolute or null.

Author:

Lee Iverson

Nested Class Summary

static class	Path.Failure Class that signals a Path construction error.
static interface	Path.Generator Lazy evaluator for a Path.

Method Summary

PathEquivalence	addEquivalent(Path other) Register the equivalence of another Path with this.
Path	ancestorOpNamed(java.lang.String opName) Return the ancestor Path whose operator() has a function name that matches the opName argument.
Path	apply(Path path) A new Path obtained by following path from this starting point.
Path	apply(PathOperator op) A new Path obtained by applying the PathOperator to this starting point.
Path	apply(java.lang.String str) Parse the String as a Path and then apply to this Path.
Path	bind() The bound version of this Path, if one exists.
Getter	binding() The binding of this Path.
Path	difference(Path other) Returns the difference between this Path and other.
DocumentPath	documentPath() The Path to the Document including this Path.
PathEquivalence	equivalences() The Set of equivalent Path elements to this Path
boolean	equivalent(Path other) Return true if the other Path is equivalent to this one.
FragmentPath	fragmentPath() The FragmentPath version of this Path.
boolean	inFragment() True if this Path is a fragment reference.
boolean	isAbsolute() True if this Path has an absolute PathOperator at its root.
boolean	isAncestorOf(Path other) Is this Path an ancestor Path of other?
PathOperator	operator() The PathOperator that gives this Path when applied to the parent.
Path	parent() The parent of this Path.
java.lang.String	toURLString() The encoded URL string for this Path.

Method Detail

parent

public Path parent()

The parent of this Path.

This Path can be obtained by applying the PathOperator operator() to the parent() Path.

operator

public PathOperator operator()

The PathOperator that gives this Path when applied to the parent.

This Path can be obtained by applying the PathOperator operator() to the parent() Path.

documentPath

public DocumentPath documentPath()

The Path to the Document including this Path.

For a DocumentPath instance, this is a self-reference. For a FragmentPath, it is a reference to the containing Document or null if it is a fragment-relative Path.

fragmentPath

public FragmentPath fragmentPath()

The FragmentPath version of this Path.

This will return null if the Path is not a fragment reference.

apply

public Path apply(Path path)
           throws Path.Failure

A new Path obtained by following path from this starting point.

Throws:

Path.Failure

apply

public Path apply(java.lang.String str)
           throws Path.Failure

Parse the String as a Path and then apply to this Path.

Parameters:

str - the String to be applied

Returns:

a new Path derived from this Path and the parsed String

Throws:

Path.Failure - if the parse fails or the operator cannot be applied

apply

public Path apply(PathOperator op)
           throws Path.Failure

A new Path obtained by applying the PathOperator to this starting point.

Throws:

Path.Failure

bind

public Path bind()
          throws Path.Failure

The bound version of this Path, if one exists.

Returns:

A bound version of this Path

Throws:

Path.Failure - if unable to bind the Path.

binding

public Getter binding()

The binding of this Path. The value must be a Path for which bind() self-evaluates.

Returns:

the appropriate Getter, or null if not available.

isAncestorOf

public boolean isAncestorOf(Path other)

Is this Path an ancestor Path of other?

Parameters:

other - a Path

Returns:

true if this Path is an ancestor of other

difference

public Path difference(Path other)
                throws Path.Failure

Returns the difference between this Path and other. The difference is defined as the Path that, when apply()ed to this one, produces other. If these Paths have a common root, then a relative Path is returned, otherwise the result is clearly other. If other is not absolute, then Failure is thrown.

Parameters:

other - the Path that is the target of this difference

Returns:

a Path that produces other when apply()ed to this one.

Throws:

Path.Failure - when other is not absolute

ancestorOpNamed

public Path ancestorOpNamed(java.lang.String opName)

Return the ancestor Path whose operator() has a function name that matches the opName argument. For example, ancestorNamedOp("scheme") extracts the ancestor Path that contains only the scheme of the Path.

Parameters:

opName - the PathOperator function name to be searched for

Returns:

an ancestor Path whose PathOperator has the function name matching opName.

isAbsolute

public boolean isAbsolute()

True if this Path has an absolute PathOperator at its root.

inFragment

public boolean inFragment()

True if this Path is a fragment reference.

toURLString

public java.lang.String toURLString()

The encoded URL string for this Path.

Returns:

the encoded URL string for this Path

equivalences

public PathEquivalence equivalences()

The Set of equivalent Path elements to this Path

Returns:

the Set of equivalent Paths for this Path or null

addEquivalent

public PathEquivalence addEquivalent(Path other)

Register the equivalence of another Path with this.

Parameters:

other - the other equivalent Path elements

Returns:

the Set of all equivalences for p1 and p2

equivalent

public boolean equivalent(Path other)

Return true if the other Path is equivalent to this one.

Parameters:

other - another Path

Returns:

true if the other Path is equivalent to this one.