Interface Configuration
-
- All Known Implementing Classes:
AbstractConfiguration
,DefaultConfiguration
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.
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 theDefaultConfigurationBuilder
class, or directly by a SAX parser using aSAXConfigurationHandler
orNamespacedSAXConfigurationHandler
event handler.Namespace support
Since version 4.1, each
Configuration
node has a namespace associated with it, in the form of a string, accessible throughgetNamespace()
. If no namespace is present,getNamespace
will return blank (""). SeeDefaultConfigurationBuilder
for details on how XML namespaces are mapped toConfiguration
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 thexmlns:doc
element will not translate into a Configuration attribute, and thedoc:desc
element will become aConfiguration
node with name "desc" and namespace "http://myco.com/documentation". Thewidget
element will have namespace "".If namespace support is disabled (the default for
DefaultConfigurationBuilder
), the above XML will translate directly toConfiguration
nodes. Themy-system
node will have an attribute named "xmlns:doc", and a child called "doc:desc".Assuming the
Configuration
object is namedconf
, here is how the data could be retrieved:Code No namespaces With namespaces conf.
getName
()my-system conf.
getAttributeNames
().length2 1 conf.
getChildren
().length2 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
andboolean
.Miscellanea
Currently, the configuration tree can only be traversed one node at a time, eg., through
getChild("foo")
orgetChildren()
. 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:
- CVS $Revision: 1.27 $ $Date: 2003/02/11 15:58:38 $
- Author:
- Avalon Development Team
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description java.lang.String
getAttribute(java.lang.String paramName)
Return the value of specified attribute.java.lang.String
getAttribute(java.lang.String name, java.lang.String defaultValue)
Returns the value of the attribute specified by its name as aString
, or the default value if no attribute by that name exists or is empty.boolean
getAttributeAsBoolean(java.lang.String paramName)
Return theboolean
value of the specified parameter contained in this node.boolean
getAttributeAsBoolean(java.lang.String name, boolean defaultValue)
Returns the value of the attribute specified by its name as aboolean
, or the default value if no attribute by that name exists or is empty.float
getAttributeAsFloat(java.lang.String paramName)
Return thefloat
value of the specified parameter contained in this node.float
getAttributeAsFloat(java.lang.String name, float defaultValue)
Returns the value of the attribute specified by its name as afloat
, or the default value if no attribute by that name exists or is empty.int
getAttributeAsInteger(java.lang.String paramName)
Return theint
value of the specified attribute contained in this node.int
getAttributeAsInteger(java.lang.String name, int defaultValue)
Returns the value of the attribute specified by its name as aint
, or the default value if no attribute by that name exists or is empty.long
getAttributeAsLong(java.lang.String name)
Returns the value of the attribute specified by its name as along
.long
getAttributeAsLong(java.lang.String name, long defaultValue)
Returns the value of the attribute specified by its name as along
, or the default value if no attribute by that name exists or is empty.java.lang.String[]
getAttributeNames()
Return an array of all attribute names.Configuration
getChild(java.lang.String child)
Return a newConfiguration
instance encapsulating the specified child node.Configuration
getChild(java.lang.String child, boolean createNew)
Return aConfiguration
instance encapsulating the specified child node.Configuration[]
getChildren()
Return anArray
ofConfiguration
elements containing all node children.Configuration[]
getChildren(java.lang.String name)
Return anArray
ofConfiguration
elements containing all node children with the specified name.java.lang.String
getLocation()
Return a string describing location of Configuration.java.lang.String
getName()
Return the name of the node.java.lang.String
getNamespace()
Returns a string indicating which namespace this Configuration node belongs to.java.lang.String
getValue()
Return theString
value of the node.java.lang.String
getValue(java.lang.String defaultValue)
Returns the value of the configuration element as aString
.boolean
getValueAsBoolean()
Return theboolean
value of the node.boolean
getValueAsBoolean(boolean defaultValue)
Returns the value of the configuration element as aboolean
.float
getValueAsFloat()
Return thefloat
value of the node.float
getValueAsFloat(float defaultValue)
Returns the value of the configuration element as afloat
.int
getValueAsInteger()
Return theint
value of the node.int
getValueAsInteger(int defaultValue)
Returns the value of the configuration element as anint
.long
getValueAsLong()
Return thelong
value of the node.long
getValueAsLong(long defaultValue)
Returns the value of the configuration element as along
.
-
-
-
Method Detail
-
getName
java.lang.String getName()
Return the name of the node.- Returns:
- name of the
Configuration
node.
-
getLocation
java.lang.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);- Returns:
- a string describing location of Configuration
-
getNamespace
java.lang.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 ofbar
will be "http://blah.com".- Returns:
- a String identifying the namespace of this Configuration.
- Throws:
ConfigurationException
- if an error occurs- Since:
- 4.1
-
getChild
Configuration getChild(java.lang.String child)
Return a newConfiguration
instance encapsulating the specified child node.If no such child node exists, an empty
Configuration
will be returned, allowing constructs such asconf.getChild("foo").getChild("bar").getChild("baz").
getValue
("default");If you wish to get a
null
return when no element is present, usegetChild("foo", false)
.- Parameters:
child
- The name of the child node.- Returns:
- Configuration
-
getChild
Configuration getChild(java.lang.String child, boolean createNew)
Return aConfiguration
instance encapsulating the specified child node.- Parameters:
child
- The name of the child node.createNew
- Iftrue
, a newConfiguration
will be created and returned if the specified child does not exist. Iffalse
,null
will be returned when the specified child doesn't exist.- Returns:
- Configuration
-
getChildren
Configuration[] getChildren()
Return anArray
ofConfiguration
elements containing all node children. The array order will reflect the order in the source config file.- Returns:
- All child nodes
-
getChildren
Configuration[] getChildren(java.lang.String name)
Return anArray
ofConfiguration
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
-
getAttributeNames
java.lang.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.- Returns:
- a
String[]
value
-
getAttribute
java.lang.String getAttribute(java.lang.String paramName) throws ConfigurationException
Return the value of specified attribute.- 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.
-
getAttributeAsInteger
int getAttributeAsInteger(java.lang.String paramName) throws ConfigurationException
Return theint
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 toint
fails.
-
getAttributeAsLong
long getAttributeAsLong(java.lang.String name) throws ConfigurationException
Returns the value of the attribute specified by its name as along
.- 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 tolong
fails.
-
getAttributeAsFloat
float getAttributeAsFloat(java.lang.String paramName) throws ConfigurationException
Return thefloat
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 tofloat
fails.
-
getAttributeAsBoolean
boolean getAttributeAsBoolean(java.lang.String paramName) throws ConfigurationException
Return theboolean
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 toboolean
fails.
-
getValue
java.lang.String getValue() throws ConfigurationException
Return theString
value of the node.- Returns:
- the value of the node.
- Throws:
ConfigurationException
- if an error occurs
-
getValueAsInteger
int getValueAsInteger() throws ConfigurationException
Return theint
value of the node.- Returns:
- the value of the node.
- Throws:
ConfigurationException
- If conversion toint
fails.
-
getValueAsFloat
float getValueAsFloat() throws ConfigurationException
Return thefloat
value of the node.- Returns:
- the value of the node.
- Throws:
ConfigurationException
- If conversion tofloat
fails.
-
getValueAsBoolean
boolean getValueAsBoolean() throws ConfigurationException
Return theboolean
value of the node.- Returns:
- the value of the node.
- Throws:
ConfigurationException
- If conversion toboolean
fails.
-
getValueAsLong
long getValueAsLong() throws ConfigurationException
Return thelong
value of the node.- Returns:
- the value of the node.
- Throws:
ConfigurationException
- If conversion tolong
fails.
-
getValue
java.lang.String getValue(java.lang.String defaultValue)
Returns the value of the configuration element as aString
. 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.
-
getValueAsInteger
int getValueAsInteger(int defaultValue)
Returns the value of the configuration element as anint
. 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.
-
getValueAsLong
long getValueAsLong(long defaultValue)
Returns the value of the configuration element as along
. 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.
-
getValueAsFloat
float getValueAsFloat(float defaultValue)
Returns the value of the configuration element as afloat
. 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.
-
getValueAsBoolean
boolean getValueAsBoolean(boolean defaultValue)
Returns the value of the configuration element as aboolean
. 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.
-
getAttribute
java.lang.String getAttribute(java.lang.String name, java.lang.String defaultValue)
Returns the value of the attribute specified by its name as aString
, 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.
-
getAttributeAsInteger
int getAttributeAsInteger(java.lang.String name, int defaultValue)
Returns the value of the attribute specified by its name as aint
, 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.
-
getAttributeAsLong
long getAttributeAsLong(java.lang.String name, long defaultValue)
Returns the value of the attribute specified by its name as along
, 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.
-
getAttributeAsFloat
float getAttributeAsFloat(java.lang.String name, float defaultValue)
Returns the value of the attribute specified by its name as afloat
, 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.
-
getAttributeAsBoolean
boolean getAttributeAsBoolean(java.lang.String name, boolean defaultValue)
Returns the value of the attribute specified by its name as aboolean
, 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.
-
-