Class BaseHierarchicalConfiguration
- All Implemented Interfaces:
Cloneable,Configuration,EventSource,HierarchicalConfiguration<ImmutableNode>,ImmutableConfiguration,ImmutableHierarchicalConfiguration,SynchronizerSupport,InMemoryNodeModelSupport,NodeKeyResolver<ImmutableNode>,NodeModelSupport<ImmutableNode>
- Direct Known Subclasses:
AbstractYAMLBasedConfiguration,CombinedConfiguration,INIConfiguration,PatternSubtreeConfigurationWrapper,PropertyListConfiguration,SubnodeConfiguration,XMLConfiguration,XMLPropertyListConfiguration
A specialized hierarchical configuration implementation that is based on a structure of ImmutableNode
objects.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected static classA specialized visitor base class that can be used for storing the tree of configuration nodes. -
Constructor Summary
ConstructorsModifierConstructorDescriptionCreates a new instance ofBaseHierarchicalConfiguration.Creates a new instance ofBaseHierarchicalConfigurationand copies all data contained in the specified configuration into the new one.protectedCreates a new instance ofBaseHierarchicalConfigurationand initializes it with the givenNodeModel. -
Method Summary
Modifier and TypeMethodDescriptionReturns a list with sub configurations for all child nodes of the node selected by the given key.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 thesupportUpdatesflag.protected NodeModel<ImmutableNode> Creates a clone of the node model.configurationAt(String key) Returns a hierarchical subnode configuration for the node specified by the given key.configurationAt(String key, boolean supportUpdates) Returns a hierarchical sub configuration object that wraps the configuration node specified by the given key.configurationsAt(String key) Returns a list of sub configurations for all configuration nodes selected by the given key.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 thesupportUpdatesflag.protected SubnodeConfigurationcreateSubConfigurationForTrackedNode(NodeSelector selector, InMemoryNodeModelSupport parentModelSupport) Creates a connected sub configuration based on a selector for a tracked node.Gets theNodeModelsupported by this object.protected NodeSelectorGets theNodeSelectorto be used for a sub configuration based on the passed in key.protected InMemoryNodeModelGets theInMemoryNodeModelto be used as parent model for a new sub configuration.Returns a list of immutable configurations for all direct child elements of the node selected by the given key.Returns an immutable hierarchical configuration for the node specified by the given key.immutableConfigurationAt(String key, boolean supportUpdates) Returns an immutable hierarchical configuration object that wraps the configuration node specified by the given key.Returns a list of immutable configurations for all configuration nodes selected by the given key.protected voidInitializes aSubnodeConfigurationobject.Returns a configuration with the same content as this configuration, but with all variables replaced by their actual values.protected voidThis method is always called when a subnode configuration created from this configuration has been modified.Creates a newConfigurationobject containing all keys that start with the specified prefix.Methods inherited from class org.apache.commons.configuration2.AbstractHierarchicalConfiguration
addNodes, addNodesInternal, addPropertyDirect, addPropertyInternal, clearInternal, clearPropertyDirect, clearTree, clearTreeInternal, clone, containsKeyInternal, containsValueInternal, fetchNodeList, getExpressionEngine, getKeysInternal, getKeysInternal, getKeysInternal, getMaxIndex, getMaxIndexInternal, getModel, getPropertyInternal, getRootElementName, getRootElementNameInternal, isEmptyInternal, nodeDefined, nodeKey, resolveAddKey, resolveKey, resolveNodeKey, resolveUpdateKey, setExpressionEngine, setPropertyInternal, sizeInternal, toStringMethods inherited from class org.apache.commons.configuration2.AbstractConfiguration
addErrorLogListener, addProperty, append, beginRead, beginWrite, clear, clearProperty, cloneInterpolator, contains, containsKey, containsValue, copy, endRead, endWrite, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getConfigurationDecoder, getConversionHandler, getDouble, getDouble, getDouble, getDuration, getDuration, getEncodedString, getEncodedString, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getKeys, getKeys, getKeys, getList, getList, getList, getList, getListDelimiterHandler, getLogger, getLong, getLong, getLong, getProperties, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, getSynchronizer, immutableSubset, initLogger, installInterpolator, interpolate, interpolate, isEmpty, isScalarValue, isThrowExceptionOnMissing, lock, setConfigurationDecoder, setConversionHandler, setDefaultLookups, setInterpolator, setListDelimiterHandler, setLogger, setParentInterpolator, setPrefixLookups, setProperty, setSynchronizer, setThrowExceptionOnMissing, size, unlockMethods inherited from class org.apache.commons.configuration2.event.BaseEventSource
addEventListener, clearErrorListeners, clearEventListeners, copyEventListeners, createErrorEvent, createEvent, fireError, fireEvent, getEventListenerRegistrations, getEventListeners, isDetailEvents, removeEventListener, setDetailEventsMethods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitMethods inherited from interface org.apache.commons.configuration2.Configuration
addProperty, clear, clearProperty, getInterpolator, installInterpolator, setInterpolator, setPropertyMethods inherited from interface org.apache.commons.configuration2.ImmutableConfiguration
containsKey, containsValue, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getDouble, getDouble, getDouble, getDuration, getDuration, getEncodedString, getEncodedString, getEnum, getEnum, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getKeys, getKeys, getList, getList, getList, getList, getLong, getLong, getLong, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, immutableSubset, isEmpty, sizeMethods inherited from interface org.apache.commons.configuration2.sync.SynchronizerSupport
getSynchronizer, lock, setSynchronizer, unlock
-
Constructor Details
-
BaseHierarchicalConfiguration
public BaseHierarchicalConfiguration()Creates a new instance ofBaseHierarchicalConfiguration. -
BaseHierarchicalConfiguration
Creates a new instance ofBaseHierarchicalConfigurationand copies all data contained in the specified configuration into the new one.- Parameters:
c- the configuration that is to be copied (if null, this constructor will behave like the standard constructor)- Since:
- 1.4
-
BaseHierarchicalConfiguration
Creates a new instance ofBaseHierarchicalConfigurationand initializes it with the givenNodeModel.- Parameters:
model- theNodeModel
-
-
Method Details
-
childConfigurationsAt
Returns a list with sub configurations for all child nodes of the node selected by the given key. This method works likeImmutableHierarchicalConfiguration.immutableChildConfigurationsAt(String), but returns a list with mutable configuration objects. The configuration objects returned are not connected to the parent configuration. This implementation resolves the node(s) selected by the given key. If not a single node is selected, an empty list is returned. Otherwise, sub configurations for each child of the node are created.- Specified by:
childConfigurationsAtin interfaceHierarchicalConfiguration<ImmutableNode>- Parameters:
key- the key for selecting the desired parent node- Returns:
- a collection with
HierarchicalConfigurationobjects for all child nodes of the selected parent node
-
childConfigurationsAt
public List<HierarchicalConfiguration<ImmutableNode>> 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 thesupportUpdatesflag. This method works likechildConfigurationsAt(String); however, depending on the value of thesupportUpdatesflag, connected sub configurations may be created.- Specified by:
childConfigurationsAtin interfaceHierarchicalConfiguration<ImmutableNode>- Parameters:
key- the key for selecting the desired parent nodesupportUpdates- a flag whether the returned sub configuration should be directly connected to its parent- Returns:
- a collection with
HierarchicalConfigurationobjects for all child nodes of the selected parent node
-
cloneNodeModel
Creates a clone of the node model. This method is called byclone(). This implementation creates a new instance ofInMemoryNodeModel, initialized with this configuration's root node. This has the effect that although the same nodes are used, the original and copied configurations are independent on each other.- Specified by:
cloneNodeModelin classAbstractHierarchicalConfiguration<ImmutableNode>- Returns:
- the clone of the
NodeModel
-
configurationAt
Returns a hierarchical subnode configuration for the node specified by the given key. This is a short form forconfigurationAt(key, <strong>false</strong>). This is a short form forconfigurationAt(key, <strong>false</strong>).- Specified by:
configurationAtin interfaceHierarchicalConfiguration<ImmutableNode>- Parameters:
key- the key that selects the sub tree- Returns:
- a hierarchical configuration that contains this sub tree
- Throws:
ConfigurationRuntimeException- if the key does not select a single node- See Also:
-
configurationAt
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
IllegalArgumentExceptionwill be thrown.The difference between this method and the
Configuration.subset(String)method is thatsubset()supports arbitrary subsets of configuration nodes whileconfigurationAt()only returns a single sub tree. Please refer to the documentation of theSubnodeConfigurationclass to obtain further information about sub configurations and when they should be used.With the
The result of this implementation depends on thesupportUpdateflag 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.supportUpdatesflag: If it is false, a plainBaseHierarchicalConfigurationis returned using the selected node as root node. This is suitable for read-only access to properties. Because the configuration returned in this case is not connected to the parent configuration, updates on properties made by one configuration are not reflected by the other one. A value of true for this parameter causes a tracked node to be created, and result is aSubnodeConfigurationbased on this tracked node. This configuration is really connected to its parent, so that updated properties are visible on both.- Specified by:
configurationAtin interfaceHierarchicalConfiguration<ImmutableNode>- Parameters:
key- the key that selects the sub treesupportUpdates- a flag whether the returned sub configuration should be directly connected to its parent- Returns:
- a hierarchical configuration that contains this sub tree
- Throws:
ConfigurationRuntimeException- if the key does not select a single node- See Also:
-
configurationsAt
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 currentExpressionEngine) and then create a sub configuration for each returned node (likeHierarchicalConfiguration.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 doList 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. This implementation creates sub configurations in the same way as described forconfigurationAt(String).- Specified by:
configurationsAtin interfaceHierarchicalConfiguration<ImmutableNode>- 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
public List<HierarchicalConfiguration<ImmutableNode>> 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 thesupportUpdatesflag. This method works likeHierarchicalConfiguration.configurationsAt(String), but with the additional boolean parameter it can be specified whether the returned configurations react on updates of the parent configuration. This implementation creates tracked nodes for the specified key. Then sub configurations for these nodes are created and returned.- Specified by:
configurationsAtin interfaceHierarchicalConfiguration<ImmutableNode>- Parameters:
key- the key for selecting the desired nodessupportUpdates- 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:
-
createSubConfigurationForTrackedNode
protected SubnodeConfiguration createSubConfigurationForTrackedNode(NodeSelector selector, InMemoryNodeModelSupport parentModelSupport) Creates a connected sub configuration based on a selector for a tracked node.- Parameters:
selector- theNodeSelectorparentModelSupport- theInMemoryNodeModelSupportobject for the parent node model- Returns:
- the newly created sub configuration
- Since:
- 2.0
-
getNodeModel
Gets theNodeModelsupported by this object. This implementation returns the configuration'sNodeModel. It is guarded by the currentSynchronizer. This implementation returns theInMemoryNodeModelused by this configuration.- Specified by:
getNodeModelin interfaceInMemoryNodeModelSupport- Specified by:
getNodeModelin interfaceNodeModelSupport<ImmutableNode>- Overrides:
getNodeModelin classAbstractHierarchicalConfiguration<ImmutableNode>- Returns:
- the
NodeModel
-
getSubConfigurationNodeSelector
Gets theNodeSelectorto be used for a sub configuration based on the passed in key. This method is called whenever a sub configuration is to be created. This base implementation returns a newNodeSelectorinitialized with the passed in key. Sub classes may override this method if they have a different strategy for creating a selector.- Parameters:
key- the key of the sub configuration- Returns:
- a
NodeSelectorfor initializing a sub configuration - Since:
- 2.0
-
getSubConfigurationParentModel
Gets theInMemoryNodeModelto be used as parent model for a new sub configuration. This method is called whenever a sub configuration is to be created. This base implementation returns the model of this configuration. Sub classes with different requirements for the parent models of sub configurations have to override it.- Returns:
- the parent model for a new sub configuration
-
immutableChildConfigurationsAt
Returns a list of immutable configurations for all direct child elements of the node selected by the given key. With this method it is possible to inspect the content of a hierarchical structure; all children of a given node can be queried without having to know their exact names. If the passed in key does not point to a single node, an empty list is returned. This is also the result if the node referred to by the key does not have child elements. This implementation first delegates tochildConfigurationsAt()to create a list of mutable child configurations. Then a list with immutable wrapper configurations is created.- Specified by:
immutableChildConfigurationsAtin interfaceImmutableHierarchicalConfiguration- Parameters:
key- the key for selecting the desired parent node- Returns:
- a collection with immutable configurations for all child nodes of the selected parent node
-
immutableConfigurationAt
Returns an immutable hierarchical configuration for the node specified by the given key. This is a short form forimmutableConfigurationAt(key, <strong>false</strong>). This implementation creates aSubnodeConfigurationby delegating toconfigurationAt(). Then an immutable wrapper is created and returned.- Specified by:
immutableConfigurationAtin interfaceImmutableHierarchicalConfiguration- Parameters:
key- the key that selects the sub tree- Returns:
- a hierarchical configuration that contains this sub tree
- Throws:
ConfigurationRuntimeException- if the key does not select a single node
-
immutableConfigurationAt
public ImmutableHierarchicalConfiguration immutableConfigurationAt(String key, boolean supportUpdates) Returns an immutable hierarchical 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
IllegalArgumentExceptionwill be thrown.The difference between this method and the
This implementation creates aImmutableConfiguration.immutableSubset(String)method is thatimmutableSubset()supports arbitrary subsets of configuration nodes whileimmutableConfigurationAt()only returns a single sub tree. Please refer to the documentation of theSubnodeConfigurationclass to obtain further information about subnode configurations and when they should be used.SubnodeConfigurationby delegating toconfigurationAt(). Then an immutable wrapper is created and returned.- Specified by:
immutableConfigurationAtin interfaceImmutableHierarchicalConfiguration- Parameters:
key- the key that selects the sub treesupportUpdates- a flag whether the returned subnode configuration should be able to handle updates of its parent- Returns:
- a hierarchical configuration that contains this sub tree
-
immutableConfigurationsAt
Returns a list of immutable configurations for all configuration nodes selected by the given key. This method will evaluate the passed in key (using the currentExpressionEngine) and then create an immutable subnode configuration for each returned node (likeImmutableHierarchicalConfiguration.immutableConfigurationAt(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 doList<ImmutableHierarchicalConfiguration> fields = config.immutableConfigurationsAt("tables.table(0).fields.field"); for(Iterator<ImmutableHierarchicalConfiguration> it = fields.iterator(); it.hasNext();) { ImmutableHierarchicalConfiguration sub = 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"); ...This implementation first delegates toconfigurationsAt()to create a list ofSubnodeConfigurationobjects. Then for each element of this list an unmodifiable wrapper is created.- Specified by:
immutableConfigurationsAtin interfaceImmutableHierarchicalConfiguration- Parameters:
key- the key for selecting the desired nodes- Returns:
- a list with immutable hierarchical configuration objects; each configuration represents one of the nodes selected by the passed in key
-
initSubConfigurationForThisParent
Initializes aSubnodeConfigurationobject. This method should be called for each sub configuration created for this configuration. It ensures that the sub configuration is correctly connected to its parent instance and that update events are correctly propagated.- Parameters:
subConfig- the sub configuration to be initialized- Since:
- 2.0
-
interpolatedConfiguration
Returns a configuration with the same content as this configuration, but with all variables replaced by their actual values. This implementation is specific for hierarchical configurations. It clones the current configuration and runs a specialized visitor on the clone, which performs interpolation on the single configuration nodes.- Overrides:
interpolatedConfigurationin classAbstractConfiguration- Returns:
- a configuration with all variables interpolated
- Since:
- 1.5
-
subnodeConfigurationChanged
This method is always called when a subnode configuration created from this configuration has been modified. This implementation transforms the received event into an event of typeSUBNODE_CHANGEDand notifies the registered listeners.- Parameters:
event- the event describing the change- Since:
- 1.5
-
subset
Creates a newConfigurationobject containing all keys that start with the specified prefix. This implementation will return aBaseHierarchicalConfigurationobject so that the structure of the keys will be saved. The nodes selected by the prefix (it is possible that multiple nodes are selected) are mapped to the root node of the returned configuration, i.e. their children and attributes will become children and attributes of the new root node. However, a value of the root node is only set if exactly one of the selected nodes contain a value (if multiple nodes have a value, there is simply no way to decide how these values are merged together). Note that the returnedConfigurationobject is not connected to its source configuration: updates on the source configuration are not reflected in the subset and vice versa. The returned configuration uses the sameSynchronizeras this configuration.- Specified by:
subsetin interfaceConfiguration- Overrides:
subsetin classAbstractConfiguration- Parameters:
prefix- the prefix of the keys for the subset- Returns:
- a new configuration object representing the selected subset
- See Also:
-