    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *     http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.configuration2.tree;
    018
    019import java.util.Collection;
    020
    021/**
    022 * <p>
    023 * Definition of an interface describing a model based on a nodes structure.
    024 * </p>
    025 * <p>
    026 * This interface can be used for dealing with hierarchical, tree-like data. It defines basic operations for
    027 * manipulating the tree structure which use keys to select the nodes affected.
    028 * </p>
    029 * <p>
    030 * The idea behind this interface is that concrete implementations can be used by hierarchical configurations. This
    031 * makes it possible to integrate various hierarchical structures with the API of a hierarchical configuration, e.g.
    032 * configuration nodes stored in memory, JNDI contexts, or other structures. The configuration object interacts with the
    033 * underlying data structure via this interface. For more complex operations access to an {@link ExpressionEngine} may
    034 * be required in order to interpret the passed in keys. For these purposes a {@link NodeKeyResolver} has to be provided
    035 * which knows how to deal with keys.
    036 * </p>
    037 *
    038 * @since 2.0
    039 * @param <T> the type of the nodes managed by this model
    040 */
    041public interface NodeModel<T> {
    042    /**
    043     * Adds a collection of new nodes to this model. This operation corresponds to the {@code addNodes()} method of the
    044     * {@code HierarchicalConfiguration} interface. The new nodes are either added to an existing node (if the passed in key
    045     * selects exactly one node) or to a newly created node. The passed in {@code NodeKeyResolver} is used to interpret the
    046     * given key.
    047     *
    048     * @param key the key
    049     * @param nodes the collection of nodes to be added (may be <b>null</b>)
    050     * @param resolver the {@code NodeKeyResolver}
    051     * @throws IllegalArgumentException if the key references an attribute (of course, it is not possible to add something
    052     *         to an attribute)
    053     */
    054    void addNodes(String key, Collection<? extends T> nodes, NodeKeyResolver<T> resolver);
    055
    056    /**
    057     * Adds a new property to this node model consisting of an arbitrary number of values. The key for the add operation is
    058     * provided. For each value a new node has to be added. The passed in resolver is queried for a {@link NodeAddData}
    059     * object defining the add operation to be performed.
    060     *
    061     * @param key the key
    062     * @param values the values to be added at the position defined by the key
    063     * @param resolver the {@code NodeKeyResolver}
    064     */
    065    void addProperty(String key, Iterable<?> values, NodeKeyResolver<T> resolver);
    066
    067    /**
    068     * Removes all data from this model.
    069     *
    070     * @param resolver the {@code NodeKeyResolver}
    071     */
    072    void clear(NodeKeyResolver<T> resolver);
    073
    074    /**
    075     * Clears the value of a property. This method is similar to {@link #clearTree(String, NodeKeyResolver)}: However, the
    076     * nodes referenced by the passed in key are not removed completely, but only their value is set to <b>null</b>.
    077     *
    078     * @param key the key selecting the properties to be cleared
    079     * @param resolver the {@code NodeKeyResolver}
    080     */
    081    void clearProperty(String key, NodeKeyResolver<T> resolver);
    082
    083    /**
    084     * Removes the sub trees defined by the given key from this model. All nodes selected by this key are retrieved from the
    085     * specified {@code NodeKeyResolver} and removed from the model.
    086     *
    087     * @param key the key selecting the properties to be removed
    088     * @param resolver the {@code NodeKeyResolver}
    089     * @return an object with information about the data removed
    090     */
    091    Object clearTree(String key, NodeKeyResolver<T> resolver);
    092
    093    /**
    094     * Gets a representation of the data stored in this model in form of a nodes hierarchy of {@code ImmutableNode}
    095     * objects. A concrete model implementation can use an arbitrary means to store its data. When a model's data is to be
    096     * used together with other functionality of the <em>Configuration</em> library (e.g. when combining multiple
    097     * configuration sources) it has to be transformed into a common format. This is done by this method.
    098     * {@code ImmutableNode} is a generic representation of a hierarchical structure. Thus, it should be possible to
    099     * generate a corresponding structure from arbitrary model data.
    100     *
    101     * @return the root node of an in-memory hierarchy representing the data stored in this model
    102     */
    103    ImmutableNode getInMemoryRepresentation();
    104
    105    /**
    106     * Gets a {@code NodeHandler} for dealing with the nodes managed by this model.
    107     *
    108     * @return the {@code NodeHandler}
    109     */
    110    NodeHandler<T> getNodeHandler();
    111
    112    /**
    113     * Changes the value of a property. This is a more complex operation as it might involve adding, updating, or deleting
    114     * nodes and attributes from the model. The object representing the new value is passed to the {@code NodeKeyResolver}
    115     * which will produce a corresponding {@link NodeUpdateData} object. Based on the content of this object, update
    116     * operations are performed.
    117     *
    118     * @param key the key
    119     * @param value the new value for this property (to be evaluated by the {@code NodeKeyResolver})
    120     * @param resolver the {@code NodeKeyResolver}
    121     */
    122    void setProperty(String key, Object value, NodeKeyResolver<T> resolver);
    123
    124    /**
    125     * Sets a new root node for this model. The whole structure is replaced by the new node and its children.
    126     *
    127     * @param newRoot the new root node to be set (can be <b>null</b>, then an empty root node is set)
    128     */
    129    void setRootNode(T newRoot);
    130}