Package org.spongepowered.configurate

Interface ConfigurationVisitor<S,T,E extends Exception>

Type Parameters:
S - a state object that will be used for one visit
T - the terminal value, that can be returned at the end of the visit
E - exception type that may be thrown
All Known Subinterfaces:
ConfigurationVisitor.Safe<S,T>, ConfigurationVisitor.Stateless<E>
public interface ConfigurationVisitor<S,T,E extends Exception>
A visitor to traverse node hierarchies in a depth-first order.

Instances of stateful implementations may be reusable by taking advantage of the state object. During each visitation, a visitor will experience the node tree as a sequence of events, described by the following pseudo-grammar:

 mappingNode: enterMappingNode node* exitMappingNode
 listNode: enterListNode node* exitListNode

 node: enterNode
      (mappingNode
       | listNode
       | enterScalarNode)

 visit: newState?
        beginVisit
        node*
        endVisit

If the starting node has no value, no node events will be received. Otherwise, the first event received will be for the starting node itself, and will continue from there.

The children to visit for list and mapping nodes will only be collected after both the enterNode and enter(List|Mapping)Node methods have been executed for the node, and changes to the node values may be made to control which nodes will be visited.

Any exceptions thrown within the visitor will result in the visitation ending immediately and the exception being rethrown within the visit method.

There are a few specializations of the visitor interface available: ConfigurationVisitor.Stateless carries no state and can act as a functional interface type, and ConfigurationVisitor.Safe which throws no checked exceptions and therefore can be visited without having to handle any exceptions.

Since:
4.0.0
See Also:

  • Method Details

    • newState

      S newState() throws E
      Called to provide a state object if a visit is initiated without one already existing.
      Returns:
      a new state object to be passed through the rest of this visit
      Throws:
      E - when thrown by implementation
      Since:
      4.0.0

    • beginVisit

      void beginVisit(ConfigurationNode node, S state) throws E
      Called at the beginning of the visit with a state object created.
      Parameters:
      node - the root node
      state - the state
      Throws:
      E - when thrown by implementation
      Since:
      4.0.0

    • enterNode

      void enterNode(ConfigurationNode node, S state) throws E
      Called once per node, for every node.
      Parameters:
      node - the current node
      state - provided state
      Throws:
      E - when thrown by implementation
      Since:
      4.0.0

    • enterMappingNode

      void enterMappingNode(ConfigurationNode node, S state) throws E
      Called after enterNode(ConfigurationNode, Object) for mapping nodes.
      Parameters:
      node - current node
      state - provided state
      Throws:
      E - when thrown by implementation
      Since:
      4.0.0

    • enterListNode

      void enterListNode(ConfigurationNode node, S state) throws E
      Called after enterNode(ConfigurationNode, Object) for list nodes.
      Parameters:
      node - current node
      state - provided state
      Throws:
      E - when thrown by implementation
      Since:
      4.0.0

    • enterScalarNode

      void enterScalarNode(ConfigurationNode node, S state) throws E
      Called after enterNode(ConfigurationNode, Object) for scalar nodes.
      Parameters:
      node - current node
      state - provided state
      Throws:
      E - when thrown by implementation
      Since:
      4.0.0

    • exitMappingNode

      void exitMappingNode(ConfigurationNode node, S state) throws E
      Called for a list node after the node and any of its children have been visited.
      Parameters:
      node - the node that has been visited
      state - provided state
      Throws:
      E - when thrown by implementation
      Since:
      4.0.0

    • exitListNode

      void exitListNode(ConfigurationNode node, S state) throws E
      Called for a list node after the node and any of its children have been visited.
      Parameters:
      node - the node that has been visited
      state - provided state
      Throws:
      E - when thrown by implementation
      Since:
      4.0.0

    • endVisit

      T endVisit(S state) throws E
      Called after every node has been visited, to allow for cleanup and validation.
      Parameters:
      state - provided state
      Returns:
      a terminal value
      Throws:
      E - when thrown by implementation
      Since:
      4.0.0