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