## org.apache.commons.configuration
Class XMLConfiguration

    java.lang.Object
      org.apache.commons.configuration.event.EventSource
          org.apache.commons.configuration.AbstractConfiguration
              org.apache.commons.configuration.HierarchicalConfiguration
                  org.apache.commons.configuration.AbstractHierarchicalFileConfiguration
                      org.apache.commons.configuration.XMLConfiguration

All Implemented Interfaces:
  Serializable, Cloneable, Configuration, ConfigurationListener, FileConfiguration

Direct Known Subclasses:
  DefaultConfigurationBuilder, HierarchicalXMLConfiguration

    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: 439648 $, $Date: 2006-09-02 22:42:10 +0200 (Sa, 02 Sep 2006) $
Author:
  Jörg Schaible, Oliver Heger
See Also:
  Serialized Form

Nested Class Summary
`(package private) static class` `XMLConfiguration.XMLBuilderVisitor` A concrete `BuilderVisitor` that can construct XML documents.
`(package private) class` `XMLConfiguration.XMLNode` A specialized `Node` class that is connected with an XML element.

Nested classes/interfaces inherited from class org.apache.commons.configuration.AbstractHierarchicalFileConfiguration
`AbstractHierarchicalFileConfiguration.FileConfigurationDelegate`

Nested classes/interfaces inherited from class org.apache.commons.configuration.HierarchicalConfiguration
`HierarchicalConfiguration.BuilderVisitor, HierarchicalConfiguration.CloneVisitor, HierarchicalConfiguration.DefinedKeysVisitor, HierarchicalConfiguration.DefinedVisitor, HierarchicalConfiguration.Node, HierarchicalConfiguration.NodeVisitor`

Field Summary

Fields inherited from class org.apache.commons.configuration.HierarchicalConfiguration
`EVENT_ADD_NODES, EVENT_CLEAR_TREE`

Fields inherited from class org.apache.commons.configuration.AbstractConfiguration
`END_TOKEN, EVENT_ADD_PROPERTY, EVENT_CLEAR, EVENT_CLEAR_PROPERTY, EVENT_SET_PROPERTY, START_TOKEN`

Constructor Summary
`XMLConfiguration()` Creates a new instance of `XMLConfiguration`.
`XMLConfiguration(File file)` Creates a new instance of `XMLConfiguration`.
`XMLConfiguration(String fileName)` Creates a new instance of `XMLConfiguration`.
`XMLConfiguration(URL url)` Creates a new instance of `XMLConfiguration`.

Method Summary
`void` `clear()` Removes all properties from this configuration.
`Object` `clone()` Creates a copy of this object.
`protected AbstractHierarchicalFileConfiguration.FileConfigurationDelegate` `createDelegate()` Creates the file configuration delegate for this object.
`protected Document` `createDocument()` Creates a DOM document from the internal tree of configuration nodes.
`protected DocumentBuilder` `createDocumentBuilder()` Creates the `DocumentBuilder` to be used for loading files.
`protected HierarchicalConfiguration.Node` `createNode(String name)` Creates a new node object.
`protected Transformer` `createTransformer()` Creates and initializes the transformer used for save operations.
`Document` `getDocument()` Returns the XML document this configuration was loaded from.
`DocumentBuilder` `getDocumentBuilder()` Returns the `DocumentBuilder` object that is used for loading documents.
`String` `getPublicID()` Returns the public ID of the DOCTYPE declaration from the loaded XML document.
`String` `getRootElementName()` Returns the name of the root element.
`String` `getSystemID()` Returns the system ID of the DOCTYPE declaration from the loaded XML document.
`void` `initProperties(Document document, boolean elemRefs)` Initializes this configuration from an XML document.
`boolean` `isValidating()` Returns the value of the validating flag.
`void` `load(InputStream in)` Loads the configuration from the given input stream.
`void` `load(Reader in)` Load the configuration from the given reader.
`void` `save(Writer writer)` Saves the configuration to the specified writer.
`void` `setDocumentBuilder(DocumentBuilder documentBuilder)` Sets the `DocumentBuilder` object to be used for loading documents.
`void` `setPublicID(String publicID)` Sets the public ID of the DOCTYPE declaration.
`void` `setRootElementName(String name)` Sets the name of the root element.
`void` `setSystemID(String systemID)` Sets the system ID of the DOCTYPE declaration.
`void` `setValidating(boolean validating)` Sets the value of the validating flag.

