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 Summary

  Modifier and Type
  Method
  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()`
  Gets a representation of the data stored in this model in form of a nodes hierarchy of `ImmutableNode` objects.
  `NodeHandler<T>`
  `getNodeHandler()`
  Gets 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 Details

  - ### 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()
    Gets 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()
    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