|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.apache.commons.configuration.event.EventSource
org.apache.commons.configuration.AbstractConfiguration
org.apache.commons.configuration.HierarchicalConfiguration
org.apache.commons.configuration.AbstractHierarchicalFileConfiguration
org.apache.commons.configuration.XMLConfiguration
public class XMLConfiguration
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.
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.
Nested Class Summary | |
---|---|
(package private) static class |
XMLConfiguration.XMLBuilderVisitor
A concrete BuilderVisitor that can construct XML
documents. |
private class |
XMLConfiguration.XMLFileConfigurationDelegate
A special implementation of the FileConfiguration interface that is
used internally to implement the FileConfiguration methods
for XMLConfiguration , too. |
(package private) class |
XMLConfiguration.XMLNode
A specialized Node class that is connected with an XML
element. |
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.CloneVisitor, HierarchicalConfiguration.DefinedKeysVisitor, HierarchicalConfiguration.DefinedVisitor, HierarchicalConfiguration.Node, HierarchicalConfiguration.NodeVisitor |
Field Summary | |
---|---|
private static char |
ATTR_VALUE_DELIMITER
Constant for the delimiter for multiple attribute values. |
private static java.lang.String |
DEFAULT_ROOT_NAME
Constant for the default root element name. |
private org.w3c.dom.Document |
document
The document from this configuration's data source. |
private javax.xml.parsers.DocumentBuilder |
documentBuilder
Stores the document builder that should be used for loading. |
private java.lang.String |
publicID
Stores the public ID from the DOCTYPE. |
private java.util.Map |
registeredEntities
Stores a map with the registered public IDs. |
private java.lang.String |
rootElementName
Stores the name of the root element. |
private static long |
serialVersionUID
The serial version UID. |
private java.lang.String |
systemID
Stores the system ID from the DOCTYPE. |
private boolean |
validating
Stores a flag whether DTD validation should be performed. |
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 | |
---|---|
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 . |
Method Summary | |
---|---|
void |
addNodes(java.lang.String key,
java.util.Collection 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. |
private void |
constructHierarchy(HierarchicalConfiguration.Node node,
org.w3c.dom.Element element,
boolean elemRefs)
Helper method for building the internal storage hierarchy. |
private XMLConfiguration.XMLNode |
convertToXMLNode(ConfigurationNode node)
Converts the specified node into a XMLNode if necessary. |
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. |
java.lang.String |
getPublicID()
Returns the public ID of the DOCTYPE declaration from the loaded XML document. |
(package private) java.util.Map |
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. |
private void |
handleDelimiters(HierarchicalConfiguration.Node parent,
HierarchicalConfiguration.Node child)
Deals with elements whose value is a list. |
void |
initProperties(org.w3c.dom.Document document,
boolean elemRefs)
Initializes this configuration from an XML document. |
boolean |
isValidating()
Returns the value of the validating flag. |
private void |
load(org.xml.sax.InputSource source)
Loads a configuration file from the specified input source. |
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. |
private void |
processAttributes(HierarchicalConfiguration.Node node,
org.w3c.dom.Element element,
boolean elemRefs)
Helper method for constructing node objects for the attributes of the given XML element. |
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)
Resolves the requested external entity. |
void |
save(java.io.Writer writer)
Saves the configuration to the specified writer. |
void |
setDocumentBuilder(javax.xml.parsers.DocumentBuilder documentBuilder)
Sets the DocumentBuilder object to be used for loading
documents. |
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 |
setSystemID(java.lang.String systemID)
Sets the system ID of the DOCTYPE declaration. |
void |
setValidating(boolean validating)
Sets the value of the validating flag. |
Methods inherited from class org.apache.commons.configuration.AbstractHierarchicalFileConfiguration |
---|
addPropertyDirect, clearProperty, clearTree, configurationChanged, containsKey, fetchNodeList, getBasePath, getDelegate, getEncoding, getFile, getFileName, 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 |
Methods inherited from class org.apache.commons.configuration.HierarchicalConfiguration |
---|
clearNode, clearNode, clearReferences, configurationAt, configurationAt, configurationsAt, createAddPath, createSubnodeConfiguration, createSubnodeConfiguration, fetchAddNode, findLastPathNode, findPropertyNodes, getDefaultExpressionEngine, getExpressionEngine, getKeys, getMaxIndex, getRoot, getRootNode, interpolatedConfiguration, nodeDefined, nodeDefined, registerSubnodeConfiguration, removeNode, removeNode, setDefaultExpressionEngine, setExpressionEngine, setRoot, setRootNode, subset |
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, getKeys, getList, getList, getLong, getLong, getLong, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, subset |
Field Detail |
---|
private static final long serialVersionUID
private static final java.lang.String DEFAULT_ROOT_NAME
private static final char ATTR_VALUE_DELIMITER
private org.w3c.dom.Document document
private java.util.Map registeredEntities
private java.lang.String rootElementName
private java.lang.String publicID
private java.lang.String systemID
private javax.xml.parsers.DocumentBuilder documentBuilder
private boolean validating
Constructor Detail |
---|
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(java.lang.String fileName) throws ConfigurationException
XMLConfiguration
. The
configuration is loaded from the specified file
fileName
- the name of the file to load
ConfigurationException
- if the file cannot be loadedpublic XMLConfiguration(java.io.File file) throws ConfigurationException
XMLConfiguration
.
The configuration is loaded from the specified file.
file
- the file
ConfigurationException
- 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 URL
ConfigurationException
- if loading causes an errorMethod Detail |
---|
public 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 org.w3c.dom.Document getDocument()
public void clear()
clear
in interface Configuration
clear
in class AbstractConfiguration
public 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 setprivate void constructHierarchy(HierarchicalConfiguration.Node node, org.w3c.dom.Element element, boolean elemRefs)
node
- the actual nodeelement
- the actual XML elementelemRefs
- a flag whether references to the XML elements should be setprivate void processAttributes(HierarchicalConfiguration.Node node, org.w3c.dom.Element element, boolean elemRefs)
node
- the actual nodeelement
- the actual XML elementelemRefs
- a flag whether references to the XML elements should be setprivate void handleDelimiters(HierarchicalConfiguration.Node parent, HierarchicalConfiguration.Node child)
parent
- the parent elementchild
- the child elementprotected 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
files
javax.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 HierarchicalConfiguration
name
- the node's name
public void load(java.io.InputStream in) throws ConfigurationException
load
in interface FileConfiguration
load
in class AbstractHierarchicalFileConfiguration
in
- the input stream
ConfigurationException
- 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 FileConfiguration
in
- An InputStream.
ConfigurationException
- if an error occursprivate void load(org.xml.sax.InputSource source) throws ConfigurationException
source
- the input source
ConfigurationException
- if an error occurspublic void save(java.io.Writer writer) throws ConfigurationException
save
in interface FileConfiguration
writer
- the writer used to save the configuration
ConfigurationException
- if an error occursprotected 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 HierarchicalConfiguration
protected AbstractHierarchicalFileConfiguration.FileConfigurationDelegate createDelegate()
FileConfigurationDelegate
that deals with some specialities of XMLConfiguration
.
createDelegate
in class AbstractHierarchicalFileConfiguration
public void addNodes(java.lang.String key, java.util.Collection nodes)
XMLNode
if necessary).
addNodes
in class AbstractHierarchicalFileConfiguration
key
- the key where the nodes are to be addednodes
- the collection with the new nodesprivate XMLConfiguration.XMLNode convertToXMLNode(ConfigurationNode node)
XMLNode
if necessary.
This is required for nodes that are directly added, e.g. by
addNodes()
. If the passed in node is already an instance
of XMLNode
, it is directly returned, and conversion
stops. Otherwise a new XMLNode
is created, and the
children are also converted.
node
- the node to be converted
public 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.
publicId
- Public identifier of the DTD to be resolvedentityURL
- The URL to use for reading this DTD
java.lang.IllegalArgumentException
- if the public ID is undefinedpublic 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.EntityResolver
publicId
- the public identifier of the entity being referencedsystemId
- the system identifier of the entity being referenced
org.xml.sax.SAXException
- if a parsing exception occursjava.util.Map getRegisteredEntities()
registerEntityId()
method.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |