org.extex.framework.configuration
Interface Configuration

All Superinterfaces:
java.lang.Iterable<Configuration>
All Known Implementing Classes:
MultiConfiguration, TexConfiguration, XmlConfiguration

public interface Configuration
extends java.lang.Iterable<Configuration>

This is the interface for the configuration engine.

The configuration of a piece of software is in general independent of the way the configuration information is stored. Only a few methods are required to describe all features needed.

This interface is independent from the external representation of the configuration information. This means that the configuration information can be stored in an XML file, a properties file, a database, or even be hard-coded in the source of an implementation.

For the illustration the external representation as a special form of XML is used. The following example illustrates an XML configuration file.

   <?xml version="1.0" encoding="ISO-8859-1"?>
   <cfg>
     . . .
     <abc>
     . . .
     </abc>
     . . .
   </cfg>
 

Version:
$Revision: 6802 $
Author:
Gerd Neugebauer

Method Summary
 Configuration findConfiguration(java.lang.String key)
          Extract a sub-configuration with a given name.
 Configuration findConfiguration(java.lang.String key, java.lang.String attribute)
          Extract a sub-configuration with a given name and a given attribute.
 java.lang.String getAttribute(java.lang.String name)
          Getter for an attribute with a given name.
 Configuration getConfiguration(java.lang.String key)
          Extract a sub-configuration with a given name.
 Configuration getConfiguration(java.lang.String key, java.lang.String attribute)
          Extract a sub-configuration with a given name and a given attribute.
 java.lang.String getValue()
          Getter for the textual value of this configuration.
 java.lang.String getValue(java.lang.String key)
          Retrieve a value from the configuration as String.
 int getValueAsInteger(java.lang.String key, int defaultValue)
          Retrieve a value from the configuration as int.
 void getValues(java.util.List<java.lang.String> list, java.lang.String key)
          Get the list of all values with the given tag name in the current configuration and append them to a given String List.
 java.util.List<java.lang.String> getValues(java.lang.String key)
          Get the list of all values with the given tag name in the current configuration.
 java.util.Iterator<Configuration> iterator()
          Get an iterator for all sub-configurations.
 java.util.Iterator<Configuration> iterator(java.lang.String key)
          Retrieve an iterator over all items of a sub-configuration.
 void setConfigurationLoader(ConfigurationLoader loader)
          Sets a loader for new external sources.
 

Method Detail

findConfiguration

Configuration findConfiguration(java.lang.String key)
                                throws ConfigurationInvalidResourceException,
                                       ConfigurationNotFoundException,
                                       ConfigurationSyntaxException,
                                       ConfigurationIOException
Extract a sub-configuration with a given name.

Consider the following example with the configuration currently rooted at cfg:

   <cfg>
     . . .
     <abc>
     . . .
     </abc>
     . . .
   </cfg>
 

Then getConfig("abc") returns a new XMLConfig rooted at abc.

If there are more than one tags with the same name then the first one is used.

If there are no tags with the given name then null is returned.

Parameters:
key - the tag name of the sub-configuration
Returns:
the sub-configuration or null if none is found
Throws:
ConfigurationInvalidResourceException - in case that the given resource name is null or empty
ConfigurationNotFoundException - in case that the named path does not lead to a resource
ConfigurationSyntaxException - in case that the resource contains syntax errors
ConfigurationIOException - in case of an IO exception while reading the resource

findConfiguration

Configuration findConfiguration(java.lang.String key,
                                java.lang.String attribute)
                                throws ConfigurationException
Extract a sub-configuration with a given name and a given attribute.

Consider the following example with the configuration currently rooted at cfg:

   <cfg>
     . . .
     <abc name="one">
     . . .
     </abc>
     <abc name="two">
     . . .
     </abc>
     . . .
   </cfg>
 

Then getConfig("abc","two") returns a new XMLConfig rooted at the abc with the name attribute "two".

If there are more than one tags with the same name then the first one is used.

If there are no tags with the given name then null is returned.

Parameters:
key - the tag name of the sub-configuration
attribute - the value of the attribute name
Returns:
the sub-configuration
Throws:
ConfigurationException - in case of other errors.

