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