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 * https://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 * @param <T> the type of the nodes used by this hierarchical configuration
40 * @since 2.0
41 */
42 public interface HierarchicalConfiguration<T> extends Configuration, ImmutableHierarchicalConfiguration, NodeModelSupport<T> {
43
44 /**
45 * Adds a collection of nodes at the specified position of the configuration tree. This method works similar to
46 * {@code addProperty()}, but instead of a single property a whole collection of nodes can be added - and thus complete
47 * configuration sub trees. E.g. with this method it is possible to add parts of another
48 * {@code BaseHierarchicalConfiguration} object to this object. If the passed in key refers to an existing and unique
49 * node, the new nodes are added to this node. Otherwise a new node will be created at the specified position in the
50 * hierarchy.
51 *
52 * @param key the key where the nodes are to be added; can be <strong>null </strong>, then they are added to the root node
53 * @param nodes a collection with the {@code Node} objects to be added
54 */
55 void addNodes(String key, Collection<? extends T> nodes);
56
57 /**
58 * Returns a list with sub configurations for all child nodes of the node selected by the given key. This method works
59 * like {@link #immutableChildConfigurationsAt(String)}, but returns a list with mutable configuration objects. The
60 * configuration objects returned are <strong>not</strong> connected to the parent configuration.
61 *
62 * @param key the key for selecting the desired parent node
63 * @return a collection with {@code HierarchicalConfiguration} objects for all child nodes of the selected parent node
64 */
65 List<HierarchicalConfiguration<T>> childConfigurationsAt(String key);
66
67 /**
68 * Returns a list with sub configurations for all child nodes of the node selected by the given key allowing the caller
69 * to specify the {@code supportUpdates} flag.
70 *
71 * @param key the key for selecting the desired parent node
72 * @param supportUpdates a flag whether the returned sub configuration should be directly connected to its parent
73 * @return a collection with {@code HierarchicalConfiguration} objects for all child nodes of the selected parent node
74 */
75 List<HierarchicalConfiguration<T>> childConfigurationsAt(String key, boolean supportUpdates);
76
77 /**
78 * Removes all values of the property with the given name and of keys that start with this name. So if there is a
79 * property with the key "foo" and a property with the key "foo.bar", a call of
80 * {@code clearTree("foo")} would remove both properties.
81 *
82 * @param key the key of the property to be removed
83 */
84 void clearTree(String key);
85
86 /**
87 * Returns a hierarchical subnode configuration for the node specified by the given key. This is a short form for
88 * {@code configurationAt(key,
89 * <strong>false</strong>)}.
90 *
91 * @param key the key that selects the sub tree
92 * @return a hierarchical configuration that contains this sub tree
93 * @see SubnodeConfiguration
94 */
95 HierarchicalConfiguration<T> configurationAt(String key);
96
97 /**
98 * <p>
99 * Returns a hierarchical sub configuration object that wraps the configuration node specified by the given key. This
100 * method provides an easy means of accessing sub trees of a hierarchical configuration. In the returned configuration
101 * the sub tree can directly be accessed, it becomes the root node of this configuration. Because of this the passed in
102 * key must select exactly one configuration node; otherwise an {@code IllegalArgumentException} will be thrown.
103 * </p>
104 * <p>
105 * The difference between this method and the {@link #subset(String)} method is that {@code subset()} supports arbitrary
106 * subsets of configuration nodes while {@code configurationAt()} only returns a single sub tree. Please refer to the
107 * documentation of the {@link SubnodeConfiguration} class to obtain further information about sub configurations and
108 * when they should be used.
109 * </p>
110 * <p>
111 * With the {@code supportUpdate} flag the behavior of the returned sub configuration regarding updates of its parent
112 * configuration can be determined. If set to <strong>false</strong>, the configurations return on independent nodes structures.
113 * So changes made on one configuration cannot be seen by the other one. A value of <strong>true</strong> in contrast creates a
114 * direct connection between both configurations - they are then using the same underlying data structures as much as
115 * possible. There are however changes which break this connection; for instance, if the sub tree the sub configuration
116 * belongs to is completely removed from the parent configuration. If such a change happens, the sub configuration
117 * becomes detached from its parent. It can still be used in a normal way, but changes on it are not reflected by the
118 * parent and vice verse. Also, it is not possible to reattach a once detached sub configuration.
119 * </p>
120 *
121 * @param key the key that selects the sub tree
122 * @param supportUpdates a flag whether the returned sub configuration should be directly connected to its parent
123 * @return a hierarchical configuration that contains this sub tree
124 * @see SubnodeConfiguration
125 */
126 HierarchicalConfiguration<T> configurationAt(String key, boolean supportUpdates);
127
128 /**
129 * Returns a list of sub configurations for all configuration nodes selected by the given key. This method will evaluate
130 * the passed in key (using the current {@code ExpressionEngine}) and then create a sub configuration for each returned
131 * node (like {@link #configurationAt(String)} ). This is especially useful when dealing with list-like structures. As
132 * an example consider the configuration that contains data about database tables and their fields. If you need access
133 * to all fields of a certain table, you can simply do
134 *
135 * <pre>
136 * List fields = config.configurationsAt("tables.table(0).fields.field");
137 * for(Iterator it = fields.iterator(); it.hasNext();)
138 * {
139 * BaseHierarchicalConfiguration sub = (BaseHierarchicalConfiguration) it.next();
140 * // now the children and attributes of the field node can be
141 * // directly accessed
142 * String fieldName = sub.getString("name");
143 * String fieldType = sub.getString("type");
144 * ...
145 * </pre>
146 *
147 * The configuration objects returned are <strong>not</strong> connected to the parent configuration.
148 *
149 * @param key the key for selecting the desired nodes
150 * @return a list with hierarchical configuration objects; each configuration represents one of the nodes selected by
151 * the passed in key
152 */
153 List<HierarchicalConfiguration<T>> configurationsAt(String key);
154
155 /**
156 * Returns a list of sub configurations for all configuration nodes selected by the given key allowing the caller to
157 * specify the {@code supportUpdates} flag. This method works like {@link #configurationsAt(String)}, but with the
158 * additional boolean parameter it can be specified whether the returned configurations react on updates of the parent
159 * configuration.
160 *
161 * @param key the key for selecting the desired nodes
162 * @param supportUpdates a flag whether the returned sub configuration should be directly connected to its parent
163 * @return a list with hierarchical configuration objects; each configuration represents one of the nodes selected by
164 * the passed in key
165 * @see #configurationsAt(String, boolean)
166 */
167 List<HierarchicalConfiguration<T>> configurationsAt(String key, boolean supportUpdates);
168
169 /**
170 * Sets the expression engine to be used by this configuration. All property keys this configuration has to deal with
171 * will be interpreted by this engine.
172 *
173 * @param expressionEngine the new expression engine; can be <strong>null</strong>, then the default expression engine will be
174 * used
175 */
176 void setExpressionEngine(ExpressionEngine expressionEngine);
177 }