getAttribute

java.lang.String getAttribute(java.lang.String name)
Getter for an attribute with a given name.

Parameters:
name - the tag name of the attribute
Returns:
the value of the attribute or null if such an attribute is not present

getConfiguration

Configuration getConfiguration(java.lang.String key)
                               throws ConfigurationException
Extract a sub-configuration with a given name.

Consider the following example with the configuration currently rooted at cfg:

   <cfg>
     . . .
     <abc>
     . . .
     </abc>
     . . .
   </cfg>
 

Then getConfig("abc") returns a new XMLConfig rooted at abc.

If there are more than one tags with the same name then the first one is used.

If there are no tags with the given name then an exception is thrown.

Parameters:
key - the tag name of the sub-configuration
Returns:
the sub-configuration
Throws:
ConfigurationException - in case of other errors. Especially
ConfigurationNotFoundException in case that the given name does not correspond to one of the tags in the current configuration

getConfiguration

Configuration getConfiguration(java.lang.String key,
                               java.lang.String attribute)
                               throws ConfigurationException
Extract a sub-configuration with a given name and a given attribute.

Consider the following example with the configuration currently rooted at cfg:

   <cfg>
     . . .
     <abc name="one">
     . . .
     </abc>
     <abc name="two">
     . . .
     </abc>
     . . .
   </cfg>
 

Then getConfig("abc","two") returns a new Configuration rooted at the abc with the name attribute "two".

If there are more than one tags with the same name then the first one is used.

If there are no tags with the given name then an exception is thrown.

Parameters:
key - the tag name of the sub-configuration
attribute - the value of the attribute name
Returns:
the sub-configuration
Throws:
ConfigurationException - in case of other errors. Especially
ConfigurationNotFoundException in case that the given name does not correspond to one of the tags in the current configuration

getValue

java.lang.String getValue()
                          throws ConfigurationException
Getter for the textual value of this configuration.

Returns:
the text stored directly in this configuration
Throws:
ConfigurationException - in case that something went wrong

getValue

java.lang.String getValue(java.lang.String key)
                          throws ConfigurationException
Retrieve a value from the configuration as String. If the value could not be determined then the empty string is returned.

Consider the following example with the configuration currently rooted at cfg:

   <cfg>
     . . .
     <one>the first value</one>
     <two>the second value</two>
     . . .
   </cfg>
 

Then getValue("two") returns the String "the second value".

Parameters:
key - the name of the desired value
Returns:
the value of key or null
Throws:
ConfigurationException - in case that something went wrong

getValueAsInteger

int getValueAsInteger(java.lang.String key,
                      int defaultValue)
                      throws ConfigurationException
Retrieve a value from the configuration as int. If the value could not be determined then a given default value is returned.

Parameters:
key - the name of the desired value
defaultValue - the default value
Returns:
the value of key or the default value
Throws:
ConfigurationException - in case that something went wrong

getValues

java.util.List<java.lang.String> getValues(java.lang.String key)
Get the list of all values with the given tag name in the current configuration.

Parameters:
key - the name of the tags
Returns:
the list of values

getValues

void getValues(java.util.List<java.lang.String> list,
               java.lang.String key)
Get the list of all values with the given tag name in the current configuration and append them to a given String List.

Parameters:
key - the name of the tags. A value of null is legal. I this case nothing is appended.
list - the list to append the values to
Throws:
java.lang.IllegalArgumentException - in case that list is null

iterator

java.util.Iterator<Configuration> iterator()
                                           throws ConfigurationException
Get an iterator for all sub-configurations.

Specified by:
iterator in interface java.lang.Iterable<Configuration>
Returns:
an iterator for all sub-configurations
Throws:
ConfigurationException - in case that something went wrong

iterator

java.util.Iterator<Configuration> iterator(java.lang.String key)
                                           throws ConfigurationException
Retrieve an iterator over all items of a sub-configuration.

Parameters:
key - the name of the sub-configuration
Returns:
the iterator
Throws:
ConfigurationException - in case that something went wrong

setConfigurationLoader

void setConfigurationLoader(ConfigurationLoader loader)
Sets a loader for new external sources.

Parameters:
loader - the loader