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