public class XMLConfiguration extends AbstractHierarchicalFileConfiguration implements EntityResolver
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
this class
provides some extended functionality, e.g. interpolation of property values.
Like in AbstractConfiguration
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:PropertiesConfiguration
<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
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:
AbstractConfiguration.setDelimiterParsingDisabled(boolean)
<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
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
FileConfiguration
.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.
AbstractHierarchicalFileConfiguration.FileConfigurationDelegate
HierarchicalConfiguration.BuilderVisitor, HierarchicalConfiguration.Node, HierarchicalConfiguration.NodeVisitor
EVENT_ADD_NODES, EVENT_CLEAR_TREE, EVENT_SUBNODE_CHANGED
END_TOKEN, EVENT_ADD_PROPERTY, EVENT_CLEAR, EVENT_CLEAR_PROPERTY, EVENT_READ_PROPERTY, EVENT_SET_PROPERTY, START_TOKEN
Constructor and Description |
---|
XMLConfiguration()
Creates a new instance of
XMLConfiguration . |
XMLConfiguration(File file)
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(URL url)
Creates a new instance of
XMLConfiguration . |
Modifier and Type | Method and Description |
---|---|
void |
addNodes(String key,
Collection nodes)
Adds a collection of nodes directly to this configuration.
|
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.
|
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 |
initProperties(Document document,
boolean elemRefs)
Initializes this configuration from an XML document.
|
boolean |
isAttributeSplittingDisabled()
Returns the flag whether attribute splitting is disabled.
|
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 |
registerEntityId(String publicId,
URL entityURL)
Registers the specified DTD URL for the specified public identifier.
|
InputSource |
resolveEntity(String publicId,
String systemId)
Resolves the requested external entity.
|
void |
save(Writer writer)
Saves the configuration to the specified writer.
|
void |
setAttributeSplittingDisabled(boolean attributeSplittingDisabled)
Sets a flag whether attribute splitting is disabled.
|
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.
|
addPropertyDirect, clearProperty, clearTree, configurationChanged, containsKey, fetchNodeList, getBasePath, getDelegate, getEncoding, getFile, getFileName, getKeys, 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, subnodeConfigurationChanged
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
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, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setDelimiterParsingDisabled, setListDelimiter, setLogger, setThrowExceptionOnMissing
addConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, createErrorEvent, createEvent, fireError, fireEvent, getConfigurationListeners, getErrorListeners, isDetailEvents, removeConfigurationListener, removeErrorListener, setDetailEvents
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
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
public XMLConfiguration()
XMLConfiguration
.public XMLConfiguration(HierarchicalConfiguration c)
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.c
- the configuration to copypublic XMLConfiguration(String fileName) throws ConfigurationException
XMLConfiguration
. The
configuration is loaded from the specified filefileName
- the name of the file to loadConfigurationException
- if the file cannot be loadedpublic XMLConfiguration(File file) throws ConfigurationException
XMLConfiguration
.
The configuration is loaded from the specified file.file
- the fileConfigurationException
- if an error occurs while loading the filepublic XMLConfiguration(URL url) throws ConfigurationException
XMLConfiguration
.
The configuration is loaded from the specified URL.url
- the URLConfigurationException
- if loading causes an errorpublic String getRootElementName()
public void setRootElementName(String name)
UnsupportedOperationException
exception is thrown. Whether this configuration has been loaded from an
XML document or not can be found out using the getDocument()
method.name
- the name of the root elementpublic DocumentBuilder getDocumentBuilder()
DocumentBuilder
object that is used for
loading documents. If no specific builder has been set, this method
returns null.DocumentBuilder
for loading new documentspublic void setDocumentBuilder(DocumentBuilder documentBuilder)
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.documentBuilder
- the document builder to be used; if undefined, a
default builder will be usedpublic String getPublicID()
public void setPublicID(String publicID)
publicID
- the public IDpublic String getSystemID()
public void setSystemID(String systemID)
systemID
- the system IDpublic boolean isValidating()
public void setValidating(boolean validating)
DocumentBuilder
was set.validating
- the validating flagpublic boolean isAttributeSplittingDisabled()
setAttributeSplittingDisabled(boolean)
public void setAttributeSplittingDisabled(boolean attributeSplittingDisabled)
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, then setAttributeSplittingDisabled(false)
has to be
called, and finally the configuration can be loaded using one of its
load()
methods.
attributeSplittingDisabled
- true for disabling attribute
splitting, false for enabling itAbstractConfiguration.setDelimiterParsingDisabled(boolean)
public Document getDocument()
public void clear()
clear
in interface Configuration
clear
in class AbstractConfiguration
public void initProperties(Document document, boolean elemRefs)
document
- the document to be parsedelemRefs
- a flag whether references to the XML elements should be setprotected DocumentBuilder createDocumentBuilder() throws ParserConfigurationException
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
.DocumentBuilder
for loading configuration
filesParserConfigurationException
- if an error occursprotected Document createDocument() throws ConfigurationException
ConfigurationException
- if an error occursprotected HierarchicalConfiguration.Node createNode(String name)
XMLNode
class.createNode
in class HierarchicalConfiguration
name
- the node's namepublic void load(InputStream in) throws ConfigurationException
load
in interface FileConfiguration
load
in class AbstractHierarchicalFileConfiguration
in
- the input streamConfigurationException
- if an error occurspublic void load(Reader in) throws ConfigurationException
clear()
method is not called, so
the properties contained in the loaded file will be added to the
actual set of properties.load
in interface FileConfiguration
in
- An InputStream.ConfigurationException
- if an error occurspublic void save(Writer writer) throws ConfigurationException
save
in interface FileConfiguration
writer
- the writer used to save the configurationConfigurationException
- if an error occursprotected Transformer createTransformer() throws TransformerException
TransformerException
- if an error occurspublic Object clone()
clone
in class HierarchicalConfiguration
protected AbstractHierarchicalFileConfiguration.FileConfigurationDelegate createDelegate()
FileConfigurationDelegate
that deals with some specialities of XMLConfiguration
.createDelegate
in class AbstractHierarchicalFileConfiguration
public void addNodes(String key, Collection nodes)
XMLNode
if necessary).addNodes
in class AbstractHierarchicalFileConfiguration
key
- the key where the nodes are to be addednodes
- the collection with the new nodespublic void registerEntityId(String publicId, URL entityURL)
Registers the specified DTD URL for the specified public identifier.
XMLConfiguration
contains an internal
EntityResolver
implementation. This maps
PUBLICID
'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 every SYSTEM
URI on every processed XML document is
local. This implementation provides only basic functionality. If more
sophisticated features are required, using
setDocumentBuilder(DocumentBuilder)
to set a custom
DocumentBuilder
(which also can be initialized with a
custom EntityResolver
) is recommended.
Note: This method will have no effect when a custom
DocumentBuilder
has been set. (Setting a custom
DocumentBuilder
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 the load()
method can be invoked.
publicId
- Public identifier of the DTD to be resolvedentityURL
- The URL to use for reading this DTDIllegalArgumentException
- if the public ID is undefinedpublic InputSource resolveEntity(String publicId, String systemId) throws SAXException
EntityResolver
interface. It checks
the passed in public ID against the registered entity IDs and uses a
local URL if possible.resolveEntity
in interface EntityResolver
publicId
- the public identifier of the entity being referencedsystemId
- the system identifier of the entity being referencedSAXException
- if a parsing exception occursCopyright © 2018 JBoss by Red Hat. All rights reserved.