org.apache.commons.configuration
Class ConfigurationXMLDocument

java.lang.Object
  org.apache.commons.configuration.ConfigurationXMLDocument

public class ConfigurationXMLDocument

extends Object

A helper class that supports XML-like processing for configuration objects.

This class provides a set of methods that all have something to do with treating a Configuration object as a XML document. So a configuration can be transformed into a Document (either dom4j or w3c), saved as an XML file or passed to Digester.

Implementation note: This class is not thread safe.

Version:

$Id: ConfigurationXMLDocument.java,v 1.4 2004/03/08 23:42:16 epugh Exp $

Author:

Oliver Heger

Field Summary

protected static String	ATTR_NAME Constant for the name attribute.
protected static String	ATTR_VALUE Constant for the value attribute.
protected static String	ELEM_CLASS Constant for the class element.
protected static String	ELEM_PROPERTY Constant for the property element.

Constructor Summary

ConfigurationXMLDocument(Configuration config)
Creates a new instance of ConfigurationXMLDocument and sets the configuration object to be processed.

Method Summary

Object	callDigester(String prefix) Creates and initializes an object specified in the configuration using Digester.
protected Digester	createDefaultDigester(String prefix) Creates the default Digester instance for the given prefix.
ConfigurationXMLReader	createXMLReader() Returns a XMLReader object for the actual configuration object.
static ConfigurationXMLReader	createXMLReader(Configuration config) Returns a XMLReader object for the specified configuration object.
ConfigurationXMLReader	createXMLReader(String prefix) Returns a ConfigurationXMLReader object for the subset configuration specified by the given prefix.
Configuration	getConfiguration() Returns the Configuration object for this document.
protected Digester	getDefaultDigester(String prefix) Returns a default Digester instance.
Document	getDocument() Transforms the wrapped configuration into a dom4j document.
Document	getDocument(String prefix) Transforms the wrapped configuration into a dom4j document.
Document	getDocument(String prefix, String rootName) Transforms the wrapped configuration into a dom4j document.
Document	getW3cDocument() Transforms the wrapped configuration into a w3c document.
Document	getW3cDocument(String prefix) Transforms the wrapped configuration into a w3c document.
Document	getW3cDocument(String prefix, String rootName) Transforms the wrapped configuration into a w3c document.
void	setConfiguration(Configuration configuration) Sets the Configuration object this document operates on.
protected void	setupDefaultDigester(Digester digester) Initializes the default digester instance used for simple object creation.
void	write(Writer out) Writes the wrapped configuration to the given writer.
void	write(Writer out, boolean pretty) Writes the wrapped configuration to the given writer.
void	write(Writer out, String prefix) Writes a configuration (or parts of it) to the given writer.
void	write(Writer out, String prefix, boolean pretty) Writes a configuration (or parts of it) to the given writer.
void	write(Writer out, String prefix, String root) Writes a configuration (or parts of it) to the given writer.
void	write(Writer out, String prefix, String root, boolean pretty) Writes a configuration (or parts of it) to the given writer.

Methods inherited from class java.lang.Object

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

Field Detail

ELEM_CLASS

protected static final String ELEM_CLASS

Constant for the class element.

See Also:

Constant Field Values

ELEM_PROPERTY

protected static final String ELEM_PROPERTY

Constant for the property element.

See Also:

Constant Field Values

ATTR_NAME

protected static final String ATTR_NAME

Constant for the name attribute.

See Also:

Constant Field Values

ATTR_VALUE

protected static final String ATTR_VALUE

Constant for the value attribute.

See Also:

Constant Field Values

Constructor Detail

ConfigurationXMLDocument

public ConfigurationXMLDocument(Configuration config)

Creates a new instance of ConfigurationXMLDocument and sets the configuration object to be processed.

Parameters:

config - the configuration object

Method Detail

getConfiguration

public Configuration getConfiguration()

Returns the Configuration object for this document.

Returns:

the Configuration object

setConfiguration

public void setConfiguration(Configuration configuration)

Sets the Configuration object this document operates on.

Parameters:

configuration - the Configuration object

createXMLReader

public static ConfigurationXMLReader createXMLReader(Configuration config)

Returns a XMLReader object for the specified configuration object. This reader can then be used to perform XML-like processing on the configuration.

Parameters:

config - the configuration object

Returns:

a XMLReader for this configuration

createXMLReader

public ConfigurationXMLReader createXMLReader()

Returns a XMLReader object for the actual configuration object.

Returns:

a XMLReader for the actual configuration

createXMLReader

public ConfigurationXMLReader createXMLReader(String prefix)

Returns a ConfigurationXMLReader object for the subset configuration specified by the given prefix. If no properties are found under this prefix, a NoSuchElementException exception will be thrown.

Parameters:

prefix - the prefix of the configuration keys that belong to the subset; can be null, then the whole configuration is affected

Returns:

a XMLReader for the specified subset configuration

getDocument

public Document getDocument(String prefix,
                            String rootName)
                     throws DocumentException

Transforms the wrapped configuration into a dom4j document.

Parameters:

prefix - a prefix for the keys to process; can be null, then all keys in the configuration will be added to the document

rootName - the name of the root element in the document; can be null, then a default name will be used

Returns:

the document

Throws:

DocumentException - if an error occurs

getDocument

public Document getDocument(String prefix)
                     throws DocumentException

Transforms the wrapped configuration into a dom4j document. The root element will be given a default name.

