facets.util
Class OffsetPath

java.lang.Object
  extended by facets.util.Tracer
      extended by facets.util.OffsetPath
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
ArrayPath, NodePath

public abstract class OffsetPath
extends Tracer
implements java.io.Serializable

Abstract path through a data structure.

OffsetPath extends the principle of the array index to any structure that can be described using a set of integer offsets. It records an arbitrary path to one of a structure's elements as a sequence of offsets describing the relation of each intermediate element to its parent.

While its most obvious and significant use is to describe paths to the nodes of tree from its root, an OffsetPath can be used for any data structure that can be indexed - indeed for a simple array. It is therefore defined abstract to enable concrete implementations that know the type of a structure and the indexing convention that it uses.

A major advantage of OffsetPath is that it is indifferent to the identity of its members, describing only the relationships between them. An OffsetPath can be created describing a path in one data structure, and then used to create the corresponding path through another; the other structure need not even be of the same type, proving it subscribes to the same indexing convention.

See Also:
Serialized Form

Field Summary
static OffsetPath empty
          Convenience instance.
 int[] offsets
           
static OffsetPath singleMembered
          Convenience instance.
 
Constructor Summary
protected OffsetPath(int[] offsets)
          Core constructor.
protected OffsetPath(java.lang.Object[] members)
          Core constructor.
 
Method Summary
 boolean equals(java.lang.Object o)
           
 java.lang.Object[] members(java.lang.Object root)
          Return the members of root referenced by the stored offsets.
protected abstract  java.lang.Object[] newMembers(java.lang.Object root, int[] offsets)
          Return the members of root referenced by offsets.
protected abstract  int[] newOffsets(java.lang.Object[] members)
          Construct offsets recording a path described by its members.
abstract  OffsetPath procrusted(java.lang.Object root, java.lang.Object to)
           
 java.lang.Object target(java.lang.Object root)
          The primary target of the path.
 java.lang.String toString()
           
 
Methods inherited from class facets.util.Tracer
trace, trace, trace, trace, trace, traceDebug, traceDebug, traceObjectText, traceOutput, traceOutputWithClass
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

singleMembered

public static final OffsetPath singleMembered
Convenience instance.

A fixed single-member path.


empty

public static final OffsetPath empty
Convenience instance.

A fixed single-member path.


offsets

public final int[] offsets
Constructor Detail

OffsetPath

protected OffsetPath(int[] offsets)
Core constructor.

Stores immutable offsets for use by newMembers(Object,int[])

Parameters:
offsets - define path

OffsetPath

protected OffsetPath(java.lang.Object[] members)
Core constructor.

Creates path by

Parameters:
members - members of the path, the first being the root data object
Method Detail

equals

public boolean equals(java.lang.Object o)
Overrides:
equals in class java.lang.Object

members

public final java.lang.Object[] members(java.lang.Object root)
Return the members of root referenced by the stored offsets.

The array returned is that created in newMembers(Object,int[]).


target

public java.lang.Object target(java.lang.Object root)
The primary target of the path.

Returns the last element of members.

For many applications this will be the 'selected' element of root.


newOffsets

protected abstract int[] newOffsets(java.lang.Object[] members)
Construct offsets recording a path described by its members.

Called by OffsetPath(Object[]).

Parameters:
members - the path to be recorded

newMembers

protected abstract java.lang.Object[] newMembers(java.lang.Object root,
                                                 int[] offsets)
Return the members of root referenced by offsets.

Called by members(Object).


procrusted

public abstract OffsetPath procrusted(java.lang.Object root,
                                      java.lang.Object to)

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object