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;
018
019import java.util.Collection;
020import java.util.List;
021
022import org.apache.commons.configuration2.tree.ExpressionEngine;
023import org.apache.commons.configuration2.tree.NodeModelSupport;
024
025/**
026 * <p>
027 * An interface for mutable hierarchical configurations.
028 * </p>
029 * <p>
030 * This interface introduces methods for manipulating tree-like structured
031 * configuration sources. Also, all methods defined by the {@code Configuration}
032 * interface are available.
033 * </p>
034 * <p>
035 * This interface does not make any assumptions about the concrete type of nodes
036 * used by an implementation; this is reflected by a generic type parameter.
037 * Concrete implementations may therefore define their own hierarchical
038 * structures.
039 * </p>
040 *
041 * @since 2.0
042 * @param <T> the type of the nodes used by this hierarchical configuration
043 */
044public interface HierarchicalConfiguration<T>
045    extends Configuration, ImmutableHierarchicalConfiguration, NodeModelSupport<T>
046{
047    /**
048     * Sets the expression engine to be used by this configuration. All property
049     * keys this configuration has to deal with will be interpreted by this
050     * engine.
051     *
052     * @param expressionEngine the new expression engine; can be <b>null</b>,
053     * then the default expression engine will be used
054     */
055    void setExpressionEngine(ExpressionEngine expressionEngine);
056
057    /**
058     * Adds a collection of nodes at the specified position of the configuration
059     * tree. This method works similar to {@code addProperty()}, but
060     * instead of a single property a whole collection of nodes can be added -
061     * and thus complete configuration sub trees. E.g. with this method it is
062     * possible to add parts of another {@code BaseHierarchicalConfiguration}
063     * object to this object. If the passed in key refers to
064     * an existing and unique node, the new nodes are added to this node.
065     * Otherwise a new node will be created at the specified position in the
066     * hierarchy.
067     *
068     * @param key the key where the nodes are to be added; can be <b>null </b>,
069     * then they are added to the root node
070     * @param nodes a collection with the {@code Node} objects to be
071     * added
072     */
073    void addNodes(String key, Collection<? extends T> nodes);
074
075    /**
076     * <p>
077     * Returns a hierarchical sub configuration object that wraps the
078     * configuration node specified by the given key. This method provides an
079     * easy means of accessing sub trees of a hierarchical configuration. In the
080     * returned configuration the sub tree can directly be accessed, it becomes
081     * the root node of this configuration. Because of this the passed in key
082     * must select exactly one configuration node; otherwise an
083     * {@code IllegalArgumentException} will be thrown.
084     * </p>
085     * <p>
086     * The difference between this method and the
087     * {@link #subset(String)} method is that
088     * {@code subset()} supports arbitrary subsets of configuration nodes
089     * while {@code configurationAt()} only returns a single sub tree.
090     * Please refer to the documentation of the
091     * {@link SubnodeConfiguration} class to obtain further information
092     * about sub configurations and when they should be used.
093     * </p>
094     * <p>
095     * With the {@code supportUpdate} flag the behavior of the returned
096     * sub configuration regarding updates of its parent
097     * configuration can be determined. If set to <b>false</b>, the configurations
098     * return on independent nodes structures. So changes made on one configuration
099     * cannot be seen by the other one. A value of <b>true</b> in contrast creates
100     * a direct connection between both configurations - they are then using the
101     * same underlying data structures as much as possible. There are however changes
102     * which break this connection; for instance, if the sub tree the sub configuration
103     * belongs to is completely removed from the parent configuration. If such a
104     * change happens, the sub configuration becomes detached from its parent.
105     * It can still be used in a normal way, but changes on it are not reflected
106     * by the parent and vice verse. Also, it is not possible to reattach a once
107     * detached sub configuration.
108     * </p>
109     *
110     * @param key the key that selects the sub tree
111     * @param supportUpdates a flag whether the returned sub configuration
112     * should be directly connected to its parent
113     * @return a hierarchical configuration that contains this sub tree
114     * @see SubnodeConfiguration
115     */
116    HierarchicalConfiguration<T> configurationAt(String key, boolean supportUpdates);
117
118    /**
119     * Returns a hierarchical subnode configuration for the node specified by
120     * the given key. This is a short form for {@code configurationAt(key,
121     * <b>false</b>)}.
122     *
123     * @param key the key that selects the sub tree
124     * @return a hierarchical configuration that contains this sub tree
125     * @see SubnodeConfiguration
126     */
127    HierarchicalConfiguration<T> configurationAt(String key);
128
129    /**
130     * Returns a list of sub configurations for all configuration nodes selected
131     * by the given key. This method will evaluate the passed in key (using the
132     * current {@code ExpressionEngine}) and then create a sub configuration for
133     * each returned node (like {@link #configurationAt(String)} ). This is
134     * especially useful when dealing with list-like structures. As an example
135     * consider the configuration that contains data about database tables and
136     * their fields. If you need access to all fields of a certain table, you
137     * can simply do
138     *
139     * <pre>
140     * List fields = config.configurationsAt("tables.table(0).fields.field");
141     * for(Iterator it = fields.iterator(); it.hasNext();)
142     * {
143     *     BaseHierarchicalConfiguration sub = (BaseHierarchicalConfiguration) it.next();
144     *     // now the children and attributes of the field node can be
145     *     // directly accessed
146     *     String fieldName = sub.getString("name");
147     *     String fieldType = sub.getString("type");
148     *     ...
149     * </pre>
150     *
151     * The configuration objects returned are <strong>not</strong> connected to
152     * the parent configuration.
153     *
154     * @param key the key for selecting the desired nodes
155     * @return a list with hierarchical configuration objects; each
156     *         configuration represents one of the nodes selected by the passed
157     *         in key
158     */
159    List<HierarchicalConfiguration<T>> configurationsAt(String key);
160
161    /**
162     * Returns a list of sub configurations for all configuration nodes selected
163     * by the given key allowing the caller to specify the
164     * {@code supportUpdates} flag. This method works like
165     * {@link #configurationsAt(String)}, but with the additional boolean
166     * parameter it can be specified whether the returned configurations react
167     * on updates of the parent configuration.
168     *
169     * @param key the key for selecting the desired nodes
170     * @param supportUpdates a flag whether the returned sub configuration
171     *        should be directly connected to its parent
172     * @return a list with hierarchical configuration objects; each
173     *         configuration represents one of the nodes selected by the passed
174     *         in key
175     * @see #configurationsAt(String, boolean)
176     */
177    List<HierarchicalConfiguration<T>> configurationsAt(String key,
178            boolean supportUpdates);
179
180    /**
181     * Returns a list with sub configurations for all child nodes of the node
182     * selected by the given key. This method works like
183     * {@link #immutableChildConfigurationsAt(String)}, but returns a list with
184     * mutable configuration objects. The configuration objects returned are
185     * <strong>not</strong> connected to the parent configuration.
186     *
187     * @param key the key for selecting the desired parent node
188     * @return a collection with {@code HierarchicalConfiguration} objects for all
189     *         child nodes of the selected parent node
190     */
191    List<HierarchicalConfiguration<T>> childConfigurationsAt(String key);
192
193    /**
194     * Returns a list with sub configurations for all child nodes of the node
195     * selected by the given key allowing the caller to specify the
196     * {@code supportUpdates} flag.
197     *
198     * @param key the key for selecting the desired parent node
199     * @param supportUpdates a flag whether the returned sub configuration
200     *        should be directly connected to its parent
201     * @return a collection with {@code HierarchicalConfiguration} objects for
202     *         all child nodes of the selected parent node
203     */
204    List<HierarchicalConfiguration<T>> childConfigurationsAt(String key,
205            boolean supportUpdates);
206
207    /**
208     * Removes all values of the property with the given name and of keys that
209     * start with this name. So if there is a property with the key
210     * &quot;foo&quot; and a property with the key &quot;foo.bar&quot;, a call
211     * of {@code clearTree("foo")} would remove both properties.
212     *
213     * @param key the key of the property to be removed
214     */
215    void clearTree(String key);
216}