Package ninja.leaping.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.

See Also:

to execute this configuration visitation

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	ConfigurationVisitor.Safe<S,T>	A subinterface for visitors that do not throw any checked exceptions during their execution
static interface	ConfigurationVisitor.Stateless<E extends Exception>	Stateless specialization of visitors, where both the state and terminal type are Void

Method Summary

Modifier and Type	Method	Description
void	beginVisit(ConfigurationNode node, S state)	Called at the beginning of the visit with a state object created.
T	endVisit(S state)	Called after every node has been visited, to allow for cleanup and validation
void	enterListNode(ConfigurationNode node, S state)	Called after enterNode(ConfigurationNode, Object) for list nodes
void	enterMappingNode(ConfigurationNode node, S state)	Called after enterNode(ConfigurationNode, Object) for mapping nodes
void	enterNode(ConfigurationNode node, S state)	Called once per node, for every node
void	enterScalarNode(ConfigurationNode node, S state)	Called after enterNode(ConfigurationNode, Object) for scalar nodes
void	exitListNode(ConfigurationNode node, S state)	Called for a list node after the node and any of its children have been visited
void	exitMappingNode(ConfigurationNode node, S state)	Called for a list node after the node and any of its children have been visited
S	newState()	Called to provide a state object if a visit is initiated without one already existing

Method Detail

newState

S newState()
    throws E extends Exception

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

E extends Exception

beginVisit

void beginVisit(ConfigurationNode node,
                S state)
         throws E extends Exception

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

E extends Exception

enterNode

void enterNode(ConfigurationNode node,
               S state)
        throws E extends Exception

Called once per node, for every node

Parameters:

node - The current node

state - provided state

Throws:

E - when thrown by implementation

E extends Exception

enterMappingNode

void enterMappingNode(ConfigurationNode node,
                      S state)
               throws E extends Exception

Called after enterNode(ConfigurationNode, Object) for mapping nodes

Parameters:

node - current node

state - provided state

Throws:

E - when thrown by implementation

E extends Exception

enterListNode

void enterListNode(ConfigurationNode node,
                   S state)
            throws E extends Exception

Called after enterNode(ConfigurationNode, Object) for list nodes

Parameters:

node - current node

state - provided state

Throws:

E - when thrown by implementation

E extends Exception

enterScalarNode

void enterScalarNode(ConfigurationNode node,
                     S state)
              throws E extends Exception

Called after enterNode(ConfigurationNode, Object) for scalar nodes

Parameters:

node - current node

state - provided state

Throws:

E - when thrown by implementation

E extends Exception

exitMappingNode

void exitMappingNode(ConfigurationNode node,
                     S state)
              throws E extends Exception

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

E extends Exception

exitListNode

void exitListNode(ConfigurationNode node,
                  S state)
           throws E extends Exception

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

E extends Exception

endVisit

T endVisit(S state)
    throws E extends Exception

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

E extends Exception