org.apache.avalon.framework.configuration
public interface Configuration
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.
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.
Since version 4.1, each Configuration
node has a namespace
associated with it, in the form of a string, accessible through Configuration. If no namespace is present, getNamespace
will
return blank (""). See DefaultConfigurationBuilder for details on how
XML namespaces are mapped to Configuration
namespaces.
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
DefaultConfigurationBuilder#DefaultConfigurationBuilder(boolean) 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. () | my-system | |
conf. ().length
| 2 | 1 |
conf. ().length
| 2 | |
conf. ("version")
| 1.3 | |
conf. ("widget").getAttribute ("name")
| fooWidget | |
conf. ("widget")
.getAttributeAsBoolean ("threadsafe") |
true | |
conf. ("widget").getLocation ()
| file:///home/jeff/tmp/java/avalon/src/java/new.xconf:4:60 | |
conf. ("desc").getName ()
| desc (see getChild) | desc |
conf. ("doc:desc").getName ()
| doc:desc | doc:desc (see getChild) |
conf. ("desc").getValue ()
| ConfigurationException | This is a highly fictitious config file |
conf. ("doc:desc").getValue ()
| This is a highly fictitious config file | ConfigurationException |
conf. ("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
.
Currently, the configuration tree can only be traversed one node at a time,
eg., through getChild("foo")
or Configuration. 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. }
Version: $Id: Configuration.java 156533 2005-03-08 08:51:40 -0600 (Tue, 08 Mar 2005) leif $
Method Summary | |
---|---|
String | getAttribute(String paramName)
Return the value of specified attribute.
|
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.
|
boolean | getAttributeAsBoolean(String paramName)
Return the boolean value of the specified parameter contained
in this node.
|
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.
|
double | getAttributeAsDouble(String paramName)
Return the double value of the specified parameter contained
in this node.
|
double | getAttributeAsDouble(String name, double defaultValue)
Returns the value of the attribute specified by its name as a
double , or the default value if no attribute by
that name exists or is empty.
|
float | getAttributeAsFloat(String paramName)
Return the float value of the specified parameter contained
in this node.
|
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.
|
int | getAttributeAsInteger(String paramName)
Return the int value of the specified attribute contained
in this node.
|
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.
|
long | getAttributeAsLong(String name)
Returns the value of the attribute specified by its name as a
long .
|
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.
|
String[] | getAttributeNames()
Return an array of all attribute names.
|
Configuration | getChild(String child)
Return a new Configuration instance encapsulating the
specified child node.
|
Configuration | getChild(String child, boolean createNew)
Return a Configuration instance encapsulating the specified
child node.
|
Configuration[] | getChildren()
Return an Array of Configuration
elements containing all node children. |
Configuration[] | getChildren(String name)
Return an Array of Configuration
elements containing all node children with the specified name. |
String | getLocation()
Return a string describing location of Configuration.
|
String | getName()
Return the name of the node.
|
String | getNamespace()
Returns a string indicating which namespace this Configuration node
belongs to.
|
String | getValue()
Return the String value of the node.
|
String | getValue(String defaultValue)
Returns the value of the configuration element as a String .
|
boolean | getValueAsBoolean()
Return the boolean value of the node.
|
boolean | getValueAsBoolean(boolean defaultValue)
Returns the value of the configuration element as a boolean .
|
double | getValueAsDouble()
Return the double value of the node.
|
double | getValueAsDouble(double defaultValue)
Returns the value of the configuration element as a double .
|
float | getValueAsFloat()
Return the float value of the node.
|
float | getValueAsFloat(float defaultValue)
Returns the value of the configuration element as a float .
|
int | getValueAsInteger()
Return the int value of the node.
|
int | getValueAsInteger(int defaultValue)
Returns the value of the configuration element as an int .
|
long | getValueAsLong()
Return the long value of the node.
|
long | getValueAsLong(long defaultValue)
Returns the value of the configuration element as a long .
|
Parameters: paramName The name of the parameter you ask the value of.
Returns: String value of attribute.
Throws: ConfigurationException If no attribute with that name exists.
String
, or the default value if no attribute by
that name exists or is empty.
Parameters: name The name of the attribute you ask the value of. defaultValue The default value desired.
Returns: String value of attribute. It will return the default value if the named attribute does not exist, or if the value is not set.
boolean
value of the specified parameter contained
in this node.
Parameters: paramName The name of the parameter you ask the value of.
Returns: boolean value of attribute
Throws: ConfigurationException If no parameter with that name exists.
or if conversion to boolean
fails.
boolean
, or the default value if no attribute by
that name exists or is empty.
Parameters: name The name of the attribute you ask the value of. defaultValue The default value desired.
Returns: boolean value of attribute. It will return the default value if the named attribute does not exist, or if the value is not set.
double
value of the specified parameter contained
in this node.
Parameters: paramName The name of the parameter you ask the value of.
Returns: double value of attribute
Throws: ConfigurationException If no parameter with that name exists.
or if conversion to double
fails.
double
, or the default value if no attribute by
that name exists or is empty.
Parameters: name The name of the attribute you ask the value of. defaultValue The default value desired.
Returns: float value of attribute. It will return the default value if the named attribute does not exist, or if the value is not set.
float
value of the specified parameter contained
in this node.
Parameters: paramName The name of the parameter you ask the value of.
Returns: float value of attribute
Throws: ConfigurationException If no parameter with that name exists.
or if conversion to float
fails.
float
, or the default value if no attribute by
that name exists or is empty.
Parameters: name The name of the attribute you ask the value of. defaultValue The default value desired.
Returns: float value of attribute. It will return the default value if the named attribute does not exist, or if the value is not set.
int
value of the specified attribute contained
in this node.
Parameters: paramName The name of the parameter you ask the value of.
Returns: int value of attribute
Throws: ConfigurationException If no parameter with that name exists.
or if conversion to int
fails.
int
, or the default value if no attribute by
that name exists or is empty.
Parameters: name The name of the attribute you ask the value of. defaultValue The default value desired.
Returns: int value of attribute. It will return the default value if the named attribute does not exist, or if the value is not set.
long
.
Parameters: name The name of the parameter you ask the value of.
Returns: long value of attribute
Throws: ConfigurationException If no parameter with that name exists.
or if conversion to long
fails.
long
, or the default value if no attribute by
that name exists or is empty.
Parameters: name The name of the attribute you ask the value of. defaultValue The default value desired.
Returns: long value of attribute. It will return the default value if the named attribute does not exist, or if the value is not set.
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.
Returns: a String[]
value
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").
("default");
getValue
If you wish to get a null
return when no element is present,
use getChild("foo", false)
.
Parameters: child The name of the child node.
Returns: Configuration
Configuration
instance encapsulating the specified
child node.
Parameters: 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.
Returns: Configuration
Array
of Configuration
elements containing all node children. The array order will reflect the
order in the source config file.
Returns: All child nodes
Array
of Configuration
elements containing all node children with the specified name. The array
order will reflect the order in the source config file.
Parameters: name The name of the children to get.
Returns: The child nodes with name name
Returns: a string describing location of Configuration
Returns: name of the Configuration
node.
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".
Returns: a String identifying the namespace of this Configuration.
Throws: ConfigurationException if an error occurs
Since: 4.1
String
value of the node.
Returns: the value of the node.
Throws: ConfigurationException if an error occurs
String
.
If the configuration value is not set, the default value will be
used.
Parameters: defaultValue The default value desired.
Returns: String value of the Configuration
, or default
if none specified.
boolean
value of the node.
Returns: the value of the node.
Throws: ConfigurationException If conversion to boolean
fails.
boolean
.
If the configuration value is not set, the default value will be
used.
Parameters: defaultValue The default value desired.
Returns: boolean value of the Configuration
, or default
if none specified.
double
value of the node.
Returns: the value of the node.
Throws: ConfigurationException If conversion to double
fails.
double
.
If the configuration value is not set, the default value will be
used.
Parameters: defaultValue The default value desired.
Returns: float value of the Configuration
, or default
if none specified.
float
value of the node.
Returns: the value of the node.
Throws: ConfigurationException If conversion to float
fails.
float
.
If the configuration value is not set, the default value will be
used.
Parameters: defaultValue The default value desired.
Returns: float value of the Configuration
, or default
if none specified.
int
value of the node.
Returns: the value of the node.
Throws: ConfigurationException If conversion to int
fails.
int
.
If the configuration value is not set, the default value will be
used.
Parameters: defaultValue The default value desired.
Returns: int value of the Configuration
, or default
if none specified.
long
value of the node.
Returns: the value of the node.
Throws: ConfigurationException If conversion to long
fails.
long
.
If the configuration value is not set, the default value will be
used.
Parameters: defaultValue The default value desired.
Returns: long value of the Configuration
, or default
if none specified.