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 * @since 2.0
040 */
041public interface ImmutableHierarchicalConfiguration extends ImmutableConfiguration
042{
043    /**
044     * Returns the expression engine used by this configuration. This method
045     * will never return <b>null</b>; if no specific expression engine was set,
046     * the default expression engine will be returned.
047     *
048     * @return the current expression engine
049     */
050    ExpressionEngine getExpressionEngine();
051
052    /**
053     * Returns the maximum defined index for the given key. This is useful if
054     * there are multiple values for this key. They can then be addressed
055     * separately by specifying indices from 0 to the return value of this
056     * method.
057     *
058     * @param key the key to be checked
059     * @return the maximum defined index for this key
060     */
061    int getMaxIndex(String key);
062
063    /**
064     * Returns the name of the root element of this configuration. This
065     * information may be of use in some cases, e.g. for sub configurations
066     * created using the {@code immutableConfigurationsAt()} method. The exact
067     * meaning of the string returned by this method is specific to a concrete
068     * implementation. For instance, an XML configuration might return the name
069     * of the document element.
070     *
071     * @return the name of the root element of this configuration
072     */
073    String getRootElementName();
074
075    /**
076     * <p>
077     * Returns an immutable hierarchical configuration object that wraps the
078     * configuration node specified by the given key. This method provides an
079     * easy means of accessing sub trees of a hierarchical configuration. In the
080     * returned configuration the sub tree can directly be accessed, it becomes
081     * the root node of this configuration. Because of this the passed in key
082     * must select exactly one configuration node; otherwise an
083     * {@code IllegalArgumentException} will be thrown.
084     * </p>
085     * <p>
086     * The difference between this method and the
087     * {@link #immutableSubset(String)} method is that
088     * {@code immutableSubset()} supports arbitrary subsets of configuration nodes
089     * while {@code immutableConfigurationAt()} only returns a single sub tree.
090     * Please refer to the documentation of the
091     * {@code SubnodeConfiguration} class to obtain further information
092     * about subnode configurations and when they should be used.
093     * </p>
094     *
095     * @param key the key that selects the sub tree
096     * @param supportUpdates a flag whether the returned subnode configuration
097     * should be able to handle updates of its parent
098     * @return a hierarchical configuration that contains this sub tree
099     */
100    ImmutableHierarchicalConfiguration immutableConfigurationAt(String key,
101            boolean supportUpdates);
102
103    /**
104     * Returns an immutable hierarchical configuration for the node specified by
105     * the given key. This is a short form for {@code immutableConfigurationAt(key,
106     * <b>false</b>)}.
107     *
108     * @param key the key that selects the sub tree
109     * @return a hierarchical configuration that contains this sub tree
110     */
111    ImmutableHierarchicalConfiguration immutableConfigurationAt(String key);
112
113    /**
114     * Returns a list of immutable configurations for all configuration nodes selected
115     * by the given key. This method will evaluate the passed in key (using the
116     * current {@code ExpressionEngine}) and then create an immutable subnode
117     * configuration for each returned node (like
118     * {@link #immutableConfigurationAt(String)}}). This is especially
119     * useful when dealing with list-like structures. As an example consider the
120     * configuration that contains data about database tables and their fields.
121     * If you need access to all fields of a certain table, you can simply do
122     *
123     * <pre>
124     * List&lt;ImmutableHierarchicalConfiguration&gt; fields =
125     *   config.immutableConfigurationsAt("tables.table(0).fields.field");
126     * for(Iterator&lt;ImmutableHierarchicalConfiguration&gt; it = fields.iterator();
127     *   it.hasNext();)
128     * {
129     *     ImmutableHierarchicalConfiguration sub = it.next();
130     *     // now the children and attributes of the field node can be
131     *     // directly accessed
132     *     String fieldName = sub.getString("name");
133     *     String fieldType = sub.getString("type");
134     *     ...
135     * </pre>
136     *
137     * @param key the key for selecting the desired nodes
138     * @return a list with immutable hierarchical configuration objects; each
139     * configuration represents one of the nodes selected by the passed in key
140     */
141    List<ImmutableHierarchicalConfiguration> immutableConfigurationsAt(String key);
142
143    /**
144     * Returns a list of immutable configurations for all direct child elements
145     * of the node selected by the given key. With this method it is possible to
146     * inspect the content of a hierarchical structure; all children of a given
147     * node can be queried without having to know their exact names. If the
148     * passed in key does not point to a single node, an empty list is returned.
149     * This is also the result if the node referred to by the key does not have
150     * child elements.
151     *
152     * @param key the key for selecting the desired parent node
153     * @return a collection with immutable configurations for all child nodes of
154     *         the selected parent node
155     */
156    List<ImmutableHierarchicalConfiguration> immutableChildConfigurationsAt(
157            String key);
158}