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