Package 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 03:57:54 -0500 (Fri, 30 Jul 2004) niclas $

Author:

Avalon Development Team

Field Summary

Fields

Modifier and Type	Field	Description
private SAXConfigurationHandler	m_handler
private org.xml.sax.XMLReader	m_parser

Constructor Summary

Constructors

Constructor	Description
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

Modifier and Type	Method	Description
org.apache.avalon.framework.configuration.Configuration	build(java.io.InputStream inputStream)	Build a configuration object using an InputStream.
org.apache.avalon.framework.configuration.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.
org.apache.avalon.framework.configuration.Configuration	build(java.lang.String uri)	Build a configuration object using an URI
org.apache.avalon.framework.configuration.Configuration	build(org.xml.sax.InputSource input)	Build a configuration object using an XML InputSource object
org.apache.avalon.framework.configuration.Configuration	buildFromFile(java.io.File file)	Build a configuration object from a file using a File object.
org.apache.avalon.framework.configuration.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.
private void	setParser(org.xml.sax.XMLReader parser)	Internally sets up the XMLReader

Methods inherited from class java.lang.Object

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

Field Detail

m_handler

private SAXConfigurationHandler m_handler

m_parser

private org.xml.sax.XMLReader m_parser

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

setParser

private void setParser(org.xml.sax.XMLReader parser)

Internally sets up the XMLReader

getHandler

protected SAXConfigurationHandler getHandler()

Get a SAXConfigurationHandler for your configuration reading.

Returns:

a SAXConfigurationHandler

buildFromFile

public org.apache.avalon.framework.configuration.Configuration buildFromFile(java.lang.String filename)
                                                                      throws org.xml.sax.SAXException,
                                                                             java.io.IOException,
                                                                             org.apache.avalon.framework.configuration.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

org.apache.avalon.framework.configuration.ConfigurationException - if an error occurs

buildFromFile

public org.apache.avalon.framework.configuration.Configuration buildFromFile(java.io.File file)
                                                                      throws org.xml.sax.SAXException,
                                                                             java.io.IOException,
                                                                             org.apache.avalon.framework.configuration.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

org.apache.avalon.framework.configuration.ConfigurationException - if an error occurs

build

public org.apache.avalon.framework.configuration.Configuration build(java.io.InputStream inputStream)
                                                              throws org.xml.sax.SAXException,
                                                                     java.io.IOException,
                                                                     org.apache.avalon.framework.configuration.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

org.apache.avalon.framework.configuration.ConfigurationException - if an error occurs

build

public org.apache.avalon.framework.configuration.Configuration build(java.io.InputStream inputStream,
                                                                     java.lang.String systemId)
                                                              throws org.xml.sax.SAXException,
                                                                     java.io.IOException,
                                                                     org.apache.avalon.framework.configuration.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

org.apache.avalon.framework.configuration.ConfigurationException - if an error occurs

build

public org.apache.avalon.framework.configuration.Configuration build(java.lang.String uri)
                                                              throws org.xml.sax.SAXException,
                                                                     java.io.IOException,
                                                                     org.apache.avalon.framework.configuration.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

org.apache.avalon.framework.configuration.ConfigurationException - if an error occurs

build

public org.apache.avalon.framework.configuration.Configuration build(org.xml.sax.InputSource input)
                                                              throws org.xml.sax.SAXException,
                                                                     java.io.IOException,
                                                                     org.apache.avalon.framework.configuration.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

org.apache.avalon.framework.configuration.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