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 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​(java.lang.String key,
                         java.lang.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​(java.lang.String key,
                      java.util.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:
        java.lang.IllegalArgumentException - if the key references an attribute (of course, it is not possible to add something to an attribute)
      • setProperty

        void setProperty​(java.lang.String key,
                         java.lang.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

        java.lang.Object clearTree​(java.lang.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​(java.lang.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