Class XMLConfiguration
- All Implemented Interfaces:
Serializable
,Cloneable
,Configuration
,ConfigurationErrorListener
,ConfigurationListener
,FileConfiguration
,FileSystemBased
,Reloadable
,EntityRegistry
,EntityResolver
- Direct Known Subclasses:
DefaultConfigurationBuilder
,HierarchicalXMLConfiguration
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 functionality, e.g. interpolation of property values.
Like in PropertiesConfiguration
property values can
contain delimiter characters (the comma ',' per default) and are then split
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 split 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.
The configuration API allows setting multiple values for a single attribute, e.g. something like the following is legal (assuming that the default expression engine is used):
XMLConfiguration config = new XMLConfiguration(); config.addProperty("test.dir[@name]", "C:\\Temp\\"); config.addProperty("test.dir[@name]", "D:\\Data\\");
Because in XML such a constellation is not directly supported (an attribute
can appear only once for a single element), the values are concatenated to a
single value. If delimiter parsing is enabled (refer to the
AbstractConfiguration.setDelimiterParsingDisabled(boolean)
method), the
current list delimiter character will be used as separator. Otherwise the
pipe symbol ("|") will be used for this purpose. No matter which character is
used as delimiter, it can always be escaped with a backslash. A backslash
itself can also be escaped with another backslash. Consider the following
example fragment from a configuration file:
<directories names="C:\Temp\\|D:\Data\"/>Here the backslash after Temp is escaped. This is necessary because it would escape the list delimiter (the pipe symbol assuming that list delimiter parsing is disabled) otherwise. So this attribute would have two values.
Note: You should ensure that the delimiter parsing disabled property is always consistent when you load and save a configuration file. Otherwise the values of properties can become corrupted.
Whitespace in the content of XML documents is trimmed per default. In most cases this is desired. However, sometimes whitespace is indeed important and should be treated as part of the value of a property as in the following example:
<indent> </indent>
Per default the spaces in the indent
element will be trimmed
resulting in an empty element. To tell XMLConfiguration
that
spaces are relevant the xml:space
attribute can be used, which is
defined in the XML
specification. This will look as follows:
<indent xml:space="preserve"> </indent>The value of the
indent
property will now contain the spaces.
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
.
Note:Configuration objects of this type can be read concurrently by multiple threads. However if one of these threads modifies the object, synchronization has to be performed manually.
- Since:
- commons-configuration 1.0
- Version:
- $Id: XMLConfiguration.java 1534429 2013-10-22 00:45:36Z henning $
- Author:
- Jörg Schaible
- See Also:
-
Nested Class Summary
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.Node, HierarchicalConfiguration.NodeVisitor
-
Field Summary
Fields inherited from class org.apache.commons.configuration.HierarchicalConfiguration
EVENT_ADD_NODES, EVENT_CLEAR_TREE, EVENT_SUBNODE_CHANGED
Fields inherited from class org.apache.commons.configuration.AbstractConfiguration
END_TOKEN, EVENT_ADD_PROPERTY, EVENT_CLEAR, EVENT_CLEAR_PROPERTY, EVENT_READ_PROPERTY, EVENT_SET_PROPERTY, START_TOKEN
-
Constructor Summary
ConstructorsConstructorDescriptionCreates a new instance ofXMLConfiguration
.XMLConfiguration
(File file) Creates a new instance ofXMLConfiguration
.XMLConfiguration
(String fileName) Creates a new instance ofXMLConfiguration
.XMLConfiguration
(URL url) Creates a new instance ofXMLConfiguration
.Creates a new instance ofXMLConfiguration
and copies the content of the passed in configuration into this object. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addNodes
(String key, Collection<? extends ConfigurationNode> nodes) Adds a collection of nodes directly to this configuration.void
clear()
Removes all properties from this configuration.clone()
Creates a copy of this object.Creates the file configuration delegate for this object.protected Document
Creates a DOM document from the internal tree of configuration nodes.protected DocumentBuilder
Creates theDocumentBuilder
to be used for loading files.protected HierarchicalConfiguration.Node
createNode
(String name) Creates a new node object.protected Transformer
Creates and initializes the transformer used for save operations.Returns the XML document this configuration was loaded from.Returns theDocumentBuilder
object that is used for loading documents.Returns the EntityResolver.Returns the public ID of the DOCTYPE declaration from the loaded XML document.Returns a map with the entity IDs that have been registered using theregisterEntityId()
method.Returns the name of the root element.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
Returns the flag whether attribute splitting is disabled.boolean
Returns the value of the schemaValidation flag.boolean
Returns the value of the validating flag.void
load
(InputStream in) Loads the configuration from the given input stream.void
Load the configuration from the given reader.void
registerEntityId
(String publicId, URL entityURL) Registers the specified DTD URL for the specified public identifier.resolveEntity
(String publicId, String systemId) Deprecated.Use getEntityResolver().resolveEntity()void
Saves the configuration to the specified writer.void
setAttributeSplittingDisabled
(boolean attributeSplittingDisabled) Sets a flag whether attribute splitting is disabled.void
setDocumentBuilder
(DocumentBuilder documentBuilder) Sets theDocumentBuilder
object to be used for loading documents.void
setEntityResolver
(EntityResolver resolver) Sets a new EntityResolver.void
setPublicID
(String publicID) Sets the public ID of the DOCTYPE declaration.void
setRootElementName
(String name) Sets the name of the root element.void
setSchemaValidation
(boolean schemaValidation) Sets the value of the schemaValidation flag.void
setSystemID
(String systemID) Sets the system ID of the DOCTYPE declaration.void
setValidating
(boolean validating) Sets the value of the validating flag.void
validate()
Validate the document against the Schema.Methods inherited from class org.apache.commons.configuration.AbstractHierarchicalFileConfiguration
addPropertyDirect, clearProperty, clearTree, configurationChanged, configurationError, containsKey, fetchNodeList, getBasePath, getDelegate, getEncoding, getFile, getFileName, getFileSystem, getKeys, getKeys, getProperty, getReloadingStrategy, getReloadLock, getURL, isAutoSave, isEmpty, load, load, load, load, load, refresh, reload, resetFileSystem, save, save, save, save, save, save, setAutoSave, setBasePath, setDelegate, setEncoding, setFile, setFileName, setFileSystem, setProperty, setReloadingStrategy, setURL, subnodeConfigurationChanged
Methods inherited from class org.apache.commons.configuration.HierarchicalConfiguration
clearNode, clearNode, clearReferences, configurationAt, configurationAt, configurationsAt, createAddPath, createSubnodeConfiguration, createSubnodeConfiguration, fetchAddNode, findLastPathNode, findPropertyNodes, getDefaultExpressionEngine, getExpressionEngine, getMaxIndex, getRoot, getRootNode, interpolatedConfiguration, nodeDefined, nodeDefined, removeNode, removeNode, setDefaultExpressionEngine, setExpressionEngine, setRoot, setRootNode, subset
Methods inherited from class org.apache.commons.configuration.AbstractConfiguration
addErrorLogListener, addProperty, append, clearPropertyDirect, copy, createInterpolator, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDefaultListDelimiter, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getList, getList, getListDelimiter, getLogger, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, getSubstitutor, interpolate, interpolate, interpolateHelper, isDelimiterParsingDisabled, isScalarValue, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setDelimiterParsingDisabled, setListDelimiter, setLogger, setThrowExceptionOnMissing
Methods inherited from class org.apache.commons.configuration.event.EventSource
addConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, createErrorEvent, createEvent, fireError, fireEvent, getConfigurationListeners, getErrorListeners, isDetailEvents, removeConfigurationListener, removeErrorListener, 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, getList, getList, getLong, getLong, getLong, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, subset
-
Constructor Details
-
XMLConfiguration
public XMLConfiguration()Creates a new instance ofXMLConfiguration
. -
XMLConfiguration
Creates a new instance ofXMLConfiguration
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 aXMLConfiguration
, too, things like comments or processing instructions will be lost.- Parameters:
c
- the configuration to copy- Since:
- 1.4
-
XMLConfiguration
Creates a new instance ofXMLConfiguration
. 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
Creates a new instance ofXMLConfiguration
. The configuration is loaded from the specified file.- Parameters:
file
- the file- Throws:
ConfigurationException
- if an error occurs while loading the file
-
XMLConfiguration
Creates a new instance ofXMLConfiguration
. The configuration is loaded from the specified URL.- Parameters:
url
- the URL- Throws:
ConfigurationException
- if loading causes an error
-
-
Method Details
-
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
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 anUnsupportedOperationException
exception is thrown. Whether this configuration has been loaded from an XML document or not can be found out using thegetDocument()
method.- Parameters:
name
- the name of the root element
-
getDocumentBuilder
Returns theDocumentBuilder
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
Sets theDocumentBuilder
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
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
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
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
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
Returns the value of the validating flag.- Returns:
- the validating flag
- Since:
- 1.2
-
setValidating
Sets the value of the validating flag. This flag determines whether DTD/Schema validation should be performed when loading XML documents. This flag is evaluated only if no customDocumentBuilder
was set.- Parameters:
validating
- the validating flag- Since:
- 1.2
-
isSchemaValidation
Returns the value of the schemaValidation flag.- Returns:
- the schemaValidation flag
- Since:
- 1.7
-
setSchemaValidation
Sets the value of the schemaValidation flag. This flag determines whether DTD or Schema validation should be used. This flag is evaluated only if no customDocumentBuilder
was set. If set to true the XML document must contain a schemaLocation definition that provides resolvable hints to the required schemas.- Parameters:
schemaValidation
- the validating flag- Since:
- 1.7
-
setEntityResolver
Sets a new EntityResolver. Setting this will cause RegisterEntityId to have no effect.- Parameters:
resolver
- The EntityResolver to use.- Since:
- 1.7
-
getEntityResolver
Returns the EntityResolver.- Returns:
- The EntityResolver.
- Since:
- 1.7
-
isAttributeSplittingDisabled
Returns the flag whether attribute splitting is disabled.- Returns:
- the flag whether attribute splitting is disabled
- Since:
- 1.6
- See Also:
-
setAttributeSplittingDisabled
Sets a flag whether attribute splitting is disabled.
The Configuration API allows adding multiple values to an attribute. This is problematic when storing the configuration because in XML an attribute can appear only once with a single value. To solve this problem, per default multiple attribute values are concatenated using a special separator character and split again when the configuration is loaded. The separator character is either the list delimiter character (see
AbstractConfiguration.setListDelimiter(char)
) or the pipe symbol ("|") if list delimiter parsing is disabled.In some constellations the splitting of attribute values can have undesired effects, especially if list delimiter parsing is disabled and attributes may contain the "|" character. In these cases it is possible to disable the attribute splitting mechanism by calling this method with a boolean value set to false. If attribute splitting is disabled, the values of attributes will not be processed, but stored as configuration properties exactly as they are returned by the XML parser.
Note that in this mode multiple attribute values cannot be handled correctly. It is possible to create a
XMLConfiguration
object, add multiple values to an attribute and save it. When the configuration is loaded again and attribute splitting is disabled, the attribute will only have a single value, which is the concatenation of all values set before. So it lies in the responsibility of the application to carefully set the values of attributes.As is true for the
AbstractConfiguration.setDelimiterParsingDisabled(boolean)
method, this method must be called before the configuration is loaded. So it can't be used together with one of the constructors expecting the specification of the file to load. Instead the default constructor has to be used, thensetAttributeSplittingDisabled(false)
has to be called, and finally the configuration can be loaded using one of itsload()
methods.- Parameters:
attributeSplittingDisabled
- true for disabling attribute splitting, false for enabling it- Since:
- 1.6
- See Also:
-
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
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 interfaceConfiguration
- Overrides:
clear
in classHierarchicalConfiguration
-
initProperties
Initializes this configuration from an XML document.- Parameters:
document
- the document to be parsedelemRefs
- a flag whether references to the XML elements should be set
-
createDocumentBuilder
Creates theDocumentBuilder
to be used for loading files. This implementation checks whether a specificDocumentBuilder
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 validatingDocumentBuilder
.- Returns:
- the
DocumentBuilder
for loading configuration files - Throws:
ParserConfigurationException
- if an error occurs- Since:
- 1.2
-
createDocument
Creates a DOM document from the internal tree of configuration nodes.- Returns:
- the new document
- Throws:
ConfigurationException
- if an error occurs
-
createNode
Creates a new node object. This implementation returns an instance of theXMLNode
class.- Overrides:
createNode
in classHierarchicalConfiguration
- Parameters:
name
- the node's name- Returns:
- the new node
-
load
Loads the configuration from the given input stream.- Specified by:
load
in interfaceFileConfiguration
- Overrides:
load
in classAbstractHierarchicalFileConfiguration
- Parameters:
in
- the input stream- Throws:
ConfigurationException
- if an error occurs
-
load
Load the configuration from the given reader. Note that theclear()
method is not called, so the properties contained in the loaded file will be added to the actual set of properties.- Specified by:
load
in interfaceFileConfiguration
- Parameters:
in
- An InputStream.- Throws:
ConfigurationException
- if an error occurs
-
save
Saves the configuration to the specified writer.- Specified by:
save
in interfaceFileConfiguration
- Parameters:
writer
- the writer used to save the configuration- Throws:
ConfigurationException
- if an error occurs
-
validate
Validate the document against the Schema.- Throws:
ConfigurationException
- if the validation fails.
-
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
-
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 classHierarchicalConfiguration
- Returns:
- the copy
-
createDelegate
Creates the file configuration delegate for this object. This implementation will return an instance of a class derived fromFileConfigurationDelegate
that deals with some specialties ofXMLConfiguration
.- Overrides:
createDelegate
in classAbstractHierarchicalFileConfiguration
- Returns:
- the delegate for this object
-
addNodes
Adds a collection of nodes directly to this configuration. This implementation ensures that the nodes to be added are of the correct node type (they have to be converted toXMLNode
if necessary).- Overrides:
addNodes
in classAbstractHierarchicalFileConfiguration
- Parameters:
key
- the key where the nodes are to be addednodes
- the collection with the new nodes- Since:
- 1.5
-
registerEntityId
Registers the specified DTD URL for the specified public identifier.
XMLConfiguration
contains an internalEntityResolver
implementation. This mapsPUBLICID
's to URLs (from which the resource will be loaded). A common use case for this method is to register local URLs (possibly computed at runtime by a class loader) for DTDs. This allows the performance advantage of using a local version without having to ensure everySYSTEM
URI on every processed XML document is local. This implementation provides only basic functionality. If more sophisticated features are required, usingsetDocumentBuilder(DocumentBuilder)
to set a customDocumentBuilder
(which also can be initialized with a customEntityResolver
) is recommended.Note: This method will have no effect when a custom
DocumentBuilder
has been set. (Setting a customDocumentBuilder
overrides the internal implementation.)Note: This method must be called before the configuration is loaded. So the default constructor of
XMLConfiguration
should be used, the location of the configuration file set,registerEntityId()
called, and finally theload()
method can be invoked.- Specified by:
registerEntityId
in interfaceEntityRegistry
- Parameters:
publicId
- Public identifier of the DTD to be resolvedentityURL
- The URL to use for reading this DTD- Throws:
IllegalArgumentException
- if the public ID is undefined- Since:
- 1.5
-
resolveEntity
Deprecated.Use getEntityResolver().resolveEntity()Resolves the requested external entity. This is the default implementation of theEntityResolver
interface. It checks the passed in public ID against the registered entity IDs and uses a local URL if possible.- Specified by:
resolveEntity
in interfaceEntityResolver
- Parameters:
publicId
- the public identifier of the entity being referencedsystemId
- the system identifier of the entity being referenced- Returns:
- an input source for the specified entity
- Throws:
SAXException
- if a parsing exception occurs- Since:
- 1.5
-
getRegisteredEntities
Returns a map with the entity IDs that have been registered using theregisterEntityId()
method.- Specified by:
getRegisteredEntities
in interfaceEntityRegistry
- Returns:
- a map with the registered entity IDs
-