org.neo4j.graphdb
Interface Traverser

All Superinterfaces:

Iterable<Node>

public interface Traverser
extends Iterable<Node>

A traversal in the node space. A Traverser is an Iterable that encapsulates a number of traversal parameters (defined at traverser creation) and returns an iterator of nodes that match those parameters. It is created by invoking Node.traverse(...). Upon creation, the traverser is positioned at the start node, but it doesn't actually start traversing until its iterator().next() method is invoked and will then traverse lazily one step each time next is called.

When a Traverser is created it is parameterized with two evaluators and the relationship types to traverse, with the direction to traverse each type in. The evaluators are used for determining for each node in the set of candidate nodes if it should be returned or not, and if the traversal should be pruned (stopped) at this point. The nodes that are traversed by a Traverser are each visited exactly once, meaning that the returned iterator of nodes will never contain duplicate nodes. This also means that the traversed relationships will form a spanning tree over the traversed nodes, with the side effect that some internal relationships between nodes in the traversal are not traversed (and hence not visible in the evaluators).

Typically a Traverser is used in a for-each loop as follows:

 
 Traverser friends = node.traverse( Order.BREADTH_FIRST,
     StopEvaluator.END_OF_GRAPH, ReturnableEvaluator.ALL_BUT_START_NODE,
     MyRelationshipTypes.KNOWS, Direction.OUTGOING );
 for ( Node friend : friends )
 {
     // ...
 }
 
 

Relationships are equally well traversed regardless of their direction, performance-wise.

For more usage examples please refer to the wiki documentation.

See Also:

Node.traverse(org.neo4j.graphdb.Traverser.Order, org.neo4j.graphdb.StopEvaluator, org.neo4j.graphdb.ReturnableEvaluator, org.neo4j.graphdb.RelationshipType, org.neo4j.graphdb.Direction)

Nested Class Summary

static class

Traverser.Order Defines a traversal order as used by the traversal framework.

Method Summary

TraversalPosition	currentPosition() Returns the current traversal position, that is where the traversal is at the moment.
Collection<Node>	getAllNodes() Returns a collection of all nodes for this traversal.
Iterator<Node>	iterator() Returns an Iterator representing the traversal of the graph.

Method Detail

currentPosition

TraversalPosition currentPosition()

Returns the current traversal position, that is where the traversal is at the moment. It contains information such as which node we're at, which the last traversed relationship was (if any) and at which depth the current position is (relative to the starting node). You can use it in your traverser for-loop like this:

 
 Traverser traverser = node.traverse( ... );
 for ( Node node : traverser )
 {
     TraversalPosition currentPosition = traverser.currentPosition();
     // Get "current position" information right here.
 }
 
 

Returns:

The current traversal position

getAllNodes

Collection<Node> getAllNodes()

Returns a collection of all nodes for this traversal. It traverses through the graph (according to given filters and evaluators) and collects those encountered nodes along the way. When this method has returned, this traverser will be at the end of its traversal, such that a call to hasNext() for the iterator() will return false.

Returns:

A collection of all nodes for this this traversal.

iterator

Iterator<Node> iterator()

Returns an Iterator representing the traversal of the graph. The iteration is completely lazy in that it will only traverse one step (to the next "hit") for every call to hasNext()/next(). Consecutive calls to this method will return the same instance.

Specified by:

iterator in interface Iterable<Node>

Returns:

An iterator for this traverser