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,
Configuration
s 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
Configuration
s (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.