Package com.apicatalog.tree.io

Class TreeTraversal

java.lang.Object
com.apicatalog.tree.io.TreeTraversal
Direct Known Subclasses:
NativeMaterializer
public class TreeTraversal extends Object
Provides a stateful, non-recursive, depth-first iterator for arbitrary tree-like structures. This class decouples the traversal algorithm from the concrete representation of the tree by operating on the TreeAdapter abstraction.

It can be used in two primary ways:

  1. Manual Iteration: By repeatedly calling the next() method in a loop, you can process each node individually, allowing for complex logic like searching, validation, or conditional processing.
  2. Automated Transformation: The traverse(TreeGenerator) method provides a high-level utility to walk the entire tree and drive a TreeGenerator, effectively translating or transforming one tree representation into another.

Traversal Rules:

  • When visiting a map, keys are visited before their corresponding values. The order of keys can be controlled with a custom Comparator.
  • When visiting a collection, elements are visited in their natural iteration order.

  • Field Details

    • UNLIMITED_DEPTH

      public static final int UNLIMITED_DEPTH
      A sentinel value indicating that traversal depth is not limited.
      See Also:

    • UNLIMITED_NODES

      public static final int UNLIMITED_NODES
      A sentinel value indicating that the number of visited nodes is not limited.
      See Also:

    • adapters

      protected final Deque<TreeAdapter> adapters

    • stack

      protected final Deque<Object> stack

    • entryComparator

      protected Comparator<Map.Entry<?,?>> entryComparator

    • maxVisited

      protected int maxVisited

    • maxDepth

      protected int maxDepth

    • depth

      protected int depth

    • visited

      protected int visited

    • currentNode

      protected Object currentNode

    • currentNodeType

      protected NodeType currentNodeType

    • currentNodeContext

      protected TreeTraversal.Context currentNodeContext

  • Constructor Details

  • Method Details

    • traverse

      public void traverse(Consumer<TreeTraversal> consumer)

    • traverse

      public void traverse(TreeGenerator generator) throws TreeIOException
      A high-level utility method that fully traverses the tree and drives the provided TreeGenerator. This is the primary method for tree transformation, serialization, or deep cloning. It iterates through every node using next() and emits a corresponding event to the generator.
      Parameters:
      generator - the generator that will receive construction events.
      Throws:
      TreeIOException - if the generator encounters an I/O error.
      IllegalStateException - if the source tree is malformed (e.g., unclosed structures).

    • next

      public boolean next()
      Advances the traversal to the next node in the depth-first sequence.

      Each call to this method processes exactly one node or structural marker. After a successful call, the visitor's state is updated, and the details of the current item can be accessed via node(), nodeType(), and nodeContext().

      Returns:
      true if the traversal advanced to a new item, or false if the traversal is complete.
      Throws:
      IllegalStateException - if the traversal exceeds configured limits (e.g., maximum depth or node count).

    • next

      protected boolean next(TreeTraversal.Context stepContext)

    • reset

      public TreeTraversal reset()
      Resets the visitor's internal state, clearing the traversal stack and counters. The visitor can be reused after calling this method, but a new root node must be set using root(Object, TreeAdapter).
      Returns:
      this instance, for chaining.

    • root

      public TreeTraversal root(Object node, TreeAdapter adapter)
      Sets the root node for the traversal, initializing the visitor's stack.
      Parameters:
      node - the new root node.
      adapter - the adapter for interpreting the new tree structure.
      Returns:
      this instance, for chaining.

    • visited

      public long visited()
      Gets the total number of nodes visited so far.

    • maxDepth

      public void maxDepth(int maxDepth)
      Sets the maximum traversal depth. If the traversal reaches this depth, it will not process the children of nodes at that depth.
      Parameters:
      maxDepth - the maximum depth, or UNLIMITED_DEPTH for no limit.

    • maxDepth

      public int maxDepth()
      Gets the configured maximum traversal depth.
      Returns:
      the maximum depth, or UNLIMITED_DEPTH if no limit is set.

    • maxVisited

      public void maxVisited(int maxVisitedNodes)
      Sets the maximum number of nodes to visit. The traversal will throw an IllegalStateException if this limit is exceeded.
      Parameters:
      maxVisitedNodes - the maximum number of nodes, or UNLIMITED_NODES for no limit.

    • maxVisited

      public int maxVisited()
      Gets the configured maximum number of nodes to visit.
      Returns:
      the maximum node count, or UNLIMITED_NODES if no limit is set.

    • adapter

      public TreeAdapter adapter()
      Gets the adapter to process the #currentNode().

    • node

      public Object node()
      Gets the current node being processed.

    • nodeType

      public NodeType nodeType()
      Gets the type of the current node.

    • nodeContext

      public TreeTraversal.Context nodeContext()
      Gets the context of the current node.