Configuration (Avalon Framework API)
Keywords: org.apache.avalon.framework.configuration.Configuration interface

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.avalon.framework.configuration
Interface Configuration

All Known Subinterfaces:
  MutableConfiguration

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 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.
     }

Version:
  CVS $Revision: 1.29 $ $Date: 2004/02/11 14:34:24 $
Author:
  Avalon Development Team

Method Summary
`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 a `String`, or the default value if no attribute by that name exists or is empty.
`boolean` | `getAttributeAsBoolean(java.lang.String paramName)` Return the `boolean` 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 a `boolean`, or the default value if no attribute by that name exists or is empty.
`float` | `getAttributeAsFloat(java.lang.String paramName)` Return the `float` 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 a `float`, or the default value if no attribute by that name exists or is empty.
`int` | `getAttributeAsInteger(java.lang.String paramName)` Return the `int` 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 a `int`, 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 a `long`.
`long` | `getAttributeAsLong(java.lang.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.
`java.lang.String[]` | `getAttributeNames()` Return an array of all attribute names.
`Configuration` | `getChild(java.lang.String child)` Return a new `Configuration` instance encapsulating the specified child node.
`Configuration` | `getChild(java.lang.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(java.lang.String name)` Return an `Array` of `Configuration` 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 the `String` value of the node.
`java.lang.String` | `getValue(java.lang.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`.
`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`.

Method Detail

### getName

    public java.lang.String getName()

  Return the name of the node.

  Returns:
    name of the `Configuration` node.

### getLocation

    public 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

    public 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 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

### getChild

    public Configuration getChild(java.lang.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)`.

  Parameters:
    `child` - The name of the child node.
  Returns:
    Configuration

### getChild

    public Configuration getChild(java.lang.String child,
                                  boolean createNew)

  Return a `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

### 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.

  Returns:
    All child nodes

### getChildren

    public Configuration[] getChildren(java.lang.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.

  Parameters:
    `name` - The name of the children to get.
  Returns:
    The child nodes with name `name`

### getAttributeNames

    public 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

    public 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

    public int getAttributeAsInteger(java.lang.String paramName)
                              throws ConfigurationException

  Return the `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.

### getAttributeAsLong

    public long getAttributeAsLong(java.lang.String name)
                            throws ConfigurationException

  Returns the value of the attribute specified by its name as a `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.

### getAttributeAsFloat

    public float getAttributeAsFloat(java.lang.String paramName)
                              throws ConfigurationException

  Return the `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.

### getAttributeAsBoolean

    public boolean getAttributeAsBoolean(java.lang.String paramName)
                                  throws ConfigurationException

  Return the `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.

### getValue

    public java.lang.String getValue()
                              throws ConfigurationException

  Return the `String` value of the node.

  Returns:
    the value of the node.
  Throws:
    `ConfigurationException` - if an error occurs

### getValueAsInteger

    public int getValueAsInteger()
                          throws ConfigurationException

  Return the `int` value of the node.

  Returns:
    the value of the node.
  Throws:
    `ConfigurationException` - If conversion to `int` fails.

### getValueAsFloat

    public float getValueAsFloat()
                          throws ConfigurationException

  Return the `float` value of the node.

  Returns:
    the value of the node.
  Throws:
    `ConfigurationException` - If conversion to `float` fails.

### getValueAsBoolean

    public boolean getValueAsBoolean()
                              throws ConfigurationException

  Return the `boolean` value of the node.

  Returns:
    the value of the node.
  Throws:
    `ConfigurationException` - If conversion to `boolean` fails.

### getValueAsLong

    public long getValueAsLong()
                        throws ConfigurationException

  Return the `long` value of the node.

  Returns:
    the value of the node.
  Throws:
    `ConfigurationException` - If conversion to `long` fails.

### getValue

    public java.lang.String getValue(java.lang.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.

  Parameters:
    `defaultValue` - The default value desired.
  Returns:
    String value of the `Configuration`, or default if none specified.

### 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.

  Parameters:
    `defaultValue` - The default value desired.
  Returns:
    int value of the `Configuration`, or default if none specified.

### 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.

  Parameters:
    `defaultValue` - The default value desired.
  Returns:
    long value of the `Configuration`, or default if none specified.

### 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.

  Parameters:
    `defaultValue` - The default value desired.
  Returns:
    float value of the `Configuration`, or default if none specified.

### 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.

  Parameters:
    `defaultValue` - The default value desired.
  Returns:
    boolean value of the `Configuration`, or default if none specified.

### getAttribute

    public java.lang.String getAttribute(java.lang.String name,
                                         java.lang.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.

  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

    public int getAttributeAsInteger(java.lang.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.

  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

    public long getAttributeAsLong(java.lang.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.

  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

    public float getAttributeAsFloat(java.lang.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.

  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

    public boolean getAttributeAsBoolean(java.lang.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.

  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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © The Apache Software Foundation. All Rights Reserved.