public class XMLConfiguration extends AbstractHierarchicalFileConfiguration implements org.xml.sax.EntityResolver, EntityRegistry
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.
AbstractHierarchicalFileConfiguration.FileConfigurationDelegateHierarchicalConfiguration.BuilderVisitor, HierarchicalConfiguration.Node, HierarchicalConfiguration.NodeVisitorEVENT_ADD_NODES, EVENT_CLEAR_TREE, EVENT_SUBNODE_CHANGEDEND_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(java.io.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(java.lang.String fileName)
Creates a new instance of
XMLConfiguration. |
XMLConfiguration(java.net.URL url)
Creates a new instance of
XMLConfiguration. |
| Modifier and Type | Method and Description |
|---|---|
void |
addNodes(java.lang.String key,
java.util.Collection<? extends ConfigurationNode> nodes)
Adds a collection of nodes directly to this configuration.
|
void |
clear()
Removes all properties from this configuration.
|
java.lang.Object |
clone()
Creates a copy of this object.
|
protected AbstractHierarchicalFileConfiguration.FileConfigurationDelegate |
createDelegate()
Creates the file configuration delegate for this object.
|
protected org.w3c.dom.Document |
createDocument()
Creates a DOM document from the internal tree of configuration nodes.
|
protected javax.xml.parsers.DocumentBuilder |
createDocumentBuilder()
Creates the
DocumentBuilder to be used for loading files. |
protected HierarchicalConfiguration.Node |
createNode(java.lang.String name)
Creates a new node object.
|
protected javax.xml.transform.Transformer |
createTransformer()
Creates and initializes the transformer used for save operations.
|
org.w3c.dom.Document |
getDocument()
Returns the XML document this configuration was loaded from.
|
javax.xml.parsers.DocumentBuilder |
getDocumentBuilder()
Returns the
DocumentBuilder object that is used for
loading documents. |
org.xml.sax.EntityResolver |
getEntityResolver()
Returns the EntityResolver.
|
java.lang.String |
getPublicID()
Returns the public ID of the DOCTYPE declaration from the loaded XML
document.
|
java.util.Map<java.lang.String,java.net.URL> |
getRegisteredEntities()
Returns a map with the entity IDs that have been registered using the
registerEntityId() method. |
java.lang.String |
getRootElementName()
Returns the name of the root element.
|
java.lang.String |
getSystemID()
Returns the system ID of the DOCTYPE declaration from the loaded XML
document.
|
void |
initProperties(org.w3c.dom.Document document,
boolean elemRefs)
Initializes this configuration from an XML document.
|
boolean |
isAttributeSplittingDisabled()
Returns the flag whether attribute splitting is disabled.
|
boolean |
isSchemaValidation()
Returns the value of the schemaValidation flag.
|
boolean |
isValidating()
Returns the value of the validating flag.
|
void |
load(java.io.InputStream in)
Loads the configuration from the given input stream.
|
void |
load(java.io.Reader in)
Load the configuration from the given reader.
|
void |
registerEntityId(java.lang.String publicId,
java.net.URL entityURL)
Registers the specified DTD URL for the specified public identifier.
|
org.xml.sax.InputSource |
resolveEntity(java.lang.String publicId,
java.lang.String systemId)
Deprecated.
Use getEntityResolver().resolveEntity()
|
void |
save(java.io.Writer writer)
Saves the configuration to the specified writer.
|
void |
setAttributeSplittingDisabled(boolean attributeSplittingDisabled)
Sets a flag whether attribute splitting is disabled.
|
void |
setDocumentBuilder(javax.xml.parsers.DocumentBuilder documentBuilder)
Sets the
DocumentBuilder object to be used for loading
documents. |
void |
setEntityResolver(org.xml.sax.EntityResolver resolver)
Sets a new EntityResolver.
|
void |
setPublicID(java.lang.String publicID)
Sets the public ID of the DOCTYPE declaration.
|
void |
setRootElementName(java.lang.String name)
Sets the name of the root element.
|
void |
setSchemaValidation(boolean schemaValidation)
Sets the value of the schemaValidation flag.
|
void |
setSystemID(java.lang.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.
|
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, subnodeConfigurationChangedclearNode, 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, subsetaddErrorLogListener, 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, setThrowExceptionOnMissingaddConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, createErrorEvent, createEvent, fireError, fireEvent, getConfigurationListeners, getErrorListeners, isDetailEvents, removeConfigurationListener, removeErrorListener, setDetailEventsequals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitaddProperty, 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, subsetpublic 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(java.lang.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(java.io.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(java.net.URL url) throws ConfigurationException
XMLConfiguration.
The configuration is loaded from the specified URL.url - the URLConfigurationException - if loading causes an errorpublic java.lang.String getRootElementName()
public void setRootElementName(java.lang.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 javax.xml.parsers.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(javax.xml.parsers.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 java.lang.String getPublicID()
public void setPublicID(java.lang.String publicID)
publicID - the public IDpublic java.lang.String getSystemID()
public void setSystemID(java.lang.String systemID)
systemID - the system IDpublic boolean isValidating()
public void setValidating(boolean validating)
DocumentBuilder was set.validating - the validating flagpublic boolean isSchemaValidation()
public void setSchemaValidation(boolean schemaValidation)
DocumentBuilder was set.
If set to true the XML document must contain a schemaLocation definition
that provides resolvable hints to the required schemas.schemaValidation - the validating flagpublic void setEntityResolver(org.xml.sax.EntityResolver resolver)
resolver - The EntityResolver to use.public org.xml.sax.EntityResolver getEntityResolver()
public 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 org.w3c.dom.Document getDocument()
public void clear()
clear in interface Configurationclear in class HierarchicalConfigurationpublic void initProperties(org.w3c.dom.Document document, boolean elemRefs)
document - the document to be parsedelemRefs - a flag whether references to the XML elements should be setprotected javax.xml.parsers.DocumentBuilder createDocumentBuilder() throws javax.xml.parsers.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
filesjavax.xml.parsers.ParserConfigurationException - if an error occursprotected org.w3c.dom.Document createDocument() throws ConfigurationException
ConfigurationException - if an error occursprotected HierarchicalConfiguration.Node createNode(java.lang.String name)
XMLNode class.createNode in class HierarchicalConfigurationname - the node's namepublic void load(java.io.InputStream in) throws ConfigurationException
load in interface FileConfigurationload in class AbstractHierarchicalFileConfigurationin - the input streamConfigurationException - if an error occurspublic void load(java.io.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 FileConfigurationin - An InputStream.ConfigurationException - if an error occurspublic void save(java.io.Writer writer) throws ConfigurationException
save in interface FileConfigurationwriter - the writer used to save the configurationConfigurationException - if an error occurspublic void validate() throws ConfigurationException
ConfigurationException - if the validation fails.protected javax.xml.transform.Transformer createTransformer() throws javax.xml.transform.TransformerException
javax.xml.transform.TransformerException - if an error occurspublic java.lang.Object clone()
clone in class HierarchicalConfigurationprotected AbstractHierarchicalFileConfiguration.FileConfigurationDelegate createDelegate()
FileConfigurationDelegate
that deals with some specialties of XMLConfiguration.createDelegate in class AbstractHierarchicalFileConfigurationpublic void addNodes(java.lang.String key, java.util.Collection<? extends ConfigurationNode> nodes)
XMLNode if necessary).addNodes in class AbstractHierarchicalFileConfigurationkey - the key where the nodes are to be addednodes - the collection with the new nodespublic void registerEntityId(java.lang.String publicId, java.net.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.
registerEntityId in interface EntityRegistrypublicId - Public identifier of the DTD to be resolvedentityURL - The URL to use for reading this DTDjava.lang.IllegalArgumentException - if the public ID is undefined@Deprecated public org.xml.sax.InputSource resolveEntity(java.lang.String publicId, java.lang.String systemId) throws org.xml.sax.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 org.xml.sax.EntityResolverpublicId - the public identifier of the entity being referencedsystemId - the system identifier of the entity being referencedorg.xml.sax.SAXException - if a parsing exception occurspublic java.util.Map<java.lang.String,java.net.URL> getRegisteredEntities()
registerEntityId() method.getRegisteredEntities in interface EntityRegistry