org.apache.commons.configuration2.tree.NodeModel Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of commons-configuration2 Show documentation
Tools to assist in the reading of configuration/preferences files in various formats
There is a newer version: 2.10.1
Show newest version
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.configuration2.tree;

import java.util.Collection;

/**
 * 
 * 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 {@link ExpressionEngine}
 * may be required in order to interpret the passed in keys. For these purposes
 * a {@link NodeKeyResolver} has to be provided which knows how to deal with
 * keys.
 * 
 *
 * @since 2.0
 * @param  the type of the nodes managed by this model
 */
public interface NodeModel
{
    /**
     * Sets a new root node for this model. The whole structure is replaced by
     * the new node and its children.
     *
     * @param newRoot the new root node to be set (can be null, then an
     *        empty root node is set)
     */
    void setRootNode(T newRoot);

    /**
     * Returns a {@code NodeHandler} for dealing with the nodes managed by this
     * model.
     *
     * @return the {@code NodeHandler}
     */
    NodeHandler getNodeHandler();

    /**
     * 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
     * {@link NodeAddData} object defining the add operation to be performed.
     *
     * @param key the key
     * @param values the values to be added at the position defined by the key
     * @param resolver the {@code NodeKeyResolver}
     */
    void addProperty(String key, Iterable values, NodeKeyResolver resolver);

    /**
     * Adds a collection of new nodes to this model. This operation corresponds
     * to the {@code addNodes()} method of the {@code 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 {@code NodeKeyResolver} is used to interpret the given key.
     *
     * @param key the key
     * @param nodes the collection of nodes to be added (may be null)
     * @param resolver the {@code NodeKeyResolver}
     * @throws IllegalArgumentException if the key references an attribute (of
     *         course, it is not possible to add something to an attribute)
     */
    void addNodes(String key, Collection nodes,
            NodeKeyResolver 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
     * {@code NodeKeyResolver} which will produce a corresponding
     * {@link NodeUpdateData} object. Based on the content of this object,
     * update operations are performed.
     *
     * @param key the key
     * @param value the new value for this property (to be evaluated by the
     *        {@code NodeKeyResolver})
     * @param resolver the {@code NodeKeyResolver}
     */
    void setProperty(String key, Object value, NodeKeyResolver resolver);

    /**
     * Removes the sub trees defined by the given key from this model. All nodes
     * selected by this key are retrieved from the specified
     * {@code NodeKeyResolver} and removed from the model.
     *
     * @param key the key selecting the properties to be removed
     * @param resolver the {@code NodeKeyResolver}
     * @return an object with information about the data removed
     */
    Object clearTree(String key, NodeKeyResolver resolver);

    /**
     * Clears the value of a property. This method is similar to
     * {@link #clearTree(String, NodeKeyResolver)}: However, the nodes
     * referenced by the passed in key are not removed completely, but only
     * their value is set to null.
     *
     * @param key the key selecting the properties to be cleared
     * @param resolver the {@code NodeKeyResolver}
     */
    void clearProperty(String key, NodeKeyResolver resolver);

    /**
     * Removes all data from this model.
     *
     * @param resolver the {@code NodeKeyResolver}
     */
    void clear(NodeKeyResolver resolver);

    /**
     * Returns a representation of the data stored in this model in form of a
     * nodes hierarchy of {@code 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. {@code ImmutableNode} is a generic
     * representation of a hierarchical structure. Thus, it should be possible
     * to generate a corresponding structure from arbitrary model data.
     *
     * @return the root node of an in-memory hierarchy representing the data
     *         stored in this model
     */
    ImmutableNode getInMemoryRepresentation();
}