org.apache.commons.configuration

Class XMLConfiguration

public class XMLConfiguration extends AbstractHierarchicalFileConfiguration

A specialized hierarchical configuration class that is able to parse XML documents.

The parsed document will be stored keeping its structure. The class also tries to preserve as much information from the loaded XML document as possible, including comments and processing instructions. These will be contained in documents created by the save() methods, too.

Like other file based configuration classes this class maintains the name and path to the loaded configuration file. These properties can be altered using several setter methods, but they are not modified by save() and load() methods. If XML documents contain relative paths to other documents (e.g. to a DTD), these references are resolved based on the path set for this configuration.

By inheriting from AbstractConfiguration this class provides some extended functionaly, e.g. interpolation of property values. Like in PropertiesConfiguration property values can contain delimiter characters (the comma ',' per default) and are then splitted into multiple values. This works for XML attributes and text content of elements as well. The delimiter can be escaped by a backslash. As an example consider the following XML fragment:

 <config>
   <array>10,20,30,40</array>
   <scalar>3\,1415</scalar>
   <cite text="To be or not to be\, this is the question!"/>
 </config>
 

Here the content of the array element will be splitted at the commas, so the array key will be assigned 4 values. In the scalar property and the text attribute of the cite element the comma is escaped, so that no splitting is performed.

XMLConfiguration implements the FileConfiguration interface and thus provides full support for loading XML documents from different sources like files, URLs, or streams. A full description of these features can be found in the documentation of AbstractFileConfiguration.

Since: commons-configuration 1.0

Version: $Revision: 513498 $, $Date: 2007-03-01 22:15:07 +0100 (Do, 01 Mrz 2007) $

Author: Jörg Schaible Oliver Heger

Nested Class Summary
static classXMLConfiguration.XMLBuilderVisitor
A concrete BuilderVisitor that can construct XML documents.
classXMLConfiguration.XMLFileConfigurationDelegate
A special implementation of the FileConfiguration interface that is used internally to implement the FileConfiguration methods for XMLConfiguration, too.
classXMLConfiguration.XMLNode
A specialized Node class that is connected with an XML element.
Field Summary
Documentdocument
The document from this configuration's data source.
DocumentBuilderdocumentBuilder
Stores the document builder that should be used for loading.
static StringDEFAULT_ROOT_NAME
Constant for the default root element name.
StringpublicID
Stores the public ID from the DOCTYPE.
StringrootElementName
Stores the name of the root element.
static longserialVersionUID
The serial version UID.
StringsystemID
Stores the system ID from the DOCTYPE.
booleanvalidating
Stores a flag whether DTD validation should be performed.
Constructor Summary
XMLConfiguration()
Creates a new instance of XMLConfiguration.
XMLConfiguration(HierarchicalConfiguration c)
Creates a new instance of XMLConfiguration and copies the content of the passed in configuration into this object.
XMLConfiguration(String fileName)
Creates a new instance of XMLConfiguration.
XMLConfiguration(File file)
Creates a new instance of XMLConfiguration.
XMLConfiguration(URL url)
Creates a new instance of XMLConfiguration.
Method Summary
voidclear()
Removes all properties from this configuration.
Objectclone()
Creates a copy of this object.
voidconstructHierarchy(Node node, Element element, boolean elemRefs)
Helper method for building the internal storage hierarchy.
protected FileConfigurationDelegatecreateDelegate()
Creates the file configuration delegate for this object.
protected DocumentcreateDocument()
Creates a DOM document from the internal tree of configuration nodes.
protected DocumentBuildercreateDocumentBuilder()
Creates the DocumentBuilder to be used for loading files.
protected NodecreateNode(String name)
Creates a new node object.
protected TransformercreateTransformer()
Creates and initializes the transformer used for save operations.
DocumentgetDocument()
Returns the XML document this configuration was loaded from.
DocumentBuildergetDocumentBuilder()
Returns the DocumentBuilder object that is used for loading documents.
StringgetPublicID()
Returns the public ID of the DOCTYPE declaration from the loaded XML document.
StringgetRootElementName()
Returns the name of the root element.
StringgetSystemID()
Returns the system ID of the DOCTYPE declaration from the loaded XML document.
voidhandleDelimiters(Node parent, Node child)
Deals with elements whose value is a list.
voidinitProperties(Document document, boolean elemRefs)
Initializes this configuration from an XML document.
booleanisValidating()
Returns the value of the validating flag.
voidload(InputStream in)
Loads the configuration from the given input stream.
voidload(Reader in)
Load the configuration from the given reader.
voidload(InputSource source)
Loads a configuration file from the specified input source.
voidprocessAttributes(Node node, Element element, boolean elemRefs)
Helper method for constructing node objects for the attributes of the given XML element.
voidsave(Writer writer)
Saves the configuration to the specified writer.
voidsetDocumentBuilder(DocumentBuilder documentBuilder)
Sets the DocumentBuilder object to be used for loading documents.
voidsetPublicID(String publicID)
Sets the public ID of the DOCTYPE declaration.
voidsetRootElementName(String name)
Sets the name of the root element.
voidsetSystemID(String systemID)
Sets the system ID of the DOCTYPE declaration.
voidsetValidating(boolean validating)
Sets the value of the validating flag.

