org.apache.commons.configuration
Class XMLConfiguration

java.lang.Object
  |
  +--org.apache.commons.configuration.AbstractConfiguration
        |
        +--org.apache.commons.configuration.HierarchicalConfiguration
              |
              +--org.apache.commons.configuration.AbstractHierarchicalFileConfiguration
                    |
                    +--org.apache.commons.configuration.XMLConfiguration
All Implemented Interfaces:
Cloneable, Configuration, FileConfiguration, Serializable
Direct Known Subclasses:
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$, $Date: 2005-11-20 20:39:51 +0100 (Sun, 20 Nov 2005) $
Author:
Jörg Schaible, Oliver Heger
See Also:
Serialized Form

Inner classes inherited from class org.apache.commons.configuration.AbstractHierarchicalFileConfiguration
AbstractHierarchicalFileConfiguration.FileConfigurationDelegate
 
Inner classes inherited from class org.apache.commons.configuration.HierarchicalConfiguration
HierarchicalConfiguration.BuilderVisitor, HierarchicalConfiguration.Node, HierarchicalConfiguration.NodeVisitor
 
Fields inherited from class org.apache.commons.configuration.AbstractConfiguration
END_TOKEN, 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.
 Document getDocument()
          Returns the XML document this configuration was loaded from.
 DocumentBuilder getDocumentBuilder()
          Returns the DocumentBuilder object that is used for loading documents.
 String getRootElementName()
          Returns the name of the root element.
 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 setRootElementName(String name)
          Sets the name of the root element.
 void setValidating(boolean validating)
          Sets the value of the validating flag.
 
Methods inherited from class org.apache.commons.configuration.AbstractHierarchicalFileConfiguration
addPropertyDirect, clearProperty, clearTree, 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, createAddPath, fetchAddNode, fetchNodeList, findLastPathNode, findPropertyNodes, getKeys, getMaxIndex, getRoot, nodeDefined, removeNode, setRoot, subset
 
Methods inherited from class org.apache.commons.configuration.AbstractConfiguration
addProperty, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getList, getList, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, interpolate, interpolate, interpolateHelper, isThrowExceptionOnMissing, resolveContainerStore, setDelimiter, setThrowExceptionOnMissing
 
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

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

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-2005 The Apache Software Foundation. All Rights Reserved.