Package 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 Details

    • 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)

    • 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

    • clear

      void clear(NodeKeyResolver<T> resolver)
      Removes all data from this model.
      Parameters:
      resolver - the NodeKeyResolver

    • 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

    • 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

    • getInMemoryRepresentation

      ImmutableNode getInMemoryRepresentation()
      Gets 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

    • getNodeHandler

      NodeHandler<T> getNodeHandler()
      Gets a NodeHandler for dealing with the nodes managed by this model.
      Returns:
      the NodeHandler

    • 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

    • 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)