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
027 * defines basic operations for manipulating the tree structure which use keys
028 * to select the nodes affected.
029 * </p>
030 * <p>
031 * The idea behind this interface is that concrete implementations can be used
032 * by hierarchical configurations. This makes it possible to integrate various
033 * hierarchical structures with the API of a hierarchical configuration, e.g.
034 * configuration nodes stored in memory, JNDI contexts, or other structures. The
035 * configuration object interacts with the underlying data structure via this
036 * interface. For more complex operations access to an {@link ExpressionEngine}
037 * may be required in order to interpret the passed in keys. For these purposes
038 * a {@link NodeKeyResolver} has to be provided which knows how to deal with
039 * keys.
040 * </p>
041 *
042 * @since 2.0
043 * @param <T> the type of the nodes managed by this model
044 */
045public interface NodeModel<T>
046{
047    /**
048     * Sets a new root node for this model. The whole structure is replaced by
049     * the new node and its children.
050     *
051     * @param newRoot the new root node to be set (can be <b>null</b>, then an
052     *        empty root node is set)
053     */
054    void setRootNode(T newRoot);
055
056    /**
057     * Returns a {@code NodeHandler} for dealing with the nodes managed by this
058     * model.
059     *
060     * @return the {@code NodeHandler}
061     */
062    NodeHandler<T> getNodeHandler();
063
064    /**
065     * Adds a new property to this node model consisting of an arbitrary number
066     * of values. The key for the add operation is provided. For each value a
067     * new node has to be added. The passed in resolver is queried for a
068     * {@link NodeAddData} object defining the add operation to be performed.
069     *
070     * @param key the key
071     * @param values the values to be added at the position defined by the key
072     * @param resolver the {@code NodeKeyResolver}
073     */
074    void addProperty(String key, Iterable<?> values, NodeKeyResolver<T> resolver);
075
076    /**
077     * Adds a collection of new nodes to this model. This operation corresponds
078     * to the {@code addNodes()} method of the {@code HierarchicalConfiguration}
079     * interface. The new nodes are either added to an existing node (if the
080     * passed in key selects exactly one node) or to a newly created node. The
081     * passed in {@code NodeKeyResolver} is used to interpret the given key.
082     *
083     * @param key the key
084     * @param nodes the collection of nodes to be added (may be <b>null</b>)
085     * @param resolver the {@code NodeKeyResolver}
086     * @throws IllegalArgumentException if the key references an attribute (of
087     *         course, it is not possible to add something to an attribute)
088     */
089    void addNodes(String key, Collection<? extends T> nodes,
090            NodeKeyResolver<T> resolver);
091
092    /**
093     * Changes the value of a property. This is a more complex operation as it
094     * might involve adding, updating, or deleting nodes and attributes from the
095     * model. The object representing the new value is passed to the
096     * {@code NodeKeyResolver} which will produce a corresponding
097     * {@link NodeUpdateData} object. Based on the content of this object,
098     * update operations are performed.
099     *
100     * @param key the key
101     * @param value the new value for this property (to be evaluated by the
102     *        {@code NodeKeyResolver})
103     * @param resolver the {@code NodeKeyResolver}
104     */
105    void setProperty(String key, Object value, NodeKeyResolver<T> resolver);
106
107    /**
108     * Removes the sub trees defined by the given key from this model. All nodes
109     * selected by this key are retrieved from the specified
110     * {@code NodeKeyResolver} and removed from the model.
111     *
112     * @param key the key selecting the properties to be removed
113     * @param resolver the {@code NodeKeyResolver}
114     * @return an object with information about the data removed
115     */
116    Object clearTree(String key, NodeKeyResolver<T> resolver);
117
118    /**
119     * Clears the value of a property. This method is similar to
120     * {@link #clearTree(String, NodeKeyResolver)}: However, the nodes
121     * referenced by the passed in key are not removed completely, but only
122     * their value is set to <b>null</b>.
123     *
124     * @param key the key selecting the properties to be cleared
125     * @param resolver the {@code NodeKeyResolver}
126     */
127    void clearProperty(String key, NodeKeyResolver<T> resolver);
128
129    /**
130     * Removes all data from this model.
131     *
132     * @param resolver the {@code NodeKeyResolver}
133     */
134    void clear(NodeKeyResolver<T> resolver);
135
136    /**
137     * Returns a representation of the data stored in this model in form of a
138     * nodes hierarchy of {@code ImmutableNode} objects. A concrete model
139     * implementation can use an arbitrary means to store its data. When a
140     * model's data is to be used together with other functionality of the
141     * <em>Configuration</em> library (e.g. when combining multiple
142     * configuration sources) it has to be transformed into a common format.
143     * This is done by this method. {@code ImmutableNode} is a generic
144     * representation of a hierarchical structure. Thus, it should be possible
145     * to generate a corresponding structure from arbitrary model data.
146     *
147     * @return the root node of an in-memory hierarchy representing the data
148     *         stored in this model
149     */
150    ImmutableNode getInMemoryRepresentation();
151}