public class HierarchicalConfiguration extends AbstractConfiguration implements Serializable, Cloneable
A specialized configuration class that extends its base class by the ability of keeping more structure in the stored properties.
There
are some sources of configuration data that cannot be stored very well in a
BaseConfiguration
object because then their structure is lost.
This is especially true for XML documents. This class can deal with such
structured configuration sources by storing the properties in a tree-like
organization.
The internal used storage form allows for a more sophisticated access to single properties. As an example consider the following XML document:
<database> <tables> <table> <name>users</name> <fields> <field> <name>lid</name> <type>long</name> </field> <field> <name>usrName</name> <type>java.lang.String</type> </field> ... </fields> </table> <table> <name>documents</name> <fields> <field> <name>docid</name> <type>long</type> </field> ... </fields> </table> ... </tables> </database>
If this document is parsed and stored in a
HierarchicalConfiguration
object (which can be done by one of
the sub classes), there are enhanced possibilities of accessing properties.
The keys for querying information can contain indices that select a certain
element if there are multiple hits.
For instance the key
tables.table(0).name
can be used to find out the name of the
first table. In opposite tables.table.name
would return a
collection with the names of all available tables. Similarly the key
tables.table(1).fields.field.name
returns a collection with
the names of all fields of the second table. If another index is added after
the field
element, a single field can be accessed:
tables.table(1).fields.field(0).name
.
There is a
getMaxIndex()
method that returns the maximum allowed index
that can be added to a given property key. This method can be used to iterate
over all values defined for a certain property.
Since the 1.3 release of Commons Configuration hierarchical
configurations support an expression engine. This expression engine
is responsible for evaluating the passed in configuration keys and map them
to the stored properties. The examples above are valid for the default
expression engine, which is used when a new HierarchicalConfiguration
instance is created. With the setExpressionEngine()
method a
different expression engine can be set. For instance with
there is an expression engine available that supports configuration keys in
XPATH syntax.XPathExpressionEngine
In addition to the events common for all configuration classes hierarchical configurations support some more events that correspond to some specific methods and features:
addNodes()
method
was called; the event object contains the key, to which the nodes were added,
and a collection with the new nodes as value.clearTree()
method was
called; the event object stores the key of the removed sub tree.SubnodeConfiguration
that was created from this configuration has been changed. The value property
of the event object contains the original event object as it was sent by the
subnode configuration.Note:Configuration objects of this type can be read concurrently by multiple threads. However if one of these threads modifies the object, synchronization has to be performed manually.
Modifier and Type | Class and Description |
---|---|
protected static class |
HierarchicalConfiguration.BuilderVisitor
A specialized visitor base class that can be used for storing the tree of
configuration nodes.
|
static class |
HierarchicalConfiguration.Node
A data class for storing (hierarchical) property information.
|
static class |
HierarchicalConfiguration.NodeVisitor
Definition of a visitor class for traversing a node and all of its
children.
|
Modifier and Type | Field and Description |
---|---|
static int |
EVENT_ADD_NODES
Constant for the add nodes event.
|
static int |
EVENT_CLEAR_TREE
Constant for the clear tree event.
|
static int |
EVENT_SUBNODE_CHANGED
Constant for the subnode configuration modified event.
|
END_TOKEN, EVENT_ADD_PROPERTY, EVENT_CLEAR, EVENT_CLEAR_PROPERTY, EVENT_READ_PROPERTY, EVENT_SET_PROPERTY, START_TOKEN
Constructor and Description |
---|
HierarchicalConfiguration()
Creates a new instance of
HierarchicalConfiguration . |
HierarchicalConfiguration(HierarchicalConfiguration c)
Creates a new instance of
HierarchicalConfiguration and
copies all data contained in the specified configuration into the new
one. |
Modifier and Type | Method and Description |
---|---|
void |
addNodes(String key,
Collection nodes)
Adds a collection of nodes at the specified position of the configuration
tree.
|
protected void |
addPropertyDirect(String key,
Object obj)
Adds the property with the specified key.
|
protected void |
clearNode(ConfigurationNode node)
Clears the value of the specified node.
|
protected void |
clearNode(HierarchicalConfiguration.Node node)
Deprecated.
Use the method
instead |
void |
clearProperty(String key)
Removes the property with the given key.
|
protected static void |
clearReferences(ConfigurationNode node)
Clears all reference fields in a node structure.
|
void |
clearTree(String key)
Removes all values of the property with the given name and of keys that
start with this name.
|
Object |
clone()
Creates a copy of this object.
|
SubnodeConfiguration |
configurationAt(String key)
Returns a hierarchical subnode configuration for the node specified by
the given key.
|
SubnodeConfiguration |
configurationAt(String key,
boolean supportUpdates)
Returns a hierarchical subnode configuration object that wraps the
configuration node specified by the given key.
|
List |
configurationsAt(String key)
Returns a list of sub configurations for all configuration nodes selected
by the given key.
|
boolean |
containsKey(String key)
Checks if the specified key is contained in this configuration.
|
protected HierarchicalConfiguration.Node |
createAddPath(ConfigurationKey.KeyIterator keyIt,
HierarchicalConfiguration.Node root)
Deprecated.
Adding new properties is now to a major part delegated to the
ExpressionEngine associated with this configuration instance.
This method will no longer be called. Developers who want to modify the
process of adding new properties should consider implementing their own
expression engine. |
protected HierarchicalConfiguration.Node |
createNode(String name)
Creates a new
Node object with the specified name. |
protected SubnodeConfiguration |
createSubnodeConfiguration(ConfigurationNode node)
Creates a subnode configuration for the specified node.
|
protected SubnodeConfiguration |
createSubnodeConfiguration(ConfigurationNode node,
String subnodeKey)
Creates a new subnode configuration for the specified node and sets its
construction key.
|
protected HierarchicalConfiguration.Node |
fetchAddNode(ConfigurationKey.KeyIterator keyIt,
HierarchicalConfiguration.Node startNode)
Deprecated.
Adding new properties is now to a major part delegated to the
ExpressionEngine associated with this configuration instance.
This method will no longer be called. Developers who want to modify the
process of adding new properties should consider implementing their own
expression engine. |
protected List |
fetchNodeList(String key)
Helper method for fetching a list of all nodes that are addressed by the
specified key.
|
protected HierarchicalConfiguration.Node |
findLastPathNode(ConfigurationKey.KeyIterator keyIt,
HierarchicalConfiguration.Node node)
Deprecated.
Adding new properties is now to a major part delegated to the
ExpressionEngine associated with this configuration instance.
This method will no longer be called. Developers who want to modify the
process of adding new properties should consider implementing their own
expression engine. |
protected void |
findPropertyNodes(ConfigurationKey.KeyIterator keyPart,
HierarchicalConfiguration.Node node,
Collection nodes)
Deprecated.
Property keys are now evaluated by the expression engine
associated with the configuration; this method will no longer be called.
If you want to modify the way properties are looked up, consider
implementing you own
ExpressionEngine implementation. |
static ExpressionEngine |
getDefaultExpressionEngine()
Returns the default expression engine.
|
ExpressionEngine |
getExpressionEngine()
Returns the expression engine used by this configuration.
|
Iterator |
getKeys()
Returns an iterator with all keys defined in this configuration.
|
Iterator |
getKeys(String prefix)
Returns an iterator with all keys defined in this configuration that
start with the given prefix.
|
int |
getMaxIndex(String key)
Returns the maximum defined index for the given key.
|
Object |
getProperty(String key)
Fetches the specified property.
|
HierarchicalConfiguration.Node |
getRoot()
Returns the root node of this hierarchical configuration.
|
ConfigurationNode |
getRootNode()
Returns the root node of this hierarchical configuration.
|
Configuration |
interpolatedConfiguration()
Returns a configuration with the same content as this configuration, but
with all variables replaced by their actual values.
|
boolean |
isEmpty()
Checks if this configuration is empty.
|
protected boolean |
nodeDefined(ConfigurationNode node)
Checks if the specified node is defined.
|
protected boolean |
nodeDefined(HierarchicalConfiguration.Node node)
Deprecated.
Use the method
instead. |
protected void |
removeNode(ConfigurationNode node)
Removes the specified node from this configuration.
|
protected void |
removeNode(HierarchicalConfiguration.Node node)
Deprecated.
Use the method
instead. |
static void |
setDefaultExpressionEngine(ExpressionEngine engine)
Sets the default expression engine.
|
void |
setExpressionEngine(ExpressionEngine expressionEngine)
Sets the expression engine to be used by this configuration.
|
void |
setProperty(String key,
Object value)
Sets the value of the specified property.
|
void |
setRoot(HierarchicalConfiguration.Node node)
Sets the root node of this hierarchical configuration.
|
void |
setRootNode(ConfigurationNode rootNode)
Sets the root node of this hierarchical configuration.
|
protected void |
subnodeConfigurationChanged(ConfigurationEvent event)
This method is always called when a subnode configuration created from
this configuration has been modified.
|
Configuration |
subset(String prefix)
Creates a new
Configuration object containing all keys
that start with the specified prefix. |
addErrorLogListener, addProperty, append, clear, clearPropertyDirect, copy, createInterpolator, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDefaultListDelimiter, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getList, getList, getListDelimiter, getLogger, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, getSubstitutor, interpolate, interpolate, interpolateHelper, isDelimiterParsingDisabled, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setDelimiterParsingDisabled, setListDelimiter, setLogger, setThrowExceptionOnMissing
addConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, createErrorEvent, createEvent, fireError, fireEvent, getConfigurationListeners, getErrorListeners, isDetailEvents, removeConfigurationListener, removeErrorListener, setDetailEvents
public static final int EVENT_CLEAR_TREE
public static final int EVENT_ADD_NODES
public static final int EVENT_SUBNODE_CHANGED
public HierarchicalConfiguration()
HierarchicalConfiguration
.public HierarchicalConfiguration(HierarchicalConfiguration c)
HierarchicalConfiguration
and
copies all data contained in the specified configuration into the new
one.c
- the configuration that is to be copied (if null, this
constructor will behave like the standard constructor)public HierarchicalConfiguration.Node getRoot()
getRootNode()
method instead, which operates on
the preferred data type ConfigurationNode
.public void setRoot(HierarchicalConfiguration.Node node)
setRootNode(ConfigurationNode)
method instead,
which operates on the preferred data type ConfigurationNode
.node
- the root nodepublic ConfigurationNode getRootNode()
public void setRootNode(ConfigurationNode rootNode)
rootNode
- the root nodepublic static ExpressionEngine getDefaultExpressionEngine()
public static void setDefaultExpressionEngine(ExpressionEngine engine)
engine
- the new default expression enginepublic ExpressionEngine getExpressionEngine()
public void setExpressionEngine(ExpressionEngine expressionEngine)
expressionEngine
- the new expression engine; can be null,
then the default expression engine will be usedpublic Object getProperty(String key)
getProperty
in interface Configuration
key
- the key to be looked upprotected void addPropertyDirect(String key, Object obj)
ExpressionEngine
, so the passed in key
must match the requirements of this implementation.addPropertyDirect
in class AbstractConfiguration
key
- the key of the new propertyobj
- the value of the new propertypublic void addNodes(String key, Collection nodes)
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 HierarchicalConfiguration
object to this object. (However be aware that a
ConfigurationNode
object can only belong to a single
configuration. So if nodes from one configuration are directly added to
another one using this method, the structure of the source configuration
will be broken. In this case you should clone the nodes to be added
before calling addNodes()
.) 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.key
- the key where the nodes are to be added; can be null ,
then they are added to the root nodenodes
- a collection with the Node
objects to be
addedpublic boolean isEmpty()
isEmpty
in interface Configuration
public Configuration subset(String prefix)
Configuration
object containing all keys
that start with the specified prefix. This implementation will return a
HierarchicalConfiguration
object 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 returned
Configuration
object is not connected to its source
configuration: updates on the source configuration are not reflected in
the subset and vice versa.subset
in interface Configuration
subset
in class AbstractConfiguration
prefix
- the prefix of the keys for the subsetSubsetConfiguration
public SubnodeConfiguration configurationAt(String key, boolean supportUpdates)
Returns a hierarchical subnode 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
method is that
subset(String)
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 subnode configurations and when they should be used.
With the supportUpdate
flag the behavior of the returned
SubnodeConfiguration
regarding updates of its parent
configuration can be determined. A subnode configuration operates on the
same nodes as its parent, so changes at one configuration are normally
directly visible for the other configuration. There are however changes
of the parent configuration, which are not recognized by the subnode
configuration per default. An example for this is a reload operation (for
file-based configurations): Here the complete node set of the parent
configuration is replaced, but the subnode configuration still references
the old nodes. If such changes should be detected by the subnode
configuration, the supportUpdates
flag must be set to
true. This causes the subnode configuration to reevaluate the key
used for its creation each time it is accessed. This guarantees that the
subnode configuration always stays in sync with its key, even if the
parent configuration's data significantly changes. If such a change
makes the key invalid - because it now no longer points to exactly one
node -, the subnode configuration is not reconstructed, but keeps its
old data. It is then quasi detached from its parent.
key
- the key that selects the sub treesupportUpdates
- a flag whether the returned subnode configuration
should be able to handle updates of its parentSubnodeConfiguration
public SubnodeConfiguration configurationAt(String key)
configurationAt(key,
false)
.key
- the key that selects the sub treeSubnodeConfiguration
public List configurationsAt(String key)
ExpressionEngine
) and then create a subnode
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();) { HierarchicalConfiguration sub = (HierarchicalConfiguration) 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"); ...
key
- the key for selecting the desired nodesprotected SubnodeConfiguration createSubnodeConfiguration(ConfigurationNode node)
configurationAt()
and
configurationsAt()
.node
- the node, for which a subnode configuration is to be createdprotected SubnodeConfiguration createSubnodeConfiguration(ConfigurationNode node, String subnodeKey)
node
- the node, for which a subnode configuration is to be createdsubnodeKey
- the key used to construct the configurationprotected void subnodeConfigurationChanged(ConfigurationEvent event)
EVENT_SUBNODE_CHANGED
and notifies the registered listeners.event
- the event describing the changepublic boolean containsKey(String key)
containsKey
in interface Configuration
key
- the key to be chekcedpublic void setProperty(String key, Object value)
setProperty
in interface Configuration
setProperty
in class AbstractConfiguration
key
- the key of the property to setvalue
- the new value of this propertypublic void clearTree(String key)
clearTree("foo")
would remove both properties.key
- the key of the property to be removedpublic void clearProperty(String key)
clearProperty
in interface Configuration
clearProperty
in class AbstractConfiguration
key
- the key of the property to be removedpublic Iterator getKeys()
getKeys
in interface Configuration
public Iterator getKeys(String prefix)
getKeys
in interface Configuration
getKeys
in class AbstractConfiguration
prefix
- the prefix of the keys to start withConfiguration.getKeys()
public int getMaxIndex(String key)
key
- the key to be checkedpublic Object clone()
clone
in class EventSource
public Configuration interpolatedConfiguration()
interpolatedConfiguration
in class AbstractConfiguration
protected List fetchNodeList(String key)
key
- the keyprotected void findPropertyNodes(ConfigurationKey.KeyIterator keyPart, HierarchicalConfiguration.Node node, Collection nodes)
ExpressionEngine
implementation.keyPart
- the configuration key iteratornode
- the actual nodenodes
- here the found nodes are storedprotected boolean nodeDefined(HierarchicalConfiguration.Node node)
nodeDefined(ConfigurationNode)
instead.node
- the node to be checkedprotected boolean nodeDefined(ConfigurationNode node)
node
- the node to be checkedprotected void removeNode(HierarchicalConfiguration.Node node)
removeNode(ConfigurationNode)
instead.node
- the node to be removedprotected void removeNode(ConfigurationNode node)
node
- the node to be removedprotected void clearNode(HierarchicalConfiguration.Node node)
clearNode(ConfigurationNode)
insteadnode
- the node to be clearedprotected void clearNode(ConfigurationNode node)
node
- the node to be clearedprotected HierarchicalConfiguration.Node fetchAddNode(ConfigurationKey.KeyIterator keyIt, HierarchicalConfiguration.Node startNode)
ExpressionEngine
associated with this configuration instance.
This method will no longer be called. Developers who want to modify the
process of adding new properties should consider implementing their own
expression engine.keyIt
- the iterator for the key of the new propertystartNode
- the node to start the search withprotected HierarchicalConfiguration.Node findLastPathNode(ConfigurationKey.KeyIterator keyIt, HierarchicalConfiguration.Node node)
ExpressionEngine
associated with this configuration instance.
This method will no longer be called. Developers who want to modify the
process of adding new properties should consider implementing their own
expression engine.keyIt
- the key iteratornode
- the actual nodeprotected HierarchicalConfiguration.Node createAddPath(ConfigurationKey.KeyIterator keyIt, HierarchicalConfiguration.Node root)
ExpressionEngine
associated with this configuration instance.
This method will no longer be called. Developers who want to modify the
process of adding new properties should consider implementing their own
expression engine.keyIt
- the key iteratorroot
- the base node of the path to be createdprotected HierarchicalConfiguration.Node createNode(String name)
Node
object with the specified name. This
method can be overloaded in derived classes if a specific node type is
needed. This base implementation always returns a new object of the
Node
class.name
- the name of the new nodeprotected static void clearReferences(ConfigurationNode node)
node
- the root node of the node hierarchy, in which the references
are to be clearedCopyright © 2018 JBoss by Red Hat. All rights reserved.