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.List; 20 21 import org.apache.commons.configuration2.tree.ExpressionEngine; 22 23 /** 24 * <p> 25 * An interface for immutable hierarchical configurations. 26 * </p> 27 * <p> 28 * There are some sources of configuration data that cannot be stored very well in a flat configuration object (like 29 * {@link BaseConfiguration}) because then their structure is lost. A prominent example are XML documents. 30 * </p> 31 * <p> 32 * This interface extends the basic {@link ImmutableConfiguration} interface by structured access to configuration 33 * properties. An {@link ExpressionEngine} is used to evaluate complex property keys and to map them to nodes of a 34 * tree-like structure. 35 * </p> 36 * 37 * @since 2.0 38 */ 39 public interface ImmutableHierarchicalConfiguration extends ImmutableConfiguration { 40 /** 41 * Gets the expression engine used by this configuration. This method will never return <b>null</b>; if no specific 42 * expression engine was set, the default expression engine will be returned. 43 * 44 * @return the current expression engine 45 */ 46 ExpressionEngine getExpressionEngine(); 47 48 /** 49 * Gets the maximum defined index for the given key. This is useful if there are multiple values for this key. They 50 * can then be addressed separately by specifying indices from 0 to the return value of this method. 51 * 52 * @param key the key to be checked 53 * @return the maximum defined index for this key 54 */ 55 int getMaxIndex(String key); 56 57 /** 58 * Gets the name of the root element of this configuration. This information may be of use in some cases, e.g. for 59 * sub configurations created using the {@code immutableConfigurationsAt()} method. The exact meaning of the string 60 * returned by this method is specific to a concrete implementation. For instance, an XML configuration might return the 61 * name of the document element. 62 * 63 * @return the name of the root element of this configuration 64 */ 65 String getRootElementName(); 66 67 /** 68 * Returns a list of immutable configurations for all direct child elements of the node selected by the given key. With 69 * this method it is possible to inspect the content of a hierarchical structure; all children of a given node can be 70 * queried without having to know their exact names. If the passed in key does not point to a single node, an empty list 71 * is returned. This is also the result if the node referred to by the key does not have child elements. 72 * 73 * @param key the key for selecting the desired parent node 74 * @return a collection with immutable configurations for all child nodes of the selected parent node 75 */ 76 List<ImmutableHierarchicalConfiguration> immutableChildConfigurationsAt(String key); 77 78 /** 79 * Returns an immutable hierarchical configuration for the node specified by the given key. This is a short form for 80 * {@code immutableConfigurationAt(key, 81 * <b>false</b>)}. 82 * 83 * @param key the key that selects the sub tree 84 * @return a hierarchical configuration that contains this sub tree 85 */ 86 ImmutableHierarchicalConfiguration immutableConfigurationAt(String key); 87 88 /** 89 * <p> 90 * Returns an immutable hierarchical configuration object that wraps the configuration node specified by the given key. 91 * This method provides an easy means of accessing sub trees of a hierarchical configuration. In the returned 92 * configuration the sub tree can directly be accessed, it becomes the root node of this configuration. Because of this 93 * the passed in key must select exactly one configuration node; otherwise an {@code IllegalArgumentException} will be 94 * thrown. 95 * </p> 96 * <p> 97 * The difference between this method and the {@link #immutableSubset(String)} method is that {@code immutableSubset()} 98 * supports arbitrary subsets of configuration nodes while {@code immutableConfigurationAt()} only returns a single sub 99 * tree. Please refer to the documentation of the {@code SubnodeConfiguration} class to obtain further information about 100 * subnode configurations and when they should be used. 101 * </p> 102 * 103 * @param key the key that selects the sub tree 104 * @param supportUpdates a flag whether the returned subnode configuration should be able to handle updates of its 105 * parent 106 * @return a hierarchical configuration that contains this sub tree 107 */ 108 ImmutableHierarchicalConfiguration immutableConfigurationAt(String key, boolean supportUpdates); 109 110 /** 111 * Returns a list of immutable configurations for all configuration nodes selected by the given key. This method will 112 * evaluate the passed in key (using the current {@code ExpressionEngine}) and then create an immutable subnode 113 * configuration for each returned node (like {@link #immutableConfigurationAt(String)}}). This is especially useful 114 * when dealing with list-like structures. As an example consider the configuration that contains data about database 115 * tables and their fields. If you need access to all fields of a certain table, you can simply do 116 * 117 * <pre> 118 * List<ImmutableHierarchicalConfiguration> fields = 119 * config.immutableConfigurationsAt("tables.table(0).fields.field"); 120 * for(Iterator<ImmutableHierarchicalConfiguration> it = fields.iterator(); 121 * it.hasNext();) 122 * { 123 * ImmutableHierarchicalConfiguration sub = it.next(); 124 * // now the children and attributes of the field node can be 125 * // directly accessed 126 * String fieldName = sub.getString("name"); 127 * String fieldType = sub.getString("type"); 128 * ... 129 * </pre> 130 * 131 * @param key the key for selecting the desired nodes 132 * @return a list with immutable hierarchical configuration objects; each configuration represents one of the nodes 133 * selected by the passed in key 134 */ 135 List<ImmutableHierarchicalConfiguration> immutableConfigurationsAt(String key); 136 }