    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.Collection;
    020import java.util.List;
    021
    022import org.apache.commons.configuration2.tree.ExpressionEngine;
    023import org.apache.commons.configuration2.tree.NodeModelSupport;
    024
    025/**
    026 * <p>
    027 * An interface for mutable hierarchical configurations.
    028 * </p>
    029 * <p>
    030 * This interface introduces methods for manipulating tree-like structured configuration sources. Also, all methods
    031 * defined by the {@code Configuration} interface are available.
    032 * </p>
    033 * <p>
    034 * This interface does not make any assumptions about the concrete type of nodes used by an implementation; this is
    035 * reflected by a generic type parameter. Concrete implementations may therefore define their own hierarchical
    036 * structures.
    037 * </p>
    038 *
    039 * @param <T> the type of the nodes used by this hierarchical configuration
    040 * @since 2.0
    041 */
    042public interface HierarchicalConfiguration<T> extends Configuration, ImmutableHierarchicalConfiguration, NodeModelSupport<T> {
    043
    044    /**
    045     * Adds a collection of nodes at the specified position of the configuration tree. This method works similar to
    046     * {@code addProperty()}, but instead of a single property a whole collection of nodes can be added - and thus complete
    047     * configuration sub trees. E.g. with this method it is possible to add parts of another
    048     * {@code BaseHierarchicalConfiguration} object to this object. If the passed in key refers to an existing and unique
    049     * node, the new nodes are added to this node. Otherwise a new node will be created at the specified position in the
    050     * hierarchy.
    051     *
    052     * @param key the key where the nodes are to be added; can be <strong>null </strong>, then they are added to the root node
    053     * @param nodes a collection with the {@code Node} objects to be added
    054     */
    055    void addNodes(String key, Collection<? extends T> nodes);
    056
    057    /**
    058     * Returns a list with sub configurations for all child nodes of the node selected by the given key. This method works
    059     * like {@link #immutableChildConfigurationsAt(String)}, but returns a list with mutable configuration objects. The
    060     * configuration objects returned are <strong>not</strong> connected to the parent configuration.
    061     *
    062     * @param key the key for selecting the desired parent node
    063     * @return a collection with {@code HierarchicalConfiguration} objects for all child nodes of the selected parent node
    064     */
    065    List<HierarchicalConfiguration<T>> childConfigurationsAt(String key);
    066
    067    /**
    068     * Returns a list with sub configurations for all child nodes of the node selected by the given key allowing the caller
    069     * to specify the {@code supportUpdates} flag.
    070     *
    071     * @param key the key for selecting the desired parent node
    072     * @param supportUpdates a flag whether the returned sub configuration should be directly connected to its parent
    073     * @return a collection with {@code HierarchicalConfiguration} objects for all child nodes of the selected parent node
    074     */
    075    List<HierarchicalConfiguration<T>> childConfigurationsAt(String key, boolean supportUpdates);
    076
    077    /**
    078     * Removes all values of the property with the given name and of keys that start with this name. So if there is a
    079     * property with the key &quot;foo&quot; and a property with the key &quot;foo.bar&quot;, a call of
    080     * {@code clearTree("foo")} would remove both properties.
    081     *
    082     * @param key the key of the property to be removed
    083     */
    084    void clearTree(String key);
    085
    086    /**
    087     * Returns a hierarchical subnode configuration for the node specified by the given key. This is a short form for
    088     * {@code configurationAt(key,
    089     * <strong>false</strong>)}.
    090     *
    091     * @param key the key that selects the sub tree
    092     * @return a hierarchical configuration that contains this sub tree
    093     * @see SubnodeConfiguration
    094     */
    095    HierarchicalConfiguration<T> configurationAt(String key);
    096
    097    /**
    098     * <p>
    099     * Returns a hierarchical sub configuration object that wraps the configuration node specified by the given key. This
    100     * method provides an easy means of accessing sub trees of a hierarchical configuration. In the returned configuration
    101     * the sub tree can directly be accessed, it becomes the root node of this configuration. Because of this the passed in
    102     * key must select exactly one configuration node; otherwise an {@code IllegalArgumentException} will be thrown.
    103     * </p>
    104     * <p>
    105     * The difference between this method and the {@link #subset(String)} method is that {@code subset()} supports arbitrary
    106     * subsets of configuration nodes while {@code configurationAt()} only returns a single sub tree. Please refer to the
    107     * documentation of the {@link SubnodeConfiguration} class to obtain further information about sub configurations and
    108     * when they should be used.
    109     * </p>
    110     * <p>
    111     * With the {@code supportUpdate} flag the behavior of the returned sub configuration regarding updates of its parent
    112     * configuration can be determined. If set to <strong>false</strong>, the configurations return on independent nodes structures.
    113     * So changes made on one configuration cannot be seen by the other one. A value of <strong>true</strong> in contrast creates a
    114     * direct connection between both configurations - they are then using the same underlying data structures as much as
    115     * possible. There are however changes which break this connection; for instance, if the sub tree the sub configuration
    116     * belongs to is completely removed from the parent configuration. If such a change happens, the sub configuration
    117     * becomes detached from its parent. It can still be used in a normal way, but changes on it are not reflected by the
    118     * parent and vice verse. Also, it is not possible to reattach a once detached sub configuration.
    119     * </p>
    120     *
    121     * @param key the key that selects the sub tree
    122     * @param supportUpdates a flag whether the returned sub configuration should be directly connected to its parent
    123     * @return a hierarchical configuration that contains this sub tree
    124     * @see SubnodeConfiguration
    125     */
    126    HierarchicalConfiguration<T> configurationAt(String key, boolean supportUpdates);
    127
    128    /**
    129     * Returns a list of sub configurations for all configuration nodes selected by the given key. This method will evaluate
    130     * the passed in key (using the current {@code ExpressionEngine}) and then create a sub configuration for each returned
    131     * node (like {@link #configurationAt(String)} ). This is especially useful when dealing with list-like structures. As
    132     * an example consider the configuration that contains data about database tables and their fields. If you need access
    133     * to all fields of a certain table, you can simply do
    134     *
    135     * <pre>
    136     * List fields = config.configurationsAt("tables.table(0).fields.field");
    137     * for(Iterator it = fields.iterator(); it.hasNext();)
    138     * {
    139     *     BaseHierarchicalConfiguration sub = (BaseHierarchicalConfiguration) it.next();
    140     *     // now the children and attributes of the field node can be
    141     *     // directly accessed
    142     *     String fieldName = sub.getString("name");
    143     *     String fieldType = sub.getString("type");
    144     *     ...
    145     * </pre>
    146     *
    147     * The configuration objects returned are <strong>not</strong> connected to the parent configuration.
    148     *
    149     * @param key the key for selecting the desired nodes
    150     * @return a list with hierarchical configuration objects; each configuration represents one of the nodes selected by
    151     *         the passed in key
    152     */
    153    List<HierarchicalConfiguration<T>> configurationsAt(String key);
    154
    155    /**
    156     * Returns a list of sub configurations for all configuration nodes selected by the given key allowing the caller to
    157     * specify the {@code supportUpdates} flag. This method works like {@link #configurationsAt(String)}, but with the
    158     * additional boolean parameter it can be specified whether the returned configurations react on updates of the parent
    159     * configuration.
    160     *
    161     * @param key the key for selecting the desired nodes
    162     * @param supportUpdates a flag whether the returned sub configuration should be directly connected to its parent
    163     * @return a list with hierarchical configuration objects; each configuration represents one of the nodes selected by
    164     *         the passed in key
    165     * @see #configurationsAt(String, boolean)
    166     */
    167    List<HierarchicalConfiguration<T>> configurationsAt(String key, boolean supportUpdates);
    168
    169    /**
    170     * Sets the expression engine to be used by this configuration. All property keys this configuration has to deal with
    171     * will be interpreted by this engine.
    172     *
    173     * @param expressionEngine the new expression engine; can be <strong>null</strong>, then the default expression engine will be
    174     *        used
    175     */
    176    void setExpressionEngine(ExpressionEngine expressionEngine);
    177}