Configuration is a interface encapsulating a configuration node
used to retrieve configuration values.
This is a "read only" interface preventing applications from modifying their
own configurations. Once it is created, the information never changes.
Data Model
The data model is a subset of XML's; a single-rooted hierarchical tree where each
node can contain multiple
attributes, and leaf nodes can also
contain a
value. Reflecting this,
Configurations are
usually built from an XML file by the
DefaultConfigurationBuilder
class, or directly by a SAX parser using a
SAXConfigurationHandler or
NamespacedSAXConfigurationHandler event handler.
Namespace support
Since version 4.1, each
Configuration node has a namespace
associated with it, in the form of a string, accessible through
getNamespace(). If no namespace is present,
getNamespace will
return blank (""). See
DefaultConfigurationBuilder for details on how
XML namespaces are mapped to
Configuration namespaces.
Example
As an example, consider two
Configurations (with and without
namespaces) built from this XML:
<my-system version="1.3" xmlns:doc="http://myco.com/documentation">
<doc:desc>This is a highly fictitious config file</doc:desc>
<widget name="fooWidget" initOrder="1" threadsafe="true"/>
</my-system>
If namespace support is enabled (eg through
new
DefaultConfigurationBuilder(true)), then the
xmlns:doc element
will not translate into a Configuration attribute, and the
doc:desc element will become a
Configuration node
with name "desc" and namespace "http://myco.com/documentation". The
widget element will have namespace "".
If namespace support is disabled (the default for
DefaultConfigurationBuilder), the above XML will translate directly to
Configuration nodes. The
my-system node will have
an attribute named "xmlns:doc", and a child called "doc:desc".
Assuming the
Configuration object is named
conf,
here is how the data could be retrieved:
| Code | No namespaces | With namespaces |
|---|
conf.getName() | my-system |
conf.getAttributeNames().length
| 2 | 1 |
conf.getChildren().length
| 2 |
conf.getAttributeAsFloat("version")
| 1.3 |
conf.getChild("widget").getAttribute("name")
| fooWidget |
conf.getChild("widget")
.getAttributeAsBoolean("threadsafe") |
true |
conf.getChild("widget").getLocation()
| file:///home/jeff/tmp/java/avalon/src/java/new.xconf:4:60 |
conf.getChild("desc").getName()
| desc (see getChild(String)) | desc |
conf.getChild("doc:desc").getName()
| doc:desc | doc:desc (see getChild(String)) |
conf.getChild("desc").getValue()
| ConfigurationException | This is a highly fictitious config file |
conf.getChild("doc:desc").getValue()
| This is a highly fictitious config file | ConfigurationException |
conf.getChild("desc").getNamespace()
| | http://myco.com/documentation" |
Type-safe utility methods are provided for retrieving attribute and element
values as
String,
int,
long,
float and
boolean.
Miscellanea
Currently, the configuration tree can only be traversed one node at a time,
eg., through
getChild("foo") or
getChildren. In
a future release, it may be possible to access child nodes with an XPath-like
syntax.
Checking for the existence of an attribute can be done as follows:
String value = conf.getAttribute( "myAttribute", null );
if ( null == value )
{
// Do the processing applicable if the attribute isn't present.
}
getAttribute
public String getAttribute(String paramName)
throws ConfigurationException Return the value of specified attribute.
paramName - The name of the parameter you ask the value of.
- String value of attribute.
getAttribute
public String getAttribute(String name,
String defaultValue) Returns the value of the attribute specified by its name as a
String, or the default value if no attribute by
that name exists or is empty.
name - The name of the attribute you ask the value of.defaultValue - The default value desired.
- String value of attribute. It will return the default
value if the named attribute does not exist, or if
the value is not set.
getAttributeAsBoolean
public boolean getAttributeAsBoolean(String paramName)
throws ConfigurationException Return the boolean value of the specified parameter contained
in this node.
paramName - The name of the parameter you ask the value of.
- boolean value of attribute
getAttributeAsBoolean
public boolean getAttributeAsBoolean(String name,
boolean defaultValue) Returns the value of the attribute specified by its name as a
boolean, or the default value if no attribute by
that name exists or is empty.
name - The name of the attribute you ask the value of.defaultValue - The default value desired.
- boolean value of attribute. It will return the default
value if the named attribute does not exist, or if
the value is not set.
getAttributeAsFloat
public float getAttributeAsFloat(String paramName)
throws ConfigurationException Return the float value of the specified parameter contained
in this node.
paramName - The name of the parameter you ask the value of.
getAttributeAsFloat
public float getAttributeAsFloat(String name,
float defaultValue) Returns the value of the attribute specified by its name as a
float, or the default value if no attribute by
that name exists or is empty.
name - The name of the attribute you ask the value of.defaultValue - The default value desired.
- float value of attribute. It will return the default
value if the named attribute does not exist, or if
the value is not set.
getAttributeAsInteger
public int getAttributeAsInteger(String paramName)
throws ConfigurationException Return the int value of the specified attribute contained
in this node.
paramName - The name of the parameter you ask the value of.
getAttributeAsInteger
public int getAttributeAsInteger(String name,
int defaultValue) Returns the value of the attribute specified by its name as a
int, or the default value if no attribute by
that name exists or is empty.
name - The name of the attribute you ask the value of.defaultValue - The default value desired.
- int value of attribute. It will return the default
value if the named attribute does not exist, or if
the value is not set.
getAttributeAsLong
public long getAttributeAsLong(String name)
throws ConfigurationException Returns the value of the attribute specified by its name as a
long.
name - The name of the parameter you ask the value of.
getAttributeAsLong
public long getAttributeAsLong(String name,
long defaultValue) Returns the value of the attribute specified by its name as a
long, or the default value if no attribute by
that name exists or is empty.
name - The name of the attribute you ask the value of.defaultValue - The default value desired.
- long value of attribute. It will return the default
value if the named attribute does not exist, or if
the value is not set.
getAttributeNames
public String[] getAttributeNames()
Return an array of all attribute names.
The order of attributes in this array can not be relied on. As
with XML, a
Configuration's attributes are an
unordered set. If your code relies on order, eg
conf.getAttributeNames()[0], then it is liable to break if a
different XML parser is used.
getChild
public Configuration getChild(String child)
Return a new
Configuration instance encapsulating the
specified child node.
If no such child node exists, an empty
Configuration will be
returned, allowing constructs such as
conf.getChild("foo").getChild("bar").getChild("baz").getValue("default");
If you wish to get a
null return when no element is present,
use
getChild("foo", false).
child - The name of the child node.
getChild
public Configuration getChild(String child,
boolean createNew) Return a Configuration instance encapsulating the specified
child node.
child - The name of the child node.createNew - If true, a new Configuration
will be created and returned if the specified child does not exist. If
false, null will be returned when the specified
child doesn't exist.
getChildren
public Configuration[] getChildren()
Return an Array of Configuration
elements containing all node children. The array order will reflect the
order in the source config file.
getChildren
public Configuration[] getChildren(String name)
Return an Array of Configuration
elements containing all node children with the specified name. The array
order will reflect the order in the source config file.
name - The name of the children to get.
- The child nodes with name
name
getLocation
public String getLocation()
Return a string describing location of Configuration.
Location can be different for different mediums (ie "file:line" for normal XML files or
"table:primary-key" for DB based configurations);
- a string describing location of Configuration
getName
public String getName()
Return the name of the node.
- name of the
Configuration node.
getNamespace
public String getNamespace()
throws ConfigurationException Returns a string indicating which namespace this Configuration node
belongs to.
What this returns is dependent on the configuration file and the
Configuration builder. If the Configuration builder does not support
namespaces, this method will return a blank string.
In the case of
DefaultConfigurationBuilder, the namespace will
be the URI associated with the XML element. Eg.,:
<foo xmlns:x="http://blah.com">
<x:bar/>
</foo>
The namespace of
foo will be "", and the namespace of
bar will be "http://blah.com".
- a String identifying the namespace of this Configuration.
getValue
public String getValue()
throws ConfigurationException Return the String value of the node.
getValue
public String getValue(String defaultValue)
Returns the value of the configuration element as a String.
If the configuration value is not set, the default value will be
used.
defaultValue - The default value desired.
- String value of the
Configuration, or default
if none specified.
getValueAsBoolean
public boolean getValueAsBoolean()
throws ConfigurationException Return the boolean value of the node.
getValueAsBoolean
public boolean getValueAsBoolean(boolean defaultValue)
Returns the value of the configuration element as a boolean.
If the configuration value is not set, the default value will be
used.
defaultValue - The default value desired.
- boolean value of the
Configuration, or default
if none specified.
getValueAsFloat
public float getValueAsFloat()
throws ConfigurationException Return the float value of the node.
getValueAsFloat
public float getValueAsFloat(float defaultValue)
Returns the value of the configuration element as a float.
If the configuration value is not set, the default value will be
used.
defaultValue - The default value desired.
- float value of the
Configuration, or default
if none specified.
getValueAsInteger
public int getValueAsInteger()
throws ConfigurationException Return the int value of the node.
getValueAsInteger
public int getValueAsInteger(int defaultValue)
Returns the value of the configuration element as an int.
If the configuration value is not set, the default value will be
used.
defaultValue - The default value desired.
- int value of the
Configuration, or default
if none specified.
getValueAsLong
public long getValueAsLong()
throws ConfigurationException Return the long value of the node.
getValueAsLong
public long getValueAsLong(long defaultValue)
Returns the value of the configuration element as a long.
If the configuration value is not set, the default value will be
used.
defaultValue - The default value desired.
- long value of the
Configuration, or default
if none specified.