Field Detail

document

private Document document
The document from this configuration's data source.

documentBuilder

private DocumentBuilder documentBuilder
Stores the document builder that should be used for loading.

DEFAULT_ROOT_NAME

private static final String DEFAULT_ROOT_NAME
Constant for the default root element name.

publicID

private String publicID
Stores the public ID from the DOCTYPE.

rootElementName

private String rootElementName
Stores the name of the root element.

serialVersionUID

private static final long serialVersionUID
The serial version UID.

systemID

private String systemID
Stores the system ID from the DOCTYPE.

validating

private boolean validating
Stores a flag whether DTD validation should be performed.

Constructor Detail

XMLConfiguration

public XMLConfiguration()
Creates a new instance of XMLConfiguration.

XMLConfiguration

public XMLConfiguration(HierarchicalConfiguration c)
Creates a new instance of XMLConfiguration and copies the content of the passed in configuration into this object. Note that only the data of the passed in configuration will be copied. If, for instance, the other configuration is a XMLConfiguration, too, things like comments or processing instructions will be lost.

Parameters: c the configuration to copy

Since: 1.4

XMLConfiguration

public XMLConfiguration(String fileName)
Creates a new instance of XMLConfiguration. The configuration is loaded from the specified file

Parameters: fileName the name of the file to load

Throws: ConfigurationException if the file cannot be loaded

XMLConfiguration

public XMLConfiguration(File file)
Creates a new instance of XMLConfiguration. The configuration is loaded from the specified file.

Parameters: file the file

Throws: ConfigurationException if an error occurs while loading the file

XMLConfiguration

public XMLConfiguration(URL url)
Creates a new instance of XMLConfiguration. The configuration is loaded from the specified URL.

Parameters: url the URL

Throws: ConfigurationException if loading causes an error

Method Detail

clear

public void clear()
Removes all properties from this configuration. If this configuration was loaded from a file, the associated DOM document is also cleared.

clone

public Object clone()
Creates a copy of this object. The new configuration object will contain the same properties as the original, but it will lose any connection to a source document (if one exists). This is to avoid race conditions if both the original and the copy are modified and then saved.

Returns: the copy

constructHierarchy

private void constructHierarchy(Node node, Element element, boolean elemRefs)
Helper method for building the internal storage hierarchy. The XML elements are transformed into node objects.

Parameters: node the actual node element the actual XML element elemRefs a flag whether references to the XML elements should be set

createDelegate

protected FileConfigurationDelegate createDelegate()
Creates the file configuration delegate for this object. This implementation will return an instance of a class derived from FileConfigurationDelegate that deals with some specialities of XMLConfiguration.

Returns: the delegate for this object

createDocument

protected Document createDocument()
Creates a DOM document from the internal tree of configuration nodes.

Returns: the new document

Throws: ConfigurationException if an error occurs

createDocumentBuilder

protected DocumentBuilder createDocumentBuilder()
Creates the DocumentBuilder to be used for loading files. This implementation checks whether a specific DocumentBuilder has been set. If this is the case, this one is used. Otherwise a default builder is created. Depending on the value of the validating flag this builder will be a validating or a non validating DocumentBuilder.

Returns: the DocumentBuilder for loading configuration files

Throws: ParserConfigurationException if an error occurs

Since: 1.2

createNode

protected Node createNode(String name)
Creates a new node object. This implementation returns an instance of the XMLNode class.

Parameters: name the node's name

Returns: the new node

createTransformer

