TraversalDescription (Neo4j Community 2.1.0-M01 API)
Date: 2014-02-20

org.neo4j.graphdb.traversal

## Interface TraversalDescription

-     public interface TraversalDescription

  Represents a description of a traversal. This interface describes the rules and behavior of a traversal. A traversal description is immutable and each method which adds or modifies the behavior returns a new instances that includes the new modification, leaving the instance which returns the new instance intact. For instance,

       TraversalDescription td = new TraversalDescriptionImpl();
       td.depthFirst();

  is not going to modify td. you will need to reassign td, like

       td = td.depthFirst();

  When all the rules and behaviors have been described the traversal is started by using `traverse(Node)` where a starting node is supplied. The `Traverser` that is returned is then used to step through the graph, and return the positions that matches the rules.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `TraversalDescription` | `breadthFirst()` A convenience method for `order(BranchOrderingPolicy)` where a "preorder breadth first" selector is used.
    `TraversalDescription` | `depthFirst()` A convenience method for `order(BranchOrderingPolicy)` where a "preorder depth first" selector is used.
    `TraversalDescription` | `evaluator(Evaluator evaluator)` Adds `evaluator` to the list of evaluators which will control the behavior of the traversal.
    `TraversalDescription` | `evaluator(PathEvaluator evaluator)` Adds `evaluator` to the list of evaluators which will control the behavior of the traversal.
    `TraversalDescription` | `expand(PathExpander<?> expander)` Sets the `PathExpander` as the expander of relationships, discarding all previous calls to `relationships(RelationshipType)` and `relationships(RelationshipType, Direction)` or any other expand method.
    `<STATE> TraversalDescription` | `expand(PathExpander<STATE> expander, InitialBranchState<STATE> initialState)` Sets the `PathExpander` as the expander of relationships, discarding all previous calls to `relationships(RelationshipType)` and `relationships(RelationshipType, Direction)` or any other expand method.
    `<STATE> TraversalDescription` | `expand(PathExpander<STATE> expander, InitialStateFactory<STATE> initialState)` Deprecated. Because InitialStateFactory is deprecated
    `TraversalDescription` | `expand(RelationshipExpander expander)` Deprecated. Because RelationshipExpander is deprecated
    `TraversalDescription` | `order(BranchOrderingPolicy selector)` Sets the `BranchOrderingPolicy` to use.
    `TraversalDescription` | `relationships(RelationshipType type)` Adds `type` to the list of relationship types to traverse.
    `TraversalDescription` | `relationships(RelationshipType type, Direction direction)` Adds `type` to the list of relationship types to traverse in the given `direction`.
    `TraversalDescription` | `reverse()` Creates an identical `TraversalDescription`, although reversed in how it traverses the graph.
    `TraversalDescription` | `sort(Comparator<? super Path> comparator)`
    `Traverser` | `traverse(Node... startNodes)` Traverse from a set of start nodes based on all the rules and behavior in this description.
    `Traverser` | `traverse(Node startNode)` Traverse from a single start node based on all the rules and behavior in this description.
    `TraversalDescription` | `uniqueness(UniquenessFactory uniqueness)` Sets the `UniquenessFactory` for creating the `UniquenessFilter` to use.
    `TraversalDescription` | `uniqueness(UniquenessFactory uniqueness, Object parameter)` Sets the `UniquenessFactory` for creating the `UniquenessFilter` to use.