Methods inherited from class org.apache.commons.configuration.AbstractHierarchicalFileConfiguration

`addPropertyDirect, clearProperty, clearTree, configurationChanged, containsKey, getBasePath, getDelegate, getEncoding, getFile, getFileName, getKeys, getProperty, getReloadingStrategy, getURL, isAutoSave, isEmpty, load, load, load, load, load, reload, save, save, save, save, save, save, setAutoSave, setBasePath, setDelegate, setEncoding, setFile, setFileName, setProperty, setReloadingStrategy, setURL`

Methods inherited from class org.apache.commons.configuration.HierarchicalConfiguration
`addNodes, clearNode, clearNode, configurationAt, configurationsAt, createAddPath, createSubnodeConfiguration, fetchAddNode, fetchNodeList, findLastPathNode, findPropertyNodes, getDefaultExpressionEngine, getExpressionEngine, getKeys, getMaxIndex, getRoot, getRootNode, nodeDefined, nodeDefined, removeNode, removeNode, setDefaultExpressionEngine, setExpressionEngine, setRoot, setRootNode, subset`

Methods inherited from class org.apache.commons.configuration.AbstractConfiguration

`addProperty, clearPropertyDirect, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDefaultListDelimiter, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getList, getList, getListDelimiter, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, interpolate, interpolate, interpolateHelper, isDelimiterParsingDisabled, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setDelimiterParsingDisabled, setListDelimiter, setThrowExceptionOnMissing`

Methods inherited from class org.apache.commons.configuration.event.EventSource
`addConfigurationListener, clearConfigurationListeners, createEvent, fireEvent, getConfigurationListeners, isDetailEvents, removeConfigurationListener, setDetailEvents`

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface org.apache.commons.configuration.Configuration
`addProperty, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getList, getList, getLong, getLong, getLong, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, subset`

Constructor Detail

### XMLConfiguration

    public XMLConfiguration()

  Creates a new instance of `XMLConfiguration`.

### XMLConfiguration

    public XMLConfiguration(String fileName)
                     throws ConfigurationException

  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)
                     throws ConfigurationException

  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)
                     throws ConfigurationException

  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

### 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

### 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

### 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

### 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

### 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

### 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

### 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

### 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

### isValidating

    public boolean isValidating()

  Returns the value of the validating flag.

  Returns:
    the validating flag
  Since:
    1.2

### 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

### 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

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

  Specified by:
    `clear` in interface `Configuration`
  Overrides:
    `clear` in class `AbstractConfiguration`

### 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

### createDocumentBuilder

    protected DocumentBuilder createDocumentBuilder()
                                             throws ParserConfigurationException

  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

### createDocument

    protected Document createDocument()
                               throws ConfigurationException

  Creates a DOM document from the internal tree of configuration nodes.

  Returns:
    the new document
  Throws:
    `ConfigurationException` - if an error occurs

### createNode

    protected HierarchicalConfiguration.Node createNode(String name)

  Creates a new node object. This implementation returns an instance of the `XMLNode` class.

  Overrides:
    `createNode` in class `HierarchicalConfiguration`
  Parameters:
    `name` - the node's name
  Returns:
    the new node

### load

    public void load(InputStream in)
              throws ConfigurationException

  Loads the configuration from the given input stream.

  Specified by:
    `load` in interface `FileConfiguration`
  Overrides:
    `load` in class `AbstractHierarchicalFileConfiguration`
  Parameters:
    `in` - the input stream
  Throws:
    `ConfigurationException` - if an error occurs

### load

    public void load(Reader in)
              throws ConfigurationException

  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

### save

    public void save(Writer writer)
              throws ConfigurationException

  Saves the configuration to the specified writer.

  Parameters:
    `writer` - the writer used to save the configuration
  Throws:
    `ConfigurationException` - if an error occurs

### createTransformer

    protected Transformer createTransformer()
                                     throws TransformerException

  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

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

  Overrides:
    `clone` in class `HierarchicalConfiguration`
  Returns:
    the copy

### createDelegate

    protected AbstractHierarchicalFileConfiguration.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`.

  Overrides:
    `createDelegate` in class `AbstractHierarchicalFileConfiguration`
  Returns:
    the delegate for this object

Copyright © 2001-2006 The Apache Software Foundation. All Rights Reserved.