facets.util
Class OffsetPath

java.lang.Object
  facets.util.Tracer
      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

• storing the first element of members for return as root
• storing the offsets returned by newOffsets(Object[])

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