protected Transformer createTransformer()
Creates and initializes the transformer used for save operations. This base implementation initializes all of the default settings like indention mode and the DOCTYPE. Derived classes may overload this method if they have specific needs.

Returns: the transformer to use for a save operation

Throws: TransformerException if an error occurs

Since: 1.3

getDocument

public Document getDocument()
Returns the XML document this configuration was loaded from. The return value is null if this configuration was not loaded from a XML document.

Returns: the XML document this configuration was loaded from

getDocumentBuilder

public DocumentBuilder getDocumentBuilder()
Returns the DocumentBuilder object that is used for loading documents. If no specific builder has been set, this method returns null.

Returns: the DocumentBuilder for loading new documents

Since: 1.2

getPublicID

public String getPublicID()
Returns the public ID of the DOCTYPE declaration from the loaded XML document. This is null if no document has been loaded yet or if the document does not contain a DOCTYPE declaration with a public ID.

Returns: the public ID

Since: 1.3

getRootElementName

public String getRootElementName()
Returns the name of the root element. If this configuration was loaded from a XML document, the name of this document's root element is returned. Otherwise it is possible to set a name for the root element that will be used when this configuration is stored.

Returns: the name of the root element

getSystemID

public String getSystemID()
Returns the system ID of the DOCTYPE declaration from the loaded XML document. This is null if no document has been loaded yet or if the document does not contain a DOCTYPE declaration with a system ID.

Returns: the system ID

Since: 1.3

handleDelimiters

private void handleDelimiters(Node parent, Node child)
Deals with elements whose value is a list. In this case multiple child elements must be added.

Parameters: parent the parent element child the child element

initProperties

public void initProperties(Document document, boolean elemRefs)
Initializes this configuration from an XML document.

Parameters: document the document to be parsed elemRefs a flag whether references to the XML elements should be set

isValidating

public boolean isValidating()
Returns the value of the validating flag.

Returns: the validating flag

Since: 1.2

load

public void load(InputStream in)
Loads the configuration from the given input stream.

Parameters: in the input stream

Throws: ConfigurationException if an error occurs

load

public void load(Reader in)
Load the configuration from the given reader. Note that the clear() method is not called, so the properties contained in the loaded file will be added to the actual set of properties.

Parameters: in An InputStream.

Throws: ConfigurationException if an error occurs

load

private void load(InputSource source)
Loads a configuration file from the specified input source.

Parameters: source the input source

Throws: ConfigurationException if an error occurs

processAttributes

private void processAttributes(Node node, Element element, boolean elemRefs)
Helper method for constructing node objects for the attributes of the given XML element.

Parameters: node the actual node element the actual XML element elemRefs a flag whether references to the XML elements should be set

save

public void save(Writer writer)
Saves the configuration to the specified writer.

Parameters: writer the writer used to save the configuration

Throws: ConfigurationException if an error occurs

setDocumentBuilder

public void setDocumentBuilder(DocumentBuilder documentBuilder)
Sets the DocumentBuilder object to be used for loading documents. This method makes it possible to specify the exact document builder. So an application can create a builder, configure it for its special needs, and then pass it to this method.

Parameters: documentBuilder the document builder to be used; if undefined, a default builder will be used

Since: 1.2

setPublicID

public void setPublicID(String publicID)
Sets the public ID of the DOCTYPE declaration. When this configuration is saved, a DOCTYPE declaration will be constructed that contains this public ID.

Parameters: publicID the public ID

Since: 1.3

setRootElementName

public void setRootElementName(String name)
Sets the name of the root element. This name is used when this configuration object is stored in an XML file. Note that setting the name of the root element works only if this configuration has been newly created. If the configuration was loaded from an XML file, the name cannot be changed and an UnsupportedOperationException exception is thrown. Whether this configuration has been loaded from an XML document or not can be found out using the getDocument() method.

Parameters: name the name of the root element

setSystemID

public void setSystemID(String systemID)
Sets the system ID of the DOCTYPE declaration. When this configuration is saved, a DOCTYPE declaration will be constructed that contains this system ID.

Parameters: systemID the system ID

Since: 1.3

setValidating

public void setValidating(boolean validating)
Sets the value of the validating flag. This flag determines whether DTD validation should be performed when loading XML documents. This flag is evaluated only if no custom DocumentBuilder was set.

Parameters: validating the validating flag

Since: 1.2