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 * "foo" and a property with the key "foo.bar", 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}