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 {@link AbstractConfiguration} this class provides some extended functionality, e.g. interpolation of property values. Like in {@link 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 {@link #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.
XMLConfiguration implements the {@link 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 {@link 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 @author Jörg Schaible @author Oliver Heger @version $Revision: 589380 $, $Date: 2007-10-28 17:37:35 +0100 (So, 28 Okt 2007) $ | |
| |
| |
| |
| |
| |
| |
| |
| |
| |