org.apache.commons.configuration2.tree

Interface NodeModel<T>

Type Parameters:

T - the type of the nodes managed by this model

All Known Implementing Classes:

InMemoryNodeModel, TrackedNodeModel

public interface NodeModel<T>

Definition of an interface describing a model based on a nodes structure.

This interface can be used for dealing with hierarchical, tree-like data. It defines basic operations for manipulating the tree structure which use keys to select the nodes affected.

The idea behind this interface is that concrete implementations can be used by hierarchical configurations. This makes it possible to integrate various hierarchical structures with the API of a hierarchical configuration, e.g. configuration nodes stored in memory, JNDI contexts, or other structures. The configuration object interacts with the underlying data structure via this interface. For more complex operations access to an ExpressionEngine may be required in order to interpret the passed in keys. For these purposes a NodeKeyResolver has to be provided which knows how to deal with keys.

Since:

2.0

Method Summary

Modifier and Type	Method and Description
void	addNodes(String key, Collection<? extends T> nodes, NodeKeyResolver<T> resolver) Adds a collection of new nodes to this model.
void	addProperty(String key, Iterable<?> values, NodeKeyResolver<T> resolver) Adds a new property to this node model consisting of an arbitrary number of values.
void	clear(NodeKeyResolver<T> resolver) Removes all data from this model.
void	clearProperty(String key, NodeKeyResolver<T> resolver) Clears the value of a property.
Object	clearTree(String key, NodeKeyResolver<T> resolver) Removes the sub trees defined by the given key from this model.
ImmutableNode	getInMemoryRepresentation() Returns a representation of the data stored in this model in form of a nodes hierarchy of ImmutableNode objects.
NodeHandler<T>	getNodeHandler() Returns a NodeHandler for dealing with the nodes managed by this model.
void	setProperty(String key, Object value, NodeKeyResolver<T> resolver) Changes the value of a property.
void	setRootNode(T newRoot) Sets a new root node for this model.

Method Detail

setRootNode

void setRootNode(T newRoot)

Sets a new root node for this model. The whole structure is replaced by the new node and its children.

Parameters:

newRoot - the new root node to be set (can be null, then an empty root node is set)

getNodeHandler

NodeHandler<T> getNodeHandler()

Returns a NodeHandler for dealing with the nodes managed by this model.

Returns:

the NodeHandler

addProperty

void addProperty(String key,
                 Iterable<?> values,
                 NodeKeyResolver<T> resolver)

Adds a new property to this node model consisting of an arbitrary number of values. The key for the add operation is provided. For each value a new node has to be added. The passed in resolver is queried for a NodeAddData object defining the add operation to be performed.

Parameters:

key - the key

values - the values to be added at the position defined by the key

resolver - the NodeKeyResolver

addNodes

void addNodes(String key,
              Collection<? extends T> nodes,
              NodeKeyResolver<T> resolver)

Adds a collection of new nodes to this model. This operation corresponds to the addNodes() method of the HierarchicalConfiguration interface. The new nodes are either added to an existing node (if the passed in key selects exactly one node) or to a newly created node. The passed in NodeKeyResolver is used to interpret the given key.

Parameters:

key - the key

nodes - the collection of nodes to be added (may be null)

resolver - the NodeKeyResolver

Throws:

IllegalArgumentException - if the key references an attribute (of course, it is not possible to add something to an attribute)

setProperty

void setProperty(String key,
                 Object value,
                 NodeKeyResolver<T> resolver)

Changes the value of a property. This is a more complex operation as it might involve adding, updating, or deleting nodes and attributes from the model. The object representing the new value is passed to the NodeKeyResolver which will produce a corresponding NodeUpdateData object. Based on the content of this object, update operations are performed.

Parameters:

key - the key

value - the new value for this property (to be evaluated by the NodeKeyResolver)

resolver - the NodeKeyResolver

clearTree

Object clearTree(String key,
                 NodeKeyResolver<T> resolver)

Removes the sub trees defined by the given key from this model. All nodes selected by this key are retrieved from the specified NodeKeyResolver and removed from the model.

Parameters:

key - the key selecting the properties to be removed

resolver - the NodeKeyResolver

Returns:

an object with information about the data removed

clearProperty

void clearProperty(String key,
                   NodeKeyResolver<T> resolver)

Clears the value of a property. This method is similar to clearTree(String, NodeKeyResolver): However, the nodes referenced by the passed in key are not removed completely, but only their value is set to null.

Parameters:

key - the key selecting the properties to be cleared

resolver - the NodeKeyResolver

clear

void clear(NodeKeyResolver<T> resolver)

Removes all data from this model.

Parameters:

resolver - the NodeKeyResolver

getInMemoryRepresentation

ImmutableNode getInMemoryRepresentation()

Returns a representation of the data stored in this model in form of a nodes hierarchy of ImmutableNode objects. A concrete model implementation can use an arbitrary means to store its data. When a model's data is to be used together with other functionality of the Configuration library (e.g. when combining multiple configuration sources) it has to be transformed into a common format. This is done by this method. ImmutableNode is a generic representation of a hierarchical structure. Thus, it should be possible to generate a corresponding structure from arbitrary model data.

Returns:

the root node of an in-memory hierarchy representing the data stored in this model