Package org.apache.commons.configuration2

Interface HierarchicalConfiguration<T>

Type Parameters:
T - the type of the nodes used by this hierarchical configuration
All Superinterfaces:
Configuration, ImmutableConfiguration, ImmutableHierarchicalConfiguration, NodeModelSupport<T>, SynchronizerSupport
All Known Implementing Classes:
AbstractHierarchicalConfiguration, AbstractYAMLBasedConfiguration, BaseHierarchicalConfiguration, CombinedConfiguration, DynamicCombinedConfiguration, INIConfiguration, JSONConfiguration, PatternSubtreeConfigurationWrapper, PropertyListConfiguration, SubnodeConfiguration, XMLConfiguration, XMLPropertyListConfiguration, YAMLConfiguration
public interface HierarchicalConfiguration<T> extends Configuration, ImmutableHierarchicalConfiguration, NodeModelSupport<T>

An interface for mutable hierarchical configurations.

This interface introduces methods for manipulating tree-like structured configuration sources. Also, all methods defined by the 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

  • Method Details

    • addNodes

      void addNodes(String key, Collection<? extends T> nodes)
      Adds a collection of nodes at the specified position of the configuration tree. This method works similar to 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 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.
      Parameters:
      key - the key where the nodes are to be added; can be null , then they are added to the root node
      nodes - a collection with the Node objects to be added

    • childConfigurationsAt

      List<HierarchicalConfiguration<T>> childConfigurationsAt(String key)
      Returns a list with sub configurations for all child nodes of the node selected by the given key. This method works like ImmutableHierarchicalConfiguration.immutableChildConfigurationsAt(String), but returns a list with mutable configuration objects. The configuration objects returned are not connected to the parent configuration.
      Parameters:
      key - the key for selecting the desired parent node
      Returns:
      a collection with HierarchicalConfiguration objects for all child nodes of the selected parent node

    • childConfigurationsAt

      List<HierarchicalConfiguration<T>> childConfigurationsAt(String key, boolean supportUpdates)
      Returns a list with sub configurations for all child nodes of the node selected by the given key allowing the caller to specify the supportUpdates flag.
      Parameters:
      key - the key for selecting the desired parent node
      supportUpdates - a flag whether the returned sub configuration should be directly connected to its parent
      Returns:
      a collection with HierarchicalConfiguration objects for all child nodes of the selected parent node

    • clearTree

      void clearTree(String key)
      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 clearTree("foo") would remove both properties.
      Parameters:
      key - the key of the property to be removed

    • configurationAt

      HierarchicalConfiguration<T> configurationAt(String key)
      Returns a hierarchical subnode configuration for the node specified by the given key. This is a short form for configurationAt(key, <b>false</b>).
      Parameters:
      key - the key that selects the sub tree
      Returns:
      a hierarchical configuration that contains this sub tree
      See Also:

    • configurationAt

      HierarchicalConfiguration<T> configurationAt(String key, boolean supportUpdates)

      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 IllegalArgumentException will be thrown.

      The difference between this method and the Configuration.subset(String) method is that subset() supports arbitrary subsets of configuration nodes while configurationAt() only returns a single sub tree. Please refer to the documentation of the SubnodeConfiguration class to obtain further information about sub configurations and when they should be used.

      With the 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.

      Parameters:
      key - the key that selects the sub tree
      supportUpdates - a flag whether the returned sub configuration should be directly connected to its parent
      Returns:
      a hierarchical configuration that contains this sub tree
      See Also:

    • configurationsAt

      List<HierarchicalConfiguration<T>> configurationsAt(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 ExpressionEngine) and then create a sub configuration for each returned node (like 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.
      Parameters:
      key - the key for selecting the desired nodes
      Returns:
      a list with hierarchical configuration objects; each configuration represents one of the nodes selected by the passed in key

    • configurationsAt

      List<HierarchicalConfiguration<T>> configurationsAt(String key, boolean supportUpdates)
      Returns a list of sub configurations for all configuration nodes selected by the given key allowing the caller to specify the supportUpdates flag. This method works like configurationsAt(String), but with the additional boolean parameter it can be specified whether the returned configurations react on updates of the parent configuration.
      Parameters:
      key - the key for selecting the desired nodes
      supportUpdates - a flag whether the returned sub configuration should be directly connected to its parent
      Returns:
      a list with hierarchical configuration objects; each configuration represents one of the nodes selected by the passed in key
      See Also:

    • setExpressionEngine

      void setExpressionEngine(ExpressionEngine expressionEngine)
      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.
      Parameters:
      expressionEngine - the new expression engine; can be null, then the default expression engine will be used