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.List; 020 021import org.apache.commons.configuration2.tree.ExpressionEngine; 022 023/** 024 * <p> 025 * An interface for immutable hierarchical configurations. 026 * </p> 027 * <p> 028 * There are some sources of configuration data that cannot be stored very well 029 * in a flat configuration object (like {@link BaseConfiguration}) because then 030 * their structure is lost. A prominent example are XML documents. 031 * </p> 032 * <p> 033 * This interface extends the basic {@link ImmutableConfiguration} interface by 034 * structured access to configuration properties. An {@link ExpressionEngine} is 035 * used to evaluate complex property keys and to map them to nodes of a 036 * tree-like structure. 037 * </p> 038 * 039 * @version $Id: ImmutableHierarchicalConfiguration.java 1679758 2015-05-16 17:35:56Z oheger $ 040 * @since 2.0 041 */ 042public interface ImmutableHierarchicalConfiguration extends ImmutableConfiguration 043{ 044 /** 045 * Returns the expression engine used by this configuration. This method 046 * will never return <b>null</b>; if no specific expression engine was set, 047 * the default expression engine will be returned. 048 * 049 * @return the current expression engine 050 */ 051 ExpressionEngine getExpressionEngine(); 052 053 /** 054 * Returns the maximum defined index for the given key. This is useful if 055 * there are multiple values for this key. They can then be addressed 056 * separately by specifying indices from 0 to the return value of this 057 * method. 058 * 059 * @param key the key to be checked 060 * @return the maximum defined index for this key 061 */ 062 int getMaxIndex(String key); 063 064 /** 065 * Returns the name of the root element of this configuration. This 066 * information may be of use in some cases, e.g. for sub configurations 067 * created using the {@code immutableConfigurationsAt()} method. The exact 068 * meaning of the string returned by this method is specific to a concrete 069 * implementation. For instance, an XML configuration might return the name 070 * of the document element. 071 * 072 * @return the name of the root element of this configuration 073 */ 074 String getRootElementName(); 075 076 /** 077 * <p> 078 * Returns an immutable hierarchical 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 #immutableSubset(String)} method is that 089 * {@code immutableSubset()} supports arbitrary subsets of configuration nodes 090 * while {@code immutableConfigurationAt()} only returns a single sub tree. 091 * Please refer to the documentation of the 092 * {@code SubnodeConfiguration} class to obtain further information 093 * about subnode configurations and when they should be used. 094 * </p> 095 * 096 * @param key the key that selects the sub tree 097 * @param supportUpdates a flag whether the returned subnode configuration 098 * should be able to handle updates of its parent 099 * @return a hierarchical configuration that contains this sub tree 100 */ 101 ImmutableHierarchicalConfiguration immutableConfigurationAt(String key, 102 boolean supportUpdates); 103 104 /** 105 * Returns an immutable hierarchical configuration for the node specified by 106 * the given key. This is a short form for {@code immutableConfigurationAt(key, 107 * <b>false</b>)}. 108 * 109 * @param key the key that selects the sub tree 110 * @return a hierarchical configuration that contains this sub tree 111 */ 112 ImmutableHierarchicalConfiguration immutableConfigurationAt(String key); 113 114 /** 115 * Returns a list of immutable configurations for all configuration nodes selected 116 * by the given key. This method will evaluate the passed in key (using the 117 * current {@code ExpressionEngine}) and then create an immutable subnode 118 * configuration for each returned node (like 119 * {@link #immutableConfigurationAt(String)}}). This is especially 120 * useful when dealing with list-like structures. As an example consider the 121 * configuration that contains data about database tables and their fields. 122 * If you need access to all fields of a certain table, you can simply do 123 * 124 * <pre> 125 * List<ImmutableHierarchicalConfiguration> fields = 126 * config.immutableConfigurationsAt("tables.table(0).fields.field"); 127 * for(Iterator<ImmutableHierarchicalConfiguration> it = fields.iterator(); 128 * it.hasNext();) 129 * { 130 * ImmutableHierarchicalConfiguration sub = it.next(); 131 * // now the children and attributes of the field node can be 132 * // directly accessed 133 * String fieldName = sub.getString("name"); 134 * String fieldType = sub.getString("type"); 135 * ... 136 * </pre> 137 * 138 * @param key the key for selecting the desired nodes 139 * @return a list with immutable hierarchical configuration objects; each 140 * configuration represents one of the nodes selected by the passed in key 141 */ 142 List<ImmutableHierarchicalConfiguration> immutableConfigurationsAt(String key); 143 144 /** 145 * Returns a list of immutable configurations for all direct child elements 146 * of the node selected by the given key. With this method it is possible to 147 * inspect the content of a hierarchical structure; all children of a given 148 * node can be queried without having to know their exact names. If the 149 * passed in key does not point to a single node, an empty list is returned. 150 * This is also the result if the node referred to by the key does not have 151 * child elements. 152 * 153 * @param key the key for selecting the desired parent node 154 * @return a collection with immutable configurations for all child nodes of 155 * the selected parent node 156 */ 157 List<ImmutableHierarchicalConfiguration> immutableChildConfigurationsAt( 158 String key); 159}