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}