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