Package org.apache.avalon.framework.configuration

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

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

    CodeNo namespacesWith namespaces
    conf.getName()my-system
    conf.getAttributeNames().length 21
    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:descdoc:desc (see getChild(String))
    conf.getChild("desc").getValue() ConfigurationExceptionThis is a highly fictitious config file
    conf.getChild("doc:desc").getValue() This is a highly fictitious config fileConfigurationException
    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:
    $Id: Configuration.java 156533 2005-03-08 08:51:40 -0600 (Tue, 08 Mar 2005) leif $
    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 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.
      double getAttributeAsDouble​(java.lang.String paramName)
      Return the double value of the specified parameter contained in this node.
      double getAttributeAsDouble​(java.lang.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​(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.
      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.

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

        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

        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

        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

        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

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

        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

        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.

      • getAttributeAsDouble

        double getAttributeAsDouble​(java.lang.String paramName)
                     throws ConfigurationException
        Return the 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.

      • getAttributeAsBoolean

        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

        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

        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

        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

        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.

      • getValueAsDouble

        double getValueAsDouble​(double defaultValue)
        Returns the value of the configuration element as a 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.

      • getValueAsBoolean

        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

        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

        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

        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

        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.

      • getAttributeAsDouble

        double getAttributeAsDouble​(java.lang.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.
        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 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.