org.apache.avalon.framework.configuration
Class DefaultConfigurationBuilder

java.lang.Object
  org.apache.avalon.framework.configuration.DefaultConfigurationBuilder

public class DefaultConfigurationBuilder

extends java.lang.Object

A DefaultConfigurationBuilder builds Configurations from XML, via a SAX2 compliant parser.

XML namespace support is optional, and disabled by default to preserve backwards-compatibility. To enable it, pass the DefaultConfigurationBuilder(boolean) constructor the flag true, or pass a namespace-enabled XMLReader to the DefaultConfigurationBuilder(XMLReader) constructor.

The mapping from XML namespaces to Configuration namespaces is pretty straightforward, with one caveat: attribute namespaces are (deliberately) not supported. Enabling namespace processing has the following effects:

• Attributes starting with xmlns: are interpreted as declaring a prefix:namespaceURI mapping, and won't result in the creation of xmlns-prefixed attributes in the Configuration.
• Prefixed XML elements, like <doc:title xmlns:doc="http://foo.com">, will result in a Configuration with getName().equals("title") and getNamespace().equals("http://foo.com").

Whitespace handling. Since mixed content is not allowed in the configurations, whitespace is completely discarded in non-leaf nodes. For the leaf nodes the default behavior is to trim the space surrounding the value. This can be changed by specifying xml:space attribute with value of preserve in that case the whitespace is left intact.

Version:

$Id: DefaultConfigurationBuilder.java 30977 2004-07-30 08:57:54Z niclas $

Author:

Avalon Development Team

Constructor Summary

DefaultConfigurationBuilder()
Create a Configuration Builder with a default XMLReader that ignores namespaces.

DefaultConfigurationBuilder(boolean enableNamespaces)
Create a Configuration Builder, specifying a flag that determines namespace support.

DefaultConfigurationBuilder(org.xml.sax.XMLReader parser)
Create a Configuration Builder with your own XMLReader.

Method Summary

Configuration	build(org.xml.sax.InputSource input) Build a configuration object using an XML InputSource object
Configuration	build(java.io.InputStream inputStream) Build a configuration object using an InputStream.
Configuration	build(java.io.InputStream inputStream, java.lang.String systemId) Build a configuration object using an InputStream; supplying a systemId to make messages about all kinds of errors more meaningfull.
Configuration	build(java.lang.String uri) Build a configuration object using an URI
Configuration	buildFromFile(java.io.File file) Build a configuration object from a file using a File object.
Configuration	buildFromFile(java.lang.String filename) Build a configuration object from a file using a filename.
protected SAXConfigurationHandler	getHandler() Get a SAXConfigurationHandler for your configuration reading.
void	setEntityResolver(org.xml.sax.EntityResolver resolver) Sets the EntityResolver to be used by parser.

Methods inherited from class java.lang.Object

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

Constructor Detail

DefaultConfigurationBuilder

public DefaultConfigurationBuilder()

Create a Configuration Builder with a default XMLReader that ignores namespaces. In order to enable namespaces, use either the constructor that has a boolean or that allows you to pass in your own namespace-enabled XMLReader.

DefaultConfigurationBuilder

public DefaultConfigurationBuilder(boolean enableNamespaces)

Create a Configuration Builder, specifying a flag that determines namespace support.

Parameters:

enableNamespaces - If true, a namespace-aware SAXParser is used. If false, the default JAXP SAXParser (without namespace support) is used.

Since:

4.1

DefaultConfigurationBuilder

public DefaultConfigurationBuilder(org.xml.sax.XMLReader parser)

Create a Configuration Builder with your own XMLReader.

Parameters:

parser - an XMLReader

Method Detail

getHandler

protected SAXConfigurationHandler getHandler()

Get a SAXConfigurationHandler for your configuration reading.

Returns:

a SAXConfigurationHandler

buildFromFile

public Configuration buildFromFile(java.lang.String filename)
                            throws org.xml.sax.SAXException,
                                   java.io.IOException,
                                   ConfigurationException

Build a configuration object from a file using a filename.

Parameters:

filename - name of the file

Returns:

a Configuration object

Throws:

org.xml.sax.SAXException - if a parsing error occurs

java.io.IOException - if an I/O error occurs

ConfigurationException - if an error occurs

buildFromFile

public Configuration buildFromFile(java.io.File file)
                            throws org.xml.sax.SAXException,
                                   java.io.IOException,
                                   ConfigurationException

Build a configuration object from a file using a File object.

Parameters:

file - a File object

Returns:

a Configuration object

Throws:

org.xml.sax.SAXException - if a parsing error occurs

java.io.IOException - if an I/O error occurs

ConfigurationException - if an error occurs

build

public Configuration build(java.io.InputStream inputStream)
                    throws org.xml.sax.SAXException,
                           java.io.IOException,
                           ConfigurationException

Build a configuration object using an InputStream.

Parameters:

inputStream - an InputStream value

Returns:

a Configuration object

Throws:

org.xml.sax.SAXException - if a parsing error occurs

java.io.IOException - if an I/O error occurs

ConfigurationException - if an error occurs

build

public Configuration build(java.io.InputStream inputStream,
                           java.lang.String systemId)
                    throws org.xml.sax.SAXException,
                           java.io.IOException,
                           ConfigurationException

Build a configuration object using an InputStream; supplying a systemId to make messages about all kinds of errors more meaningfull.

Parameters:

inputStream - an InputStream value

systemId - the systemId to set on the intermediate sax inputSource

Returns:

a Configuration object

Throws:

org.xml.sax.SAXException - if a parsing error occurs

java.io.IOException - if an I/O error occurs

ConfigurationException - if an error occurs

build

public Configuration build(java.lang.String uri)
                    throws org.xml.sax.SAXException,
                           java.io.IOException,
                           ConfigurationException

Build a configuration object using an URI

Parameters:

uri - a String value

Returns:

a Configuration object

Throws:

org.xml.sax.SAXException - if a parsing error occurs

java.io.IOException - if an I/O error occurs

ConfigurationException - if an error occurs

build

public Configuration build(org.xml.sax.InputSource input)
                    throws org.xml.sax.SAXException,
                           java.io.IOException,
                           ConfigurationException

Build a configuration object using an XML InputSource object

Parameters:

input - an InputSource value

Returns:

a Configuration object

Throws:

org.xml.sax.SAXException - if a parsing error occurs

java.io.IOException - if an I/O error occurs

ConfigurationException - if an error occurs

setEntityResolver

public void setEntityResolver(org.xml.sax.EntityResolver resolver)

Sets the EntityResolver to be used by parser. Useful when dealing with xml files that reference external entities.

Parameters:

resolver - implementation of EntityResolver