org.ceryle.tm
Class SequenceIterator

java.lang.Object
  org.ceryle.tm.SequenceIterator

All Implemented Interfaces:

Iterator

public class SequenceIterator
extends Object
implements Iterator

A utility class containing one method for traversing TopicMap graphs as according to a sequence created by use of a trio of PSIs, including a sequence association type, and member roles for to (next) and from (previous).

Note 1
Because it's possible that a traversal of what can be a graph (rather than a sequence) may lead to situations where the next element in the traversal allows more than one option, this class includes a getState() method which provides a way of checking if there is more than one option. In this case, the allNext() method will return an Iterator over all possible next items. The returned elements in this case will be whatever the iteration order of the Topic Map processor determines (which is ambiguous).

Note 2
Note that because an iterator such as this could end up in an infinite loop if the provided structure included loops, the constructor includes a boolean to determine whether this is to be allowed or not.

Since:

JDK1.4

Version:

$Id: SequenceIterator.java,v 3.4 2007-06-15 12:09:32 altheim Exp $

Author:

Murray Altheim

Field Summary

static int	STATE_AMBIGUOUS An int constant indicating that the next traversal is not necessarily in a strict sequence (i.e., there may be more than one option in the next traversal).
static int	STATE_IN_SEQUENCE An int constant indicating that the traversal is in sequence (i.e., either next or previous, depending on current direction).
static int	STATE_NO_TRAVERSE An int constant indicating that no traversal is possible from the current Topic.
static int	STATE_UNKNOWN An int constant indicating that the traversal state is unknown.
static int	TRAVERSE_FROM An int constant indicating a 'From' traversal direction, i.e., against the direction of arrows, to-to-from.
static int	TRAVERSE_TO An int constant indicating a 'To' traversal direction, i.e., in the direction of arrows, from-to-to.

Constructor Summary

SequenceIterator(Topic index, int direction, boolean allowLoops)
Creates an Iterator provided the starting Topic topic.

Method Summary

Iterator	allNext() In case there are multiple next() options, this returns an iterator over the entire set of topics located by hasNext().
int	getState() Returns the current traversal state as an int.
boolean	hasNext() Returns true if the iterator has more elements (i.e., returns true if next would return an element rather than throwing an exception.)
Object	next() Returns the next element (a Topic) in the iteration.
void	remove()
protected boolean	roleCheck(Topic t, Locator fwd, Locator rev) Returns true if the direction and role match.
void	setAllowLoops(boolean allowLoops) Sets the value of the internal variable to allowLoops, controlling whether or not to traverse to Topics that have been seen before.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TRAVERSE_FROM

public static final int TRAVERSE_FROM

An int constant indicating a 'From' traversal direction, i.e., against the direction of arrows, to-to-from.

See Also:

Constant Field Values

TRAVERSE_TO

public static final int TRAVERSE_TO

An int constant indicating a 'To' traversal direction, i.e., in the direction of arrows, from-to-to.

See Also:

Constant Field Values

STATE_UNKNOWN

public static final int STATE_UNKNOWN

An int constant indicating that the traversal state is unknown.

See Also:

Constant Field Values

STATE_NO_TRAVERSE

public static final int STATE_NO_TRAVERSE

An int constant indicating that no traversal is possible from the current Topic.

See Also:

Constant Field Values

STATE_IN_SEQUENCE

public static final int STATE_IN_SEQUENCE

An int constant indicating that the traversal is in sequence (i.e., either next or previous, depending on current direction).

See Also:

Constant Field Values

STATE_AMBIGUOUS

public static final int STATE_AMBIGUOUS

An int constant indicating that the next traversal is not necessarily in a strict sequence (i.e., there may be more than one option in the next traversal).

See Also:

Constant Field Values

Constructor Detail

SequenceIterator

public SequenceIterator(Topic index,
                        int direction,
                        boolean allowLoops)
                 throws TopicMapException

Creates an Iterator provided the starting Topic topic. If the traversal is of a linear sequence, the iterator will return the Topics in correct order. If the Topics form a graph, the iteration order is determined by the traversal order: i.e., all bets are off.

This method uses the hardwired PSIs for sequences, including the association type "sequence" and the two roles, "to" and "from". When set to disallow loops, hasNext() returns false on iterating to a Topic that it has already seen.

Parameters:

index - the Topic from which the sequence traversal begins

direction - an enumerated int setting traversal direction

allowLoops - when false, hasNext() will return false on traversing

Throws:

TopicMapException

Method Detail

hasNext

public boolean hasNext()

Returns true if the iterator has more elements (i.e., returns true if next would return an element rather than throwing an exception.)

Specified by:

hasNext in interface Iterator

Returns:

true if the iterator has more elements.

next

public Object next()

Returns the next element (a Topic) in the iteration.

Specified by:

next in interface Iterator

Returns:

the next element in the iteration.

Throws:

NoSuchElementException - iteration has no more elements.

setAllowLoops

public void setAllowLoops(boolean allowLoops)

Sets the value of the internal variable to allowLoops, controlling whether or not to traverse to Topics that have been seen before.

getState

public int getState()

Returns the current traversal state as an int.

allNext

public Iterator allNext()

In case there are multiple next() options, this returns an iterator over the entire set of topics located by hasNext().

Note:
If hasNext() is called while this Iterator is still active, a ConcurrentModificationException will not be thrown (since its reference to the underlying Collection is just removed), but the Iterator returned from this method will no longer be valid.

roleCheck

protected boolean roleCheck(Topic t,
                            Locator fwd,
                            Locator rev)

Returns true if the direction and role match. Null values for the Locators will cause checks in that direction to be ignored.

remove

public void remove()

Specified by:

remove in interface Iterator