org.apache.commons.configuration
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) $
Nested Class Summary | |
---|---|
static class | XMLConfiguration.XMLBuilderVisitor
A concrete BuilderVisitor that can construct XML
documents. |
class | XMLConfiguration.XMLFileConfigurationDelegate
A special implementation of the FileConfiguration interface that is
used internally to implement the FileConfiguration methods
for XMLConfiguration , too. |
class | XMLConfiguration.XMLNode
A specialized Node class that is connected with an XML
element. |
Field Summary | |
---|---|
Document | document The document from this configuration's data source. |
DocumentBuilder | documentBuilder Stores the document builder that should be used for loading. |
static String | DEFAULT_ROOT_NAME Constant for the default root element name. |
String | publicID Stores the public ID from the DOCTYPE. |
String | rootElementName Stores the name of the root element. |
static long | serialVersionUID
The serial version UID. |
String | systemID Stores the system ID from the DOCTYPE. |
boolean | validating 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 | |
---|---|
void | clear()
Removes all properties from this configuration. |
Object | clone()
Creates a copy of this object. |
void | constructHierarchy(Node node, Element element, boolean elemRefs)
Helper method for building the internal storage hierarchy. |
protected 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 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 | handleDelimiters(Node parent, Node child)
Deals with elements whose value is a list. |
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 | load(InputSource source)
Loads a configuration file from the specified input source. |
void | processAttributes(Node node, Element element, boolean elemRefs)
Helper method for constructing node objects for the attributes of the
given XML element.
|
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. |
XMLConfiguration
.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
. 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
.
The configuration is loaded from the specified file.
Parameters: file the file
Throws: ConfigurationException if an error occurs while loading the file
XMLConfiguration
.
The configuration is loaded from the specified URL.
Parameters: url the URL
Throws: ConfigurationException if loading causes an error
Returns: the copy
Parameters: node the actual node element the actual XML element elemRefs a flag whether references to the XML elements should be set
FileConfigurationDelegate
that deals with some specialities of XMLConfiguration
.Returns: the delegate for this object
Returns: the new document
Throws: ConfigurationException if an error occurs
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
XMLNode
class.
Parameters: name the node's name
Returns: the new node
Returns: the transformer to use for a save operation
Throws: TransformerException if an error occurs
Since: 1.3
Returns: the XML document this configuration was loaded from
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
Returns: the public ID
Since: 1.3
Returns: the name of the root element
Returns: the system ID
Since: 1.3
Parameters: parent the parent element child the child element
Parameters: document the document to be parsed elemRefs a flag whether references to the XML elements should be set
Returns: the validating flag
Since: 1.2
Parameters: in the input stream
Throws: ConfigurationException if an error occurs
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
Parameters: source the input source
Throws: ConfigurationException if an error occurs
Parameters: node the actual node element the actual XML element elemRefs a flag whether references to the XML elements should be set
Parameters: writer the writer used to save the configuration
Throws: ConfigurationException if an error occurs
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
Parameters: publicID the public ID
Since: 1.3
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
Parameters: systemID the system ID
Since: 1.3
DocumentBuilder
was set.
Parameters: validating the validating flag
Since: 1.2