Parameters:

prefix - a prefix for the keys to process; can be null, then all keys in the configuration will be added to the document

Returns:

the document

Throws:

DocumentException - if an error occurs

getDocument

public Document getDocument()
                     throws DocumentException

Transforms the wrapped configuration into a dom4j document. The root element will be given a default name.

Returns:

the document

Throws:

DocumentException - if an error occurs

getW3cDocument

public Document getW3cDocument(String prefix,
                               String rootName)
                        throws DocumentException

Transforms the wrapped configuration into a w3c document.

Parameters:

prefix - a prefix for the keys to process; can be null, then all keys in the configuration will be added to the document

rootName - the name of the root element in the document; can be null, then a default name will be used

Returns:

the document

Throws:

DocumentException - if an error occurs

getW3cDocument

public Document getW3cDocument(String prefix)
                        throws DocumentException

Transforms the wrapped configuration into a w3c document. The root element will be given a default name.

Parameters:

prefix - a prefix for the keys to process; can be null, then all keys in the configuration will be added to the document

Returns:

the document

Throws:

DocumentException - if an error occurs

getW3cDocument

public Document getW3cDocument()
                        throws DocumentException

Transforms the wrapped configuration into a w3c document. The root element will be given a default name.

Returns:

the document

Throws:

DocumentException - if an error occurs

callDigester

public Object callDigester(String prefix)
                    throws IOException,
                           SAXException

Creates and initializes an object specified in the configuration using Digester.

This method first constructs a subset configuration with the keys starting with the given prefix. It then transforms this subset into a XML document and let that be processed by Digester. The result of this processing is returned.

The method is intended to be used for creating simple objects that are specified somewhere in the configuration in a standard way. The following fragment shows how a configuration file must look like to be understood by the default Digester rule set used by this method:

 ...
   <class name="mypackage.MyClass"/>
   <args>
     <property name="myFirstProperty" value="myFirstValue"/>
     <property name="MySecondProperty" value="mySecondValue"/>
     ...
   </args>
 ...
 

Parameters:

prefix - the prefix of the keys that are passed to Digester; can be null, then the whole configuration will be processed

Returns:

the result of the Digester processing

Throws:

IOException - if an IOException occurs

SAXException - if a SAXException occurs

getDefaultDigester

protected Digester getDefaultDigester(String prefix)

Returns a default Digester instance. This instance is used for the simple object creation feature.

Parameters:

prefix - the prefix of the keys to be processed; can be null, then the whole configuration is meant

Returns:

the default Digester instance

createDefaultDigester

protected Digester createDefaultDigester(String prefix)

Creates the default Digester instance for the given prefix. This method is called by getDefaultDigester().

Parameters:

prefix - the prefix of the keys to be processed; can be null, then the whole configuration is meant

Returns:

the default Digester instance

setupDefaultDigester

protected void setupDefaultDigester(Digester digester)

Initializes the default digester instance used for simple object creation. Here all needed properties and rules can be set. This base implementation sets default rules for object creation as explained in the comment for the callDigester() methods.

Parameters:

digester - the digester instance to be initialized

write

public void write(Writer out,
                  String prefix,
                  String root,
                  boolean pretty)
           throws IOException,
                  DocumentException

Writes a configuration (or parts of it) to the given writer.

Parameters:

out - the output writer

prefix - the prefix of the subset to write; if null, the whole configuration is written

root - the name of the root element of the resulting document; null for a default name

pretty - flag for the pretty print mode

Throws:

IOException - if an IO error occurs

DocumentException - if there is an error during processing

write

public void write(Writer out,
                  String prefix,
                  String root)
           throws IOException,
                  DocumentException

Writes a configuration (or parts of it) to the given writer. This overloaded version always uses pretty print mode.

Parameters:

out - the output writer

prefix - the prefix of the subset to write; if null, the whole configuration is written

root - the name of the root element of the resulting document; null for a default name

Throws:

IOException - if an IO error occurs

DocumentException - if there is an error during processing

write

public void write(Writer out,
                  String prefix,
                  boolean pretty)
           throws IOException,
                  DocumentException

Writes a configuration (or parts of it) to the given writer. The resulting document's root element will be given a default name.

Parameters:

out - the output writer

prefix - the prefix of the subset to write; if null, the whole configuration is written

pretty - flag for the pretty print mode

Throws:

IOException - if an IO error occurs

DocumentException - if there is an error during processing

write

public void write(Writer out,
                  String prefix)
           throws IOException,
                  DocumentException

Writes a configuration (or parts of it) to the given writer. The resulting document's root element will be given a default name. This overloaded version always uses pretty print mode.

Parameters:

out - the output writer

prefix - the prefix of the subset to write; if null, the whole configuration is written

Throws:

IOException - if an IO error occurs

DocumentException - if there is an error during processing

write

public void write(Writer out,
                  boolean pretty)
           throws IOException,
                  DocumentException

Writes the wrapped configuration to the given writer. The resulting document's root element will be given a default name.

Parameters:

out - the output writer

pretty - flag for the pretty print mode

Throws:

IOException - if an IO error occurs

DocumentException - if there is an error during processing

write

public void write(Writer out)
           throws IOException,
                  DocumentException

Writes the wrapped configuration to the given writer. The resulting document's root element will be given a default name. This overloaded version always uses pretty print mode.

Parameters:

out - the output writer

Throws:

IOException - if an IO error occurs

DocumentException - if there is an error during processing