Package com.apicatalog.tree.io

Class NodeVisitor

java.lang.Object
com.apicatalog.tree.io.NodeVisitor
Direct Known Subclasses:
NodeGenerator
public class NodeVisitor extends Object
A non-recursive depth-first traversal for arbitrary trees.

Traverses trees in depth-first order, visiting nodes one at a time via step(). The traversal distinguishes between the root node, map property keys and values, and collection elements using NodeVisitor.Context.

Traversal rules:

  • When visiting a map-like node, keys are visited before their corresponding values.
  • When visiting a collection or array node, elements are visited in insertion order.
  • Other node types are visited directly.

Traversal proceeds until all nodes have been visited or limits (maximum depth or maximum nodes) are reached.

  • Field Details

    • UNLIMITED_DEPTH

      public static final int UNLIMITED_DEPTH
      Sentinel value indicating no maximum depth limit.
      See Also:

    • UNLIMITED_NODES

      public static final int UNLIMITED_NODES
      Sentinel value indicating no maximum node visit limit.
      See Also:

    • maxVisited

      protected int maxVisited
      Maximum number of nodes allowed to be visited.

    • maxDepth

      protected int maxDepth
      Maximum depth allowed during traversal.

    • stack

      protected final Deque<Object> stack
      Stack used for traversal.

    • entryComparator

      protected Comparator<Map.Entry<?,?>> entryComparator
      Comparator for map entries.

    • adapter

      protected NodeAdapter adapter
      Adapter providing access to node types and children.

    • depth

      protected long depth
      Current depth.

    • visited

      protected long visited
      Number of nodes visited.

    • node

      protected Object node
      Current node.

    • nodeType

      protected NodeType nodeType
      Type of the current node.

    • nodeContext

      protected NodeVisitor.Context nodeContext
      Role of the current node.

  • Constructor Details

    • NodeVisitor

      protected NodeVisitor(Deque<Object> stack, NodeAdapter adapter)
      Creates a new traversal with the given stack and adapter.
      Parameters:
      stack - the stack to use for traversal state
      adapter - the adapter providing node access

    • NodeVisitor

      protected NodeVisitor(Deque<Object> stack, NodeAdapter adapter, Comparator<Map.Entry<?,?>> entryComparator)

  • Method Details

    • of

      public static NodeVisitor of(Object root, NodeAdapter adapter)
      Creates a new NodeVisitor starting at the given root node, using the default property key ordering - insertion order.
      Parameters:
      root - the root node to start traversal from, must not be null
      adapter - the adapter providing access to node types and children, must not be null
      Returns:
      a new NodeVisitor instance positioned at the root node
      Throws:
      NullPointerException - if root or adapter is null

    • of

      public static NodeVisitor of(Object root, NodeAdapter adapter, Comparator<Map.Entry<?,?>> propertyComparator)
      Creates a new NodeVisitor starting at the given root node, using a custom comparator for ordering map property keys.
      Parameters:
      root - the root node to start traversal from, must not be null
      adapter - the adapter providing access to node types and children, must not be null
      propertyComparator - comparator used to order map keys during traversal, must not be null
      Returns:
      a new NodeVisitor instance positioned at the root node
      Throws:
      NullPointerException - if root, adapter, or propertyComparator is null

    • step

      public boolean step()
      Advances the traversal by one step.

      Processes exactly one node, updating node, nodeType, and nodeContext to describe it. Subsequent calls continue traversal until the entire tree has been visited.

      Returns:
      true if a node was processed, or false if traversal is complete
      Throws:
      IllegalStateException - if the traversal exceeds the maximum node count or the maximum depth configured via maxVisited(int) or maxDepth(int)

    • visited

      public long visited()
      Returns the number of nodes visited.

    • reset

      public void reset(Object node, NodeAdapter adapter)
      Resets the traversal with a new root node and adapter.
      Parameters:
      node - the new root node
      adapter - the adapter providing access to node types

    • keyComparator

      public void keyComparator(Comparator<Map.Entry<?,?>> keyComparator)
      Sets the comparator used to order map property keys during traversal.

      The comparator determines the order in which map keys are visited. By default, keys are visited in insertion order if no comparator is set.

      Parameters:
      keyComparator - comparator for map keys; must not be null

    • maxDepth

      public void maxDepth(int maxDepth)
      Sets the maximum depth of traversal.

      If the traversal reaches this depth, further children will not be visited. Use UNLIMITED_DEPTH (-1) to indicate no depth limit (default).

      Parameters:
      maxDepth - maximum depth allowed during traversal

    • maxDepth

      public int maxDepth()
      Returns the maximum depth allowed during traversal.
      Returns:
      maximum depth; -1 if no limit

    • maxVisited

      public void maxVisited(int maxVisitedNodes)
      Sets the maximum number of nodes that can be visited during traversal.

      If the number of visited nodes reaches this limit, step() will throw IllegalStateException. Use UNLIMITED_NODES (-1) to indicate no limit (default).

      Parameters:
      maxVisitedNodes - maximum number of nodes to visit

    • maxVisited

      public int maxVisited()
      Returns the maximum number of nodes that can be visited during traversal.
      Returns:
      maximum number of nodes; -1 if no limit