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
scalarproperty 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\\");
However, in XML such a constellation is not supported; an attribute can
appear only once for a single element. Therefore, an attempt to save a
configuration which violates this condition will throw an exception.
Like other
Configuration implementations,
XMLConfigurationuses a
ListDelimiterHandler object for controlling list split
operations. Per default, a list delimiter handler object is set which
disables this feature. XML has a built-in support for complex structures
including list properties; therefore, list splitting is not that relevant for
this configuration type. Nevertheless, by setting an alternative
ListDelimiterHandler implementation, this feature can be enabled. It
works as for any other concrete
Configuration implementation.
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
FileBasedConfigurationinterface and thus can be used together with a file-based builder to load XML
configuration files from various sources like files, URLs, or streams.
Like other
Configuration implementations, this class uses a
Synchronizer object to control concurrent access. By choosing a
suitable implementation of the
Synchronizer interface, an instance
can be made thread-safe or not. Note that access to most of the properties
typically set through a builder is not protected by the
Synchronizer.
The intended usage is that these properties are set once at construction time
through the builder and after that remain constant. If you wish to change
such properties during life time of an instance, you have to use the
lock() and
unlock() methods manually to ensure that other
threads see your changes.
More information about the basic functionality supported by
XMLConfiguration can be found at the user's guide at
Basic features and AbstractConfiguration. There is
also a separate chapter dealing with
XML Configurations in special.