com.phoenixst.plexus
Interface Traverser

All Superinterfaces:

Iterator

All Known Subinterfaces:

PruningTraverser

All Known Implementing Classes:

BreadthFirstTraverser, DepthFirstTraverser, EdgeIteratorTraverserAdapter, FilteredTraverser, LoggingTraverser, PostOrderTraverser, PreOrderTraverser, SingletonTraverser, TopologicalSortTraverser, TraverserChain, UnmodifiableTraverser, Walker

public interface Traverser
extends Iterator

An interface for traversing through nodes in a Graph. An edge is followed to reach every visited node, or at least most of them. For example, the start node of a breadth first search is not reached through an edge.

The hasNext() method is not consistent with that defined by Iterator. Since remove() will generally also remove a number of edges as a side-effect, hasNext() may return true before a call to remove(), but return false afterwards. Since the idiom is to call hasNext() just before calling next(), this is not normally an issue.

Note that a traverser does not necessarily move from one node to the next, following a chain of edges; that is, it is not generally a linear path.

In addition, unlike the typical node iterator, the nodes returned by next() are not necessarily distinct. This is because a traverser follows edges according to some criteria, and a traversal may touch the same node more than once. This is trivially true in multigraphs and some traversals will reach the same node twice if the graph contains cycles.

Since:

1.0

Version:

$Revision: 1.13 $

Author:

Ray A. Conner

Method Summary

Graph.Edge	getEdge() Returns the Edge which was traversed to get to the last node returned by next(), or null if no Edge was traversed.
void	removeEdge() Removes from the underlying Graph the Edge that would be returned by getEdge() (optional operation).

Methods inherited from interface java.util.Iterator

hasNext, next, remove

Method Detail

getEdge

Graph.Edge getEdge()

Returns the Edge which was traversed to get to the last node returned by next(), or null if no Edge was traversed. This call can be made only if remove() or removeEdge() has not been called after the last call to next().

Returns:

The Edge which was traversed to get to the last node returned by next(), or null if no Edge was traversed.

Throws:

IllegalStateException - if next() has not yet been called, or remove() or removeEdge() has been called after the last call to next().

removeEdge

void removeEdge()

Removes from the underlying Graph the Edge that would be returned by getEdge() (optional operation). If no Edge was traversed (as in the root of a breadth-first search), this method throws a IllegalStateException. This method can be called only once per call to next(). The behavior of a traverser is unspecified if the underlying graph structure is modified while the traversal is in progress in any way other than by calling this method or remove().

Throws:

IllegalStateException - if next() has not yet been called, or remove() or removeEdge has been called after the last call to next(), or no Edge was traversed to reach the last node returned by next().

UnsupportedOperationException - if this method is not supported by this Traverser.