| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.apache.commons.configuration2; |
| |
| import java.util.List; |
| |
| import org.apache.commons.configuration2.tree.ExpressionEngine; |
| |
| /** |
| * <p> |
| * An interface for immutable hierarchical configurations. |
| * </p> |
| * <p> |
| * There are some sources of configuration data that cannot be stored very well |
| * in a flat configuration object (like {@link BaseConfiguration}) because then |
| * their structure is lost. A prominent example are XML documents. |
| * </p> |
| * <p> |
| * This interface extends the basic {@link ImmutableConfiguration} interface by |
| * structured access to configuration properties. An {@link ExpressionEngine} is |
| * used to evaluate complex property keys and to map them to nodes of a |
| * tree-like structure. |
| * </p> |
| * |
| * @version $Id$ |
| * @since 2.0 |
| */ |
| public interface ImmutableHierarchicalConfiguration extends ImmutableConfiguration |
| { |
| /** |
| * Returns the expression engine used by this configuration. This method |
| * will never return <b>null</b>; if no specific expression engine was set, |
| * the default expression engine will be returned. |
| * |
| * @return the current expression engine |
| */ |
| ExpressionEngine getExpressionEngine(); |
| |
| /** |
| * Returns the maximum defined index for the given key. This is useful if |
| * there are multiple values for this key. They can then be addressed |
| * separately by specifying indices from 0 to the return value of this |
| * method. |
| * |
| * @param key the key to be checked |
| * @return the maximum defined index for this key |
| */ |
| int getMaxIndex(String key); |
| |
| /** |
| * Returns the name of the root element of this configuration. This |
| * information may be of use in some cases, e.g. for sub configurations |
| * created using the {@code immutableConfigurationsAt()} method. The exact |
| * meaning of the string returned by this method is specific to a concrete |
| * implementation. For instance, an XML configuration might return the name |
| * of the document element. |
| * |
| * @return the name of the root element of this configuration |
| */ |
| String getRootElementName(); |
| |
| /** |
| * <p> |
| * Returns an immutable hierarchical configuration object that wraps the |
| * configuration node specified by the given key. This method provides an |
| * easy means of accessing sub trees of a hierarchical configuration. In the |
| * returned configuration the sub tree can directly be accessed, it becomes |
| * the root node of this configuration. Because of this the passed in key |
| * must select exactly one configuration node; otherwise an |
| * {@code IllegalArgumentException} will be thrown. |
| * </p> |
| * <p> |
| * The difference between this method and the |
| * {@link #immutableSubset(String)} method is that |
| * {@code immutableSubset()} supports arbitrary subsets of configuration nodes |
| * while {@code immutableConfigurationAt()} only returns a single sub tree. |
| * Please refer to the documentation of the |
| * {@code SubnodeConfiguration} class to obtain further information |
| * about subnode configurations and when they should be used. |
| * </p> |
| * |
| * @param key the key that selects the sub tree |
| * @param supportUpdates a flag whether the returned subnode configuration |
| * should be able to handle updates of its parent |
| * @return a hierarchical configuration that contains this sub tree |
| */ |
| ImmutableHierarchicalConfiguration immutableConfigurationAt(String key, |
| boolean supportUpdates); |
| |
| /** |
| * Returns an immutable hierarchical configuration for the node specified by |
| * the given key. This is a short form for {@code immutableConfigurationAt(key, |
| * <b>false</b>)}. |
| * |
| * @param key the key that selects the sub tree |
| * @return a hierarchical configuration that contains this sub tree |
| */ |
| ImmutableHierarchicalConfiguration immutableConfigurationAt(String key); |
| |
| /** |
| * Returns a list of immutable configurations for all configuration nodes selected |
| * by the given key. This method will evaluate the passed in key (using the |
| * current {@code ExpressionEngine}) and then create an immutable subnode |
| * configuration for each returned node (like |
| * {@link #immutableConfigurationAt(String)}}). This is especially |
| * useful when dealing with list-like structures. As an example consider the |
| * configuration that contains data about database tables and their fields. |
| * If you need access to all fields of a certain table, you can simply do |
| * |
| * <pre> |
| * List<ImmutableHierarchicalConfiguration> fields = |
| * config.immutableConfigurationsAt("tables.table(0).fields.field"); |
| * for(Iterator<ImmutableHierarchicalConfiguration> it = fields.iterator(); |
| * it.hasNext();) |
| * { |
| * ImmutableHierarchicalConfiguration sub = it.next(); |
| * // now the children and attributes of the field node can be |
| * // directly accessed |
| * String fieldName = sub.getString("name"); |
| * String fieldType = sub.getString("type"); |
| * ... |
| * </pre> |
| * |
| * @param key the key for selecting the desired nodes |
| * @return a list with immutable hierarchical configuration objects; each |
| * configuration represents one of the nodes selected by the passed in key |
| */ |
| List<ImmutableHierarchicalConfiguration> immutableConfigurationsAt(String key); |
| |
| /** |
| * Returns a list of immutable configurations for all direct child elements |
| * of the node selected by the given key. With this method it is possible to |
| * inspect the content of a hierarchical structure; all children of a given |
| * node can be queried without having to know their exact names. If the |
| * passed in key does not point to a single node, an empty list is returned. |
| * This is also the result if the node referred to by the key does not have |
| * child elements. |
| * |
| * @param key the key for selecting the desired parent node |
| * @return a collection with immutable configurations for all child nodes of |
| * the selected parent node |
| */ |
| List<ImmutableHierarchicalConfiguration> immutableChildConfigurationsAt( |
| String key); |
| } |