org.extex.framework.configuration.impl
Class XmlConfiguration

java.lang.Object
  org.extex.framework.configuration.impl.XmlConfiguration

All Implemented Interfaces:

java.lang.Iterable<Configuration>, Configuration

public class XmlConfiguration
extends java.lang.Object
implements Configuration

This class provides means to deal with configurations stored as XML files.

Version:

$Revision: 7137 $

Author:

Gerd Neugebauer

Field Summary

protected static long

serialVersionUID The constant serialVersionUID contains the id for serialization.

Constructor Summary

XmlConfiguration(java.io.InputStream stream, java.lang.String resource)
Creates a new object and fills it with the configuration read from an input stream.

XmlConfiguration(java.lang.String resource)
Creates a new object.

Method Summary

Configuration	findConfiguration(java.lang.String name) 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 name) 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 tag) Get the text value of the first tag with a given name in the configuration.
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 StringList.
java.util.List<java.lang.String>	getValues(java.lang.String tag) 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.
protected void	readConfiguration(java.io.InputStream stream, java.lang.String theResource, java.lang.String theBase) Read the configuration from a stream.
void	setConfigurationLoader(ConfigurationLoader loader) Sets a loader for new external sources.
protected Configuration	src(java.lang.String name, org.w3c.dom.Node node) Recursively follow the src attribute if present.
java.lang.String	toString() Get the printable representation of this configuration.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

serialVersionUID

protected static final long serialVersionUID

The constant serialVersionUID contains the id for serialization.

See Also:

Constant Field Values

Constructor Detail

XmlConfiguration

public XmlConfiguration(java.io.InputStream stream,
                        java.lang.String resource)
                 throws ConfigurationInvalidResourceException,
                        ConfigurationNotFoundException,
                        ConfigurationSyntaxException,
                        ConfigurationIOException

Creates a new object and fills it with the configuration read from an input stream.

The path given is the location of the XML resource (file) containing the configuration information. This path is used to determine the XML resource utilizing the class loader for this class. Thus it is possible to place the XML file into a jar archive.

Beside of the class loader a search is performed by appending .xml and/or prepending config/ if the path is not sufficient to find the resource.

Parameters:

stream - the stream to read the configuration from.

resource - the name of the resource to be used; i.e. something like the file name

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.

XmlConfiguration

public XmlConfiguration(java.lang.String resource)
                 throws ConfigurationInvalidResourceException,
                        ConfigurationNotFoundException,
                        ConfigurationSyntaxException,
                        ConfigurationIOException

Creates a new object.

The path given is the location of the XML file containing the configuration information. This path is used to determine the XML file utilizing the class loader for this class. Thus it is possible to place the XML file into a jar archive.

Beside of the class loader a search is performed by appending .xml and/or prepending config/ if the path is not sufficient to find the resource.

Example

Consider the following creation of an instance of this class

   cfg = new XmlConfiguration("cfg");
  

Then the following files are searched on the classpath until one is found:

     cfg   cfg.xml   config/cfg   config/cfg.xml
  

Parameters:

resource - the name of the resource to be used; i.e. the file name

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

Method Detail

findConfiguration

public Configuration findConfiguration(java.lang.String name)
                                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 findConfiguration("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.

Specified by:

findConfiguration in interface Configuration

Parameters:

name - the tag name of the sub-configuration

Returns:

the sub-configuration or null if none was 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

See Also:

getConfiguration(java.lang.String), Configuration.findConfiguration( java.lang.String)

findConfiguration

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

Specified by:

findConfiguration in interface Configuration

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

public java.lang.String getAttribute(java.lang.String name)

Description copied from interface: Configuration

Getter for an attribute with a given name.

Specified by:

getAttribute in interface Configuration

Parameters:

name - the tag name of the attribute

Returns:

the value of the attribute or null if such an attribute is not present

See Also:

Configuration.getAttribute( java.lang.String)

getConfiguration

public Configuration getConfiguration(java.lang.String name)
                               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 getConfiguration("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.

Specified by:

getConfiguration in interface Configuration

Parameters:

name - the tag name of the sub-configuration

Returns:

the sub-configuration

Throws:

ConfigurationNotFoundException - in case that the configuration does not exist.

ConfigurationIOException - in case that an IOException occurred while reading the configuration.

ConfigurationSyntaxException - in case of a syntax error in the configuration.

ConfigurationInvalidResourceException - in case that the given resource name is null or empty

See Also:

findConfiguration(String)

getConfiguration

public Configuration getConfiguration(java.lang.String key,
                                      java.lang.String attribute)
                               throws ConfigurationNotFoundException,
                                      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 an exception is thrown.

Specified by:

getConfiguration in interface Configuration

Parameters:

key - the tag name of the sub-configuration

attribute - the value of the attribute name

Returns:

the sub-configuration

Throws:

ConfigurationNotFoundException - in case that the given name does not correspond to one of the tags in the current configuration

ConfigurationException - in case of some other kind of error

getValue

public java.lang.String getValue()
                          throws ConfigurationException

Description copied from interface: Configuration

Getter for the textual value of this configuration.

Specified by:

getValue in interface Configuration

Returns:

the text stored directly in this configuration

Throws:

ConfigurationException - in case that something went wrong

See Also:

Configuration.getValue()

getValue

public java.lang.String getValue(java.lang.String tag)

Get the text value of the first tag with a given name in the configuration. If none is found 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".

Specified by:

getValue in interface Configuration

Parameters:

tag - the name of the tag

Returns:

the value of the tag or the empty string

getValueAsInteger

public int getValueAsInteger(java.lang.String key,
                             int defaultValue)
                      throws ConfigurationException

Description copied from interface: Configuration

Retrieve a value from the configuration as int. If the value could not be determined then a given default value is returned.

Specified by:

getValueAsInteger in interface Configuration

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

See Also:

Configuration.getValueAsInteger( java.lang.String, int)

getValues

public 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 StringList. Get the list of all values with the given tag name in the current configuration and append them to a given String List.

Specified by:

getValues in interface Configuration

Parameters:

list - the list to append the values to

key - the name of the tags. A value of null is legal. I this case nothing is appended.

See Also:

Configuration.getValues(java.util.List, java.lang.String)

getValues

public java.util.List<java.lang.String> getValues(java.lang.String tag)

Get the list of all values with the given tag name in the current configuration.

Specified by:

getValues in interface Configuration

Parameters:

tag - the name of the tags

Returns:

the list of values

See Also:

Configuration.getValues(java.lang.String)

iterator

public java.util.Iterator<Configuration> iterator()

Get an iterator for all sub-configurations.

Specified by:

iterator in interface java.lang.Iterable<Configuration>

Specified by:

iterator in interface Configuration

Returns:

an iterator for all sub-configurations

See Also:

Configuration.iterator()

iterator

public java.util.Iterator<Configuration> iterator(java.lang.String key)
                                           throws ConfigurationInvalidResourceException,
                                                  ConfigurationNotFoundException,
                                                  ConfigurationSyntaxException,
                                                  ConfigurationIOException

Retrieve an iterator over all items of a sub-configuration.

Specified by:

iterator in interface Configuration

Parameters:

key - the name of the sub-configuration

Returns:

the iterator

Throws:

ConfigurationIOException - in case that an IO exception occurs during the reading of the configuration.

ConfigurationSyntaxException - in case that the configuration contains a syntax error.

ConfigurationNotFoundException - in case that the specified configuration can not be found.

ConfigurationInvalidResourceException - in case that the resource is invalid

See Also:

Configuration.iterator(java.lang.String)

readConfiguration

protected void readConfiguration(java.io.InputStream stream,
                                 java.lang.String theResource,
                                 java.lang.String theBase)
                          throws ConfigurationNotFoundException,
                                 ConfigurationIOException,
                                 ConfigurationSyntaxException

Read the configuration from a stream.

Parameters:

stream - the stream to read the configuration from.

theResource - the name of the resource to be used; i.e. something like the file name

theBase - the new value for base

Throws:

ConfigurationNotFoundException - in case that the configuration could not be found

ConfigurationIOException - in case of an IO error during reading

ConfigurationSyntaxException - in case of a syntax error in the configuration XML

setConfigurationLoader

public void setConfigurationLoader(ConfigurationLoader loader)

Sets a loader for new external sources.

Specified by:

setConfigurationLoader in interface Configuration

Parameters:

loader - the loader

See Also:

Configuration.setConfigurationLoader( org.extex.framework.configuration.ConfigurationLoader)

src

protected Configuration src(java.lang.String name,
                            org.w3c.dom.Node node)
                     throws ConfigurationInvalidResourceException,
                            ConfigurationNotFoundException,
                            ConfigurationSyntaxException,
                            ConfigurationIOException

Recursively follow the src attribute if present.

Parameters:

name - the name of the current tag

node - the current DOM node

Returns:

the configuration

Throws:

ConfigurationInvalidResourceException - in case of an invalid resource

ConfigurationNotFoundException - in case of a missing configuration

ConfigurationSyntaxException - in case of an syntax error

ConfigurationIOException - in case of an IO error

toString

public java.lang.String toString()

Get the printable representation of this configuration. Something like an XPath expression describing the configuration is produced for this instance.

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()