View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.configuration2;
18  
19  import java.util.Collection;
20  import java.util.List;
21  
22  import org.apache.commons.configuration2.tree.ExpressionEngine;
23  import org.apache.commons.configuration2.tree.NodeModelSupport;
24  
25  /**
26   * <p>
27   * An interface for mutable hierarchical configurations.
28   * </p>
29   * <p>
30   * This interface introduces methods for manipulating tree-like structured configuration sources. Also, all methods
31   * defined by the {@code Configuration} interface are available.
32   * </p>
33   * <p>
34   * This interface does not make any assumptions about the concrete type of nodes used by an implementation; this is
35   * reflected by a generic type parameter. Concrete implementations may therefore define their own hierarchical
36   * structures.
37   * </p>
38   *
39   * @since 2.0
40   * @param <T> the type of the nodes used by this hierarchical configuration
41   */
42  public interface HierarchicalConfiguration<T> extends Configuration, ImmutableHierarchicalConfiguration, NodeModelSupport<T> {
43      /**
44       * Adds a collection of nodes at the specified position of the configuration tree. This method works similar to
45       * {@code addProperty()}, but instead of a single property a whole collection of nodes can be added - and thus complete
46       * configuration sub trees. E.g. with this method it is possible to add parts of another
47       * {@code BaseHierarchicalConfiguration} object to this object. If the passed in key refers to an existing and unique
48       * node, the new nodes are added to this node. Otherwise a new node will be created at the specified position in the
49       * hierarchy.
50       *
51       * @param key the key where the nodes are to be added; can be <b>null </b>, then they are added to the root node
52       * @param nodes a collection with the {@code Node} objects to be added
53       */
54      void addNodes(String key, Collection<? extends T> nodes);
55  
56      /**
57       * Returns a list with sub configurations for all child nodes of the node selected by the given key. This method works
58       * like {@link #immutableChildConfigurationsAt(String)}, but returns a list with mutable configuration objects. The
59       * configuration objects returned are <strong>not</strong> connected to the parent configuration.
60       *
61       * @param key the key for selecting the desired parent node
62       * @return a collection with {@code HierarchicalConfiguration} objects for all child nodes of the selected parent node
63       */
64      List<HierarchicalConfiguration<T>> childConfigurationsAt(String key);
65  
66      /**
67       * Returns a list with sub configurations for all child nodes of the node selected by the given key allowing the caller
68       * to specify the {@code supportUpdates} flag.
69       *
70       * @param key the key for selecting the desired parent node
71       * @param supportUpdates a flag whether the returned sub configuration should be directly connected to its parent
72       * @return a collection with {@code HierarchicalConfiguration} objects for all child nodes of the selected parent node
73       */
74      List<HierarchicalConfiguration<T>> childConfigurationsAt(String key, boolean supportUpdates);
75  
76      /**
77       * Removes all values of the property with the given name and of keys that start with this name. So if there is a
78       * property with the key &quot;foo&quot; and a property with the key &quot;foo.bar&quot;, a call of
79       * {@code clearTree("foo")} would remove both properties.
80       *
81       * @param key the key of the property to be removed
82       */
83      void clearTree(String key);
84  
85      /**
86       * Returns a hierarchical subnode configuration for the node specified by the given key. This is a short form for
87       * {@code configurationAt(key,
88       * <b>false</b>)}.
89       *
90       * @param key the key that selects the sub tree
91       * @return a hierarchical configuration that contains this sub tree
92       * @see SubnodeConfiguration
93       */
94      HierarchicalConfiguration<T> configurationAt(String key);
95  
96      /**
97       * <p>
98       * Returns a hierarchical sub configuration object that wraps the configuration node specified by the given key. This
99       * method provides an easy means of accessing sub trees of a hierarchical configuration. In the returned configuration
100      * the sub tree can directly be accessed, it becomes the root node of this configuration. Because of this the passed in
101      * key must select exactly one configuration node; otherwise an {@code IllegalArgumentException} will be thrown.
102      * </p>
103      * <p>
104      * The difference between this method and the {@link #subset(String)} method is that {@code subset()} supports arbitrary
105      * subsets of configuration nodes while {@code configurationAt()} only returns a single sub tree. Please refer to the
106      * documentation of the {@link SubnodeConfiguration} class to obtain further information about sub configurations and
107      * when they should be used.
108      * </p>
109      * <p>
110      * With the {@code supportUpdate} flag the behavior of the returned sub configuration regarding updates of its parent
111      * configuration can be determined. If set to <b>false</b>, the configurations return on independent nodes structures.
112      * So changes made on one configuration cannot be seen by the other one. A value of <b>true</b> in contrast creates a
113      * direct connection between both configurations - they are then using the same underlying data structures as much as
114      * possible. There are however changes which break this connection; for instance, if the sub tree the sub configuration
115      * belongs to is completely removed from the parent configuration. If such a change happens, the sub configuration
116      * becomes detached from its parent. It can still be used in a normal way, but changes on it are not reflected by the
117      * parent and vice verse. Also, it is not possible to reattach a once detached sub configuration.
118      * </p>
119      *
120      * @param key the key that selects the sub tree
121      * @param supportUpdates a flag whether the returned sub configuration should be directly connected to its parent
122      * @return a hierarchical configuration that contains this sub tree
123      * @see SubnodeConfiguration
124      */
125     HierarchicalConfiguration<T> configurationAt(String key, boolean supportUpdates);
126 
127     /**
128      * Returns a list of sub configurations for all configuration nodes selected by the given key. This method will evaluate
129      * the passed in key (using the current {@code ExpressionEngine}) and then create a sub configuration for each returned
130      * node (like {@link #configurationAt(String)} ). This is especially useful when dealing with list-like structures. As
131      * an example consider the configuration that contains data about database tables and their fields. If you need access
132      * to all fields of a certain table, you can simply do
133      *
134      * <pre>
135      * List fields = config.configurationsAt("tables.table(0).fields.field");
136      * for(Iterator it = fields.iterator(); it.hasNext();)
137      * {
138      *     BaseHierarchicalConfiguration sub = (BaseHierarchicalConfiguration) it.next();
139      *     // now the children and attributes of the field node can be
140      *     // directly accessed
141      *     String fieldName = sub.getString("name");
142      *     String fieldType = sub.getString("type");
143      *     ...
144      * </pre>
145      *
146      * The configuration objects returned are <strong>not</strong> connected to the parent configuration.
147      *
148      * @param key the key for selecting the desired nodes
149      * @return a list with hierarchical configuration objects; each configuration represents one of the nodes selected by
150      *         the passed in key
151      */
152     List<HierarchicalConfiguration<T>> configurationsAt(String key);
153 
154     /**
155      * Returns a list of sub configurations for all configuration nodes selected by the given key allowing the caller to
156      * specify the {@code supportUpdates} flag. This method works like {@link #configurationsAt(String)}, but with the
157      * additional boolean parameter it can be specified whether the returned configurations react on updates of the parent
158      * configuration.
159      *
160      * @param key the key for selecting the desired nodes
161      * @param supportUpdates a flag whether the returned sub configuration should be directly connected to its parent
162      * @return a list with hierarchical configuration objects; each configuration represents one of the nodes selected by
163      *         the passed in key
164      * @see #configurationsAt(String, boolean)
165      */
166     List<HierarchicalConfiguration<T>> configurationsAt(String key, boolean supportUpdates);
167 
168     /**
169      * Sets the expression engine to be used by this configuration. All property keys this configuration has to deal with
170      * will be interpreted by this engine.
171      *
172      * @param expressionEngine the new expression engine; can be <b>null</b>, then the default expression engine will be
173      *        used
174      */
175     void setExpressionEngine(ExpressionEngine expressionEngine);
176 }