org.apache.commons.configuration2.HierarchicalConfiguration Maven / Gradle / Ivy
Show all versions of commons-configuration2 Show documentation
/*
* 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.Collection;
import java.util.List;
import org.apache.commons.configuration2.tree.ExpressionEngine;
import org.apache.commons.configuration2.tree.NodeModelSupport;
/**
*
* An interface for mutable hierarchical configurations.
*
*
* This interface introduces methods for manipulating tree-like structured
* configuration sources. Also, all methods defined by the {@code Configuration}
* interface are available.
*
*
* This interface does not make any assumptions about the concrete type of nodes
* used by an implementation; this is reflected by a generic type parameter.
* Concrete implementations may therefore define their own hierarchical
* structures.
*
*
* @since 2.0
* @param the type of the nodes used by this hierarchical configuration
*/
public interface HierarchicalConfiguration
extends Configuration, ImmutableHierarchicalConfiguration, NodeModelSupport
{
/**
* Sets the expression engine to be used by this configuration. All property
* keys this configuration has to deal with will be interpreted by this
* engine.
*
* @param expressionEngine the new expression engine; can be null,
* then the default expression engine will be used
*/
void setExpressionEngine(ExpressionEngine expressionEngine);
/**
* Adds a collection of nodes at the specified position of the configuration
* tree. This method works similar to {@code addProperty()}, but
* instead of a single property a whole collection of nodes can be added -
* and thus complete configuration sub trees. E.g. with this method it is
* possible to add parts of another {@code BaseHierarchicalConfiguration}
* object to this object. If the passed in key refers to
* an existing and unique node, the new nodes are added to this node.
* Otherwise a new node will be created at the specified position in the
* hierarchy.
*
* @param key the key where the nodes are to be added; can be null ,
* then they are added to the root node
* @param nodes a collection with the {@code Node} objects to be
* added
*/
void addNodes(String key, Collection nodes);
/**
*
* Returns a hierarchical sub 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.
*
*
* The difference between this method and the
* {@link #subset(String)} method is that
* {@code subset()} supports arbitrary subsets of configuration nodes
* while {@code configurationAt()} only returns a single sub tree.
* Please refer to the documentation of the
* {@link SubnodeConfiguration} class to obtain further information
* about sub configurations and when they should be used.
*
*
* With the {@code supportUpdate} flag the behavior of the returned
* sub configuration regarding updates of its parent
* configuration can be determined. If set to false, the configurations
* return on independent nodes structures. So changes made on one configuration
* cannot be seen by the other one. A value of true in contrast creates
* a direct connection between both configurations - they are then using the
* same underlying data structures as much as possible. There are however changes
* which break this connection; for instance, if the sub tree the sub configuration
* belongs to is completely removed from the parent configuration. If such a
* change happens, the sub configuration becomes detached from its parent.
* It can still be used in a normal way, but changes on it are not reflected
* by the parent and vice verse. Also, it is not possible to reattach a once
* detached sub configuration.
*
*
* @param key the key that selects the sub tree
* @param supportUpdates a flag whether the returned sub configuration
* should be directly connected to its parent
* @return a hierarchical configuration that contains this sub tree
* @see SubnodeConfiguration
*/
HierarchicalConfiguration configurationAt(String key, boolean supportUpdates);
/**
* Returns a hierarchical subnode configuration for the node specified by
* the given key. This is a short form for {@code configurationAt(key,
* false)}.
*
* @param key the key that selects the sub tree
* @return a hierarchical configuration that contains this sub tree
* @see SubnodeConfiguration
*/
HierarchicalConfiguration configurationAt(String key);
/**
* Returns a list of sub 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 a sub configuration for
* each returned node (like {@link #configurationAt(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
*
*
* List fields = config.configurationsAt("tables.table(0).fields.field");
* for(Iterator it = fields.iterator(); it.hasNext();)
* {
* BaseHierarchicalConfiguration sub = (BaseHierarchicalConfiguration) 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");
* ...
*
*
* The configuration objects returned are not connected to
* the parent configuration.
*
* @param key the key for selecting the desired nodes
* @return a list with hierarchical configuration objects; each
* configuration represents one of the nodes selected by the passed
* in key
*/
List> configurationsAt(String key);
/**
* Returns a list of sub configurations for all configuration nodes selected
* by the given key allowing the caller to specify the
* {@code supportUpdates} flag. This method works like
* {@link #configurationsAt(String)}, but with the additional boolean
* parameter it can be specified whether the returned configurations react
* on updates of the parent configuration.
*
* @param key the key for selecting the desired nodes
* @param supportUpdates a flag whether the returned sub configuration
* should be directly connected to its parent
* @return a list with hierarchical configuration objects; each
* configuration represents one of the nodes selected by the passed
* in key
* @see #configurationsAt(String, boolean)
*/
List> configurationsAt(String key,
boolean supportUpdates);
/**
* Returns a list with sub configurations for all child nodes of the node
* selected by the given key. This method works like
* {@link #immutableChildConfigurationsAt(String)}, but returns a list with
* mutable configuration objects. The configuration objects returned are
* not connected to the parent configuration.
*
* @param key the key for selecting the desired parent node
* @return a collection with {@code HierarchicalConfiguration} objects for all
* child nodes of the selected parent node
*/
List> childConfigurationsAt(String key);
/**
* Returns a list with sub configurations for all child nodes of the node
* selected by the given key allowing the caller to specify the
* {@code supportUpdates} flag.
*
* @param key the key for selecting the desired parent node
* @param supportUpdates a flag whether the returned sub configuration
* should be directly connected to its parent
* @return a collection with {@code HierarchicalConfiguration} objects for
* all child nodes of the selected parent node
*/
List> childConfigurationsAt(String key,
boolean supportUpdates);
/**
* Removes all values of the property with the given name and of keys that
* start with this name. So if there is a property with the key
* "foo" and a property with the key "foo.bar", a call
* of {@code clearTree("foo")} would remove both properties.
*
* @param key the key of the property to be removed
*/
void clearTree(String key);
}