- - ### Method Detail

    - #### uniqueness

          TraversalDescription uniqueness(UniquenessFactory uniqueness)

      Sets the `UniquenessFactory` for creating the `UniquenessFilter` to use.
      Parameters:
        `uniqueness` - the `UniquenessFactory` the creator of the desired `UniquenessFilter` to use.
      Returns:
        a new traversal description with the new modifications.

    - #### uniqueness

          TraversalDescription uniqueness(UniquenessFactory uniqueness,
                                        Object parameter)

      Sets the `UniquenessFactory` for creating the `UniquenessFilter` to use. It also accepts an extra parameter which is mandatory for certain uniqueness's, f.ex `Uniqueness.NODE_RECENT`.
      Parameters:
        `uniqueness` - the `UniquenessFactory` the creator of the desired `UniquenessFilter` to use.
      Returns:
        a new traversal description with the new modifications.

    - #### evaluator

          TraversalDescription evaluator(Evaluator evaluator)

      Adds `evaluator` to the list of evaluators which will control the behavior of the traversal. Each `Evaluator` can decide whether or not to include a position in the traverser result, i.e. return it from the `Traverser` iterator and also whether to continue down that path or to prune, so that the traverser won't continue further down that path. Multiple `Evaluator`s can be added. For a path to be included in the result, all evaluators must agree to include it, i.e. returning either `Evaluation.INCLUDE_AND_CONTINUE` or `Evaluation.INCLUDE_AND_PRUNE`. For making the traversal continue down that path all evaluators must agree to continue from that path, i.e. returning either `Evaluation.INCLUDE_AND_CONTINUE` or `Evaluation.EXCLUDE_AND_CONTINUE`.
      Parameters:
        `evaluator` -
      Returns:
        a new traversal description with the new modifications.

    - #### evaluator

          TraversalDescription evaluator(PathEvaluator evaluator)

      Adds `evaluator` to the list of evaluators which will control the behavior of the traversal. Each `PathEvaluator` can decide whether or not to include a position in the traverser result, i.e. return it from the `Traverser` iterator and also whether to continue down that path or to prune, so that the traverser won't continue further down that path. Multiple `PathEvaluator`s can be added. For a path to be included in the result, all evaluators must agree to include it, i.e. returning either `Evaluation.INCLUDE_AND_CONTINUE` or `Evaluation.INCLUDE_AND_PRUNE`. For making the traversal continue down that path all evaluators must agree to continue from that path, i.e. returning either `Evaluation.INCLUDE_AND_CONTINUE` or `Evaluation.EXCLUDE_AND_CONTINUE`.
      Parameters:
        `evaluator` -
      Returns:
        a new traversal description with the new modifications.

    - #### order

          TraversalDescription order(BranchOrderingPolicy selector)

      Sets the `BranchOrderingPolicy` to use. A `BranchSelector` is the basic decisions in the traversal of "where to go next". Examples of default implementations are "breadth first" and "depth first", which can be set with convenience methods `breadthFirst()` and `depthFirst()`.
      Parameters:
        `selector` - the factory which creates the `BranchSelector` to use with the traversal.
      Returns:
        a new traversal description with the new modifications.

    - #### depthFirst

          TraversalDescription depthFirst()

      A convenience method for `order(BranchOrderingPolicy)` where a "preorder depth first" selector is used. Positions which are deeper than the current position will be returned before positions on the same depth. See http://en.wikipedia.org/wiki/Depth-first_search
      Returns:
        a new traversal description with the new modifications.

    - #### breadthFirst

          TraversalDescription breadthFirst()

      A convenience method for `order(BranchOrderingPolicy)` where a "preorder breadth first" selector is used. All positions with the same depth will be returned before advancing to the next depth. See http://en.wikipedia.org/wiki/Breadth-first_search
      Returns:
        a new traversal description with the new modifications.

    - #### relationships

          TraversalDescription relationships(RelationshipType type)

      Adds `type` to the list of relationship types to traverse. There's no priority or order in which types to traverse.
      Parameters:
        `type` - the `RelationshipType` to add to the list of types to traverse.
      Returns:
        a new traversal description with the new modifications.

    - #### relationships

          TraversalDescription relationships(RelationshipType type,
                                           Direction direction)

      Adds `type` to the list of relationship types to traverse in the given `direction`. There's no priority or order in which types to traverse.
      Parameters:
        `type` - the `RelationshipType` to add to the list of types to traverse.
        `direction` - the `Direction` to traverse this type of relationship in.
      Returns:
        a new traversal description with the new modifications.

    - #### expand

          TraversalDescription expand(PathExpander<?> expander)

      Sets the `PathExpander` as the expander of relationships, discarding all previous calls to `relationships(RelationshipType)` and `relationships(RelationshipType, Direction)` or any other expand method.
      Parameters:
        `expander` - the `PathExpander` to use.
      Returns:
        a new traversal description with the new modifications.

    - #### expand

          <STATE> TraversalDescription expand(PathExpander<STATE> expander,
                                            InitialStateFactory<STATE> initialState)

      Deprecated. Because InitialStateFactory is deprecated
      Sets the `PathExpander` as the expander of relationships, discarding all previous calls to `relationships(RelationshipType)` and `relationships(RelationshipType, Direction)` or any other expand method. The supplied `InitialStateFactory` will provide the initial traversal branches with state values which flows down throughout the traversal and can be changed for child branches by the `PathExpander` at any level.
      Parameters:
        `expander` - the `PathExpander` to use.
        `initialState` - factory for supplying the initial traversal branches with state values potentially used by the `PathExpander`.
      Returns:
        a new traversal description with the new modifications.

    - #### expand

          <STATE> TraversalDescription expand(PathExpander<STATE> expander,
                                            InitialBranchState<STATE> initialState)

      Sets the `PathExpander` as the expander of relationships, discarding all previous calls to `relationships(RelationshipType)` and `relationships(RelationshipType, Direction)` or any other expand method. The supplied `InitialBranchState` will provide the initial traversal branches with state values which flows down throughout the traversal and can be changed for child branches by the `PathExpander` at any level.
      Parameters:
        `expander` - the `PathExpander` to use.
        `initialState` - factory for supplying the initial traversal branches with state values potentially used by the `PathExpander`.
      Returns:
        a new traversal description with the new modifications.

    - #### expand

          TraversalDescription expand(RelationshipExpander expander)

      Deprecated. Because RelationshipExpander is deprecated
      Sets the `RelationshipExpander` as the expander of relationships, discarding all previous calls to `relationships(RelationshipType)` and `relationships(RelationshipType, Direction)` or any other expand method.
      Parameters:
        `expander` - the `RelationshipExpander` to use.
      Returns:
        a new traversal description with the new modifications.

    - #### sort

          TraversalDescription sort(Comparator<? super Path> comparator)

      Parameters:
        `comparator` - the `Comparator` to use for sorting the paths.
      Returns:
        the paths from this traversal sorted according to `comparator`.

    - #### reverse

          TraversalDescription reverse()

      Creates an identical `TraversalDescription`, although reversed in how it traverses the graph.
      Returns:
        a new traversal description with the new modifications.

    - #### traverse

          Traverser traverse(Node startNode)

      Traverse from a single start node based on all the rules and behavior in this description. A `Traverser` is returned which is used to step through the graph and getting results back. The traversal is not guaranteed to start before the Traverser is used.
      Parameters:
        `startNode` - `Node` to start traversing from.
      Returns:
        a `Traverser` used to step through the graph and to get results from.

    - #### traverse

          Traverser traverse(Node... startNodes)

      Traverse from a set of start nodes based on all the rules and behavior in this description. A `Traverser` is returned which is used to step through the graph and getting results back. The traversal is not guaranteed to start before the Traverser is used.
      Parameters:
        `startNodes` - `Node`s to start traversing from.
      Returns:
        a `Traverser` used to step through the graph and to get results from.

Copyright © 2002–2014 The Neo4j Graph Database Project. All rights reserved.