|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.apache.commons.configuration.event.EventSource org.apache.commons.configuration.AbstractConfiguration org.apache.commons.configuration.HierarchicalConfiguration
public class HierarchicalConfiguration
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. Similarily 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.
Nested Class Summary | |
---|---|
protected static class |
HierarchicalConfiguration.BuilderVisitor
A specialized visitor base class that can be used for storing the tree of configuration nodes. |
(package private) static class |
HierarchicalConfiguration.CloneVisitor
A specialized visitor that is able to create a deep copy of a node hierarchy. |
(package private) class |
HierarchicalConfiguration.DefinedKeysVisitor
A specialized visitor that fills a list with keys that are defined in a node hierarchy. |
(package private) static class |
HierarchicalConfiguration.DefinedVisitor
A specialized visitor that checks if a node is defined. |
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. |
Field Summary | |
---|---|
static int |
EVENT_ADD_NODES
Constant for the add nodes event. |
static int |
EVENT_CLEAR_TREE
Constant for the clear tree event. |
Fields inherited from class org.apache.commons.configuration.AbstractConfiguration |
---|
END_TOKEN, EVENT_ADD_PROPERTY, EVENT_CLEAR, EVENT_CLEAR_PROPERTY, EVENT_READ_PROPERTY, EVENT_SET_PROPERTY, START_TOKEN |
Constructor Summary | |
---|---|
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. |
Method Summary | |
---|---|
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 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 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. |
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. |
Configuration |
subset(String prefix)
Creates a new Configuration object containing all keys
that start with the specified prefix. |
Methods inherited from class org.apache.commons.configuration.event.EventSource |
---|
addConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, createErrorEvent, createEvent, fireError, fireEvent, getConfigurationListeners, getErrorListeners, isDetailEvents, removeConfigurationListener, removeErrorListener, setDetailEvents |
Methods inherited from class java.lang.Object |
---|
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final int EVENT_CLEAR_TREE
public static final int EVENT_ADD_NODES
Constructor Detail |
---|
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)Method Detail |
---|
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 up
protected 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. 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
isEmpty
in class AbstractConfiguration
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.
subset
in interface Configuration
subset
in class AbstractConfiguration
prefix
- the prefix of the keys for the subset
SubsetConfiguration
public SubnodeConfiguration configurationAt(String key)
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.
key
- the key that selects the sub tree
SubnodeConfiguration
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 nodes
protected SubnodeConfiguration createSubnodeConfiguration(ConfigurationNode node)
configurationAt()
and
configurationsAt()
.
node
- the node, for which a subnode configuration is to be created
public boolean containsKey(String key)
containsKey
in interface Configuration
containsKey
in class AbstractConfiguration
key
- the key to be chekced
public 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
getKeys
in class AbstractConfiguration
public Iterator getKeys(String prefix)
getKeys
in interface Configuration
getKeys
in class AbstractConfiguration
prefix
- the prefix of the keys to start with
Configuration.getKeys()
public int getMaxIndex(String key)
key
- the key to be checked
public Object clone()
clone
in class EventSource
protected List fetchNodeList(String key)
key
- the key
protected 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 checked
protected boolean nodeDefined(ConfigurationNode node)
node
- the node to be checked
protected 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)
instead
node
- the node to be cleardprotected void clearNode(ConfigurationNode node)
node
- the node to be cleardprotected 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 with
protected 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 node
protected 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 created
protected 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 node
protected static void clearReferences(ConfigurationNode node)
node
- the root node of the node hierarchy, in which the references
are to be cleared
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |