Class XMLConfiguration
- java.lang.Object
-
- org.apache.commons.configuration2.event.BaseEventSource
-
- org.apache.commons.configuration2.AbstractConfiguration
-
- org.apache.commons.configuration2.AbstractHierarchicalConfiguration<ImmutableNode>
-
- org.apache.commons.configuration2.BaseHierarchicalConfiguration
-
- org.apache.commons.configuration2.XMLConfiguration
-
- All Implemented Interfaces:
java.lang.Cloneable
,Configuration
,EventSource
,FileBasedConfiguration
,HierarchicalConfiguration<ImmutableNode>
,ImmutableConfiguration
,ImmutableHierarchicalConfiguration
,FileBased
,FileLocatorAware
,InputStreamSupport
,SynchronizerSupport
,InMemoryNodeModelSupport
,NodeKeyResolver<ImmutableNode>
,NodeModelSupport<ImmutableNode>
public class XMLConfiguration extends BaseHierarchicalConfiguration implements FileBasedConfiguration, FileLocatorAware, InputStreamSupport
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()
andload()
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 inPropertiesConfiguration
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 thearray
key will be assigned 4 values. In thescalar
property and thetext
attribute of thecite
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,XMLConfiguration
uses aListDelimiterHandler
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 alternativeListDelimiterHandler
implementation, this feature can be enabled. It works as for any other concreteConfiguration
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 tellXMLConfiguration
that spaces are relevant thexml: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 theFileBasedConfiguration
interface 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 aSynchronizer
object to control concurrent access. By choosing a suitable implementation of theSynchronizer
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 theSynchronizer
. 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 thelock()
andunlock()
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.- Since:
- 1.0
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) static class
XMLConfiguration.XMLBuilderVisitor
A concreteBuilderVisitor
that can construct XML documents.-
Nested classes/interfaces inherited from class org.apache.commons.configuration2.BaseHierarchicalConfiguration
BaseHierarchicalConfiguration.BuilderVisitor
-
-
Field Summary
Fields Modifier and Type Field Description private static java.lang.String
ATTR_SPACE
Constant for the name of the space attribute.private static java.lang.String
ATTR_SPACE_INTERNAL
Constant for an internally used space attribute.(package private) static int
DEFAULT_INDENT_SIZE
Constant for the default indent size.private static java.lang.String
DEFAULT_ROOT_NAME
Constant for the default root element name.private javax.xml.parsers.DocumentBuilder
documentBuilder
Stores the document builder that should be used for loading.private org.xml.sax.EntityResolver
entityResolver
The EntityResolver to use(package private) static java.lang.String
INDENT_AMOUNT_PROPERTY
Constant for output property name used on a transformer to specify the indent amount.private static java.lang.String
JAXP_SCHEMA_LANGUAGE
Schema Langauge key for the parserprivate FileLocator
locator
The current file locator.private java.lang.String
publicID
Stores the public ID from the DOCTYPE.private java.lang.String
rootElementName
Stores the name of the root element.private boolean
schemaValidation
Stores a flag whether DTD or Schema validation is usedprivate java.lang.String
systemID
Stores the system ID from the DOCTYPE.private boolean
validating
Stores a flag whether DTD or Schema validation should be performed.private static java.lang.String
VALUE_PRESERVE
Constant for the xml:space value for preserving whitespace.private static java.lang.String
W3C_XML_SCHEMA
Schema Language for the parser
-
Constructor Summary
Constructors Constructor Description XMLConfiguration()
Creates a new instance ofXMLConfiguration
.XMLConfiguration(HierarchicalConfiguration<ImmutableNode> c)
Creates a new instance ofXMLConfiguration
and copies the content of the passed in configuration into this object.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private java.util.Map<java.lang.String,java.lang.String>
constructHierarchy(ImmutableNode.Builder node, org.apache.commons.lang3.mutable.MutableObject<java.lang.String> refValue, org.w3c.dom.Element element, java.util.Map<ImmutableNode,java.lang.Object> elemRefs, boolean trim, int level)
Helper method for building the internal storage hierarchy.private static int
countChildElements(org.w3c.dom.Node parent, java.lang.String name)
Determines the number of child elements of this given node with the specified node name.private ImmutableNode
createChildNodeWithValue(ImmutableNode.Builder parent, ImmutableNode.Builder child, org.w3c.dom.Element elem, java.lang.String value, boolean trim, java.util.Map<java.lang.String,java.lang.String> attrmap, java.util.Map<ImmutableNode,java.lang.Object> elemRefs)
Creates a new child node, assigns its value, and adds it to its parent.private org.w3c.dom.Document
createDocument()
Creates a DOM document from the internal tree of configuration nodes.protected javax.xml.parsers.DocumentBuilder
createDocumentBuilder()
Creates theDocumentBuilder
to be used for loading files.protected javax.xml.transform.Transformer
createTransformer()
Creates and initializes the transformer used for save operations.private static java.lang.String
determineValue(java.lang.String content, boolean hasChildren, boolean trimFlag)
Determines the value of a configuration node.org.w3c.dom.Document
getDocument()
Gets the XML document this configuration was loaded from.javax.xml.parsers.DocumentBuilder
getDocumentBuilder()
Gets theDocumentBuilder
object that is used for loading documents.private XMLDocumentHelper
getDocumentHelper()
Gets the helper object for managing the underlying document.org.xml.sax.EntityResolver
getEntityResolver()
Gets the EntityResolver.java.lang.String
getPublicID()
Gets the public ID of the DOCTYPE declaration from the loaded XML document.private ReferenceNodeHandler
getReferenceHandler()
Gets the extended node handler with support for references.protected java.lang.String
getRootElementNameInternal()
Gets the name of the root element.java.lang.String
getSystemID()
Gets the system ID of the DOCTYPE declaration from the loaded XML document.void
initFileLocator(FileLocator loc)
Passes the currentFileLocator
to this object.private void
initProperties(XMLDocumentHelper docHelper, boolean elemRefs)
Initializes this configuration from an XML document.private void
initRootElementText(org.w3c.dom.Document doc, java.lang.Object value)
Sets the text of the root element of a newly created XML Document.boolean
isSchemaValidation()
Returns the value of the schemaValidation flag.private static boolean
isSingleElementList(org.w3c.dom.Element element)
Checks whether an element defines a complete list.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.private static java.util.Map<java.lang.String,java.lang.String>
processAttributes(org.w3c.dom.Element element)
Helper method for initializing the attributes of a configuration node from the given XML element.void
read(java.io.InputStream in)
Loads the configuration from the given input stream.void
read(java.io.Reader in)
Loads the configuration from the given reader.void
setDocumentBuilder(javax.xml.parsers.DocumentBuilder documentBuilder)
Sets theDocumentBuilder
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.private static boolean
shouldTrim(org.w3c.dom.Element element, boolean currentTrim)
Checks whether the content of the current XML element should be trimmed.void
validate()
Validate the document against the Schema.void
write(java.io.Writer writer)
Saves the configuration to the specified writer.void
write(java.io.Writer writer, javax.xml.transform.Transformer transformer)
Saves the configuration to the specified writer.-
Methods inherited from class org.apache.commons.configuration2.BaseHierarchicalConfiguration
childConfigurationsAt, childConfigurationsAt, cloneNodeModel, configurationAt, configurationAt, configurationsAt, configurationsAt, createSubConfigurationForTrackedNode, getNodeModel, getSubConfigurationNodeSelector, getSubConfigurationParentModel, immutableChildConfigurationsAt, immutableConfigurationAt, immutableConfigurationAt, immutableConfigurationsAt, initSubConfigurationForThisParent, interpolatedConfiguration, subnodeConfigurationChanged, subset
-
Methods inherited from class org.apache.commons.configuration2.AbstractHierarchicalConfiguration
addNodes, addNodesInternal, addPropertyDirect, addPropertyInternal, clearInternal, clearPropertyDirect, clearTree, clearTreeInternal, clone, containsKeyInternal, containsValueInternal, fetchNodeList, getExpressionEngine, getKeysInternal, getKeysInternal, getMaxIndex, getMaxIndexInternal, getModel, getPropertyInternal, getRootElementName, isEmptyInternal, nodeDefined, nodeKey, resolveAddKey, resolveKey, resolveNodeKey, resolveUpdateKey, setExpressionEngine, setPropertyInternal, sizeInternal, toString
-
Methods inherited from class org.apache.commons.configuration2.AbstractConfiguration
addErrorLogListener, addProperty, append, beginRead, beginWrite, clear, clearProperty, cloneInterpolator, contains, containsKey, containsValue, copy, endRead, endWrite, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getConfigurationDecoder, getConversionHandler, getDouble, getDouble, getDouble, getDuration, getDuration, getEncodedString, getEncodedString, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getKeys, getKeys, getKeys, getKeysInternal, getList, getList, getList, getList, getListDelimiterHandler, getLogger, getLong, getLong, getLong, getProperties, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, getSynchronizer, immutableSubset, initLogger, installInterpolator, interpolate, interpolate, isEmpty, isScalarValue, isThrowExceptionOnMissing, lock, setConfigurationDecoder, setConversionHandler, setDefaultLookups, setInterpolator, setListDelimiterHandler, setLogger, setParentInterpolator, setPrefixLookups, setProperty, setSynchronizer, setThrowExceptionOnMissing, size, unlock
-
Methods inherited from class org.apache.commons.configuration2.event.BaseEventSource
addEventListener, clearErrorListeners, clearEventListeners, copyEventListeners, createErrorEvent, createEvent, fireError, fireEvent, getEventListenerRegistrations, getEventListeners, isDetailEvents, removeEventListener, setDetailEvents
-
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
-
Methods inherited from interface org.apache.commons.configuration2.Configuration
addProperty, clear, clearProperty, getInterpolator, installInterpolator, setInterpolator, setProperty, subset
-
Methods inherited from interface org.apache.commons.configuration2.ImmutableConfiguration
containsKey, containsValue, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getDouble, getDouble, getDouble, getDuration, getDuration, getEncodedString, getEncodedString, getEnum, getEnum, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getKeys, getKeys, getList, getList, getList, getList, getLong, getLong, getLong, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, immutableSubset, isEmpty, size
-
Methods inherited from interface org.apache.commons.configuration2.sync.SynchronizerSupport
getSynchronizer, lock, setSynchronizer, unlock
-
-
-
-
Field Detail
-
DEFAULT_INDENT_SIZE
static final int DEFAULT_INDENT_SIZE
Constant for the default indent size.- See Also:
- Constant Field Values
-
INDENT_AMOUNT_PROPERTY
static final java.lang.String INDENT_AMOUNT_PROPERTY
Constant for output property name used on a transformer to specify the indent amount.- See Also:
- Constant Field Values
-
DEFAULT_ROOT_NAME
private static final java.lang.String DEFAULT_ROOT_NAME
Constant for the default root element name.- See Also:
- Constant Field Values
-
ATTR_SPACE
private static final java.lang.String ATTR_SPACE
Constant for the name of the space attribute.- See Also:
- Constant Field Values
-
ATTR_SPACE_INTERNAL
private static final java.lang.String ATTR_SPACE_INTERNAL
Constant for an internally used space attribute.- See Also:
- Constant Field Values
-
VALUE_PRESERVE
private static final java.lang.String VALUE_PRESERVE
Constant for the xml:space value for preserving whitespace.- See Also:
- Constant Field Values
-
JAXP_SCHEMA_LANGUAGE
private static final java.lang.String JAXP_SCHEMA_LANGUAGE
Schema Langauge key for the parser- See Also:
- Constant Field Values
-
W3C_XML_SCHEMA
private static final java.lang.String W3C_XML_SCHEMA
Schema Language for the parser- See Also:
- Constant Field Values
-
rootElementName
private java.lang.String rootElementName
Stores the name of the root element.
-
publicID
private java.lang.String publicID
Stores the public ID from the DOCTYPE.
-
systemID
private java.lang.String systemID
Stores the system ID from the DOCTYPE.
-
documentBuilder
private javax.xml.parsers.DocumentBuilder documentBuilder
Stores the document builder that should be used for loading.
-
validating
private boolean validating
Stores a flag whether DTD or Schema validation should be performed.
-
schemaValidation
private boolean schemaValidation
Stores a flag whether DTD or Schema validation is used
-
entityResolver
private org.xml.sax.EntityResolver entityResolver
The EntityResolver to use
-
locator
private FileLocator locator
The current file locator.
-
-
Constructor Detail
-
XMLConfiguration
public XMLConfiguration()
Creates a new instance ofXMLConfiguration
.
-
XMLConfiguration
public XMLConfiguration(HierarchicalConfiguration<ImmutableNode> c)
Creates a new instance ofXMLConfiguration
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 aXMLConfiguration
, too, things like comments or processing instructions will be lost.- Parameters:
c
- the configuration to copy- Since:
- 1.4
-
-
Method Detail
-
countChildElements
private static int countChildElements(org.w3c.dom.Node parent, java.lang.String name)
Determines the number of child elements of this given node with the specified node name.- Parameters:
parent
- the parent nodename
- the name in question- Returns:
- the number of child elements with this name
-
determineValue
private static java.lang.String determineValue(java.lang.String content, boolean hasChildren, boolean trimFlag)
Determines the value of a configuration node. This method mainly checks whether the text value is to be trimmed or not. This is normally defined by the trim flag. However, if the node has children and its content is only whitespace, then it makes no sense to store any value; this would only scramble layout when the configuration is saved again.- Parameters:
content
- the text content of this nodehasChildren
- a flag whether the node has childrentrimFlag
- the trim flag- Returns:
- the value to be stored for this node
-
isSingleElementList
private static boolean isSingleElementList(org.w3c.dom.Element element)
Checks whether an element defines a complete list. If this is the case, extended list handling can be applied.- Parameters:
element
- the element to be checked- Returns:
- a flag whether this is the only element defining the list
-
processAttributes
private static java.util.Map<java.lang.String,java.lang.String> processAttributes(org.w3c.dom.Element element)
Helper method for initializing the attributes of a configuration node from the given XML element.- Parameters:
element
- the current XML element- Returns:
- a map with all attribute values extracted for the current node
-
shouldTrim
private static boolean shouldTrim(org.w3c.dom.Element element, boolean currentTrim)
Checks whether the content of the current XML element should be trimmed. This method checks whether axml:space
attribute is present and evaluates its value. See http://www.w3.org/TR/REC-xml/#sec-white-space for more details.- Parameters:
element
- the current XML elementcurrentTrim
- the current trim flag- Returns:
- a flag whether the content of this element should be trimmed
-
constructHierarchy
private java.util.Map<java.lang.String,java.lang.String> constructHierarchy(ImmutableNode.Builder node, org.apache.commons.lang3.mutable.MutableObject<java.lang.String> refValue, org.w3c.dom.Element element, java.util.Map<ImmutableNode,java.lang.Object> elemRefs, boolean trim, int level)
Helper method for building the internal storage hierarchy. The XML elements are transformed into node objects.- Parameters:
node
- a builder for the current noderefValue
- stores the text value of the elementelement
- the current XML elementelemRefs
- a map for assigning references objects to nodes; can be null, then reference objects are irrelevanttrim
- a flag whether the text content of elements should be trimmed; this controls the whitespace handlinglevel
- the current level in the hierarchy- Returns:
- a map with all attribute values extracted for the current node; this map also contains the value of the trim flag for this node under the key "xml:space"
-
createChildNodeWithValue
private ImmutableNode createChildNodeWithValue(ImmutableNode.Builder parent, ImmutableNode.Builder child, org.w3c.dom.Element elem, java.lang.String value, boolean trim, java.util.Map<java.lang.String,java.lang.String> attrmap, java.util.Map<ImmutableNode,java.lang.Object> elemRefs)
Creates a new child node, assigns its value, and adds it to its parent. This method also deals with elements whose value is a list. In this case multiple child elements must be added. The return value is the first child node which was added.- Parameters:
parent
- the builder for the parent elementchild
- the builder for the child elementelem
- the associated XML elementvalue
- the value of the child elementtrim
- flag whether texts of elements should be trimmedattrmap
- a map with the attributes of the current nodeelemRefs
- a map for assigning references objects to nodes; can be null, then reference objects are irrelevant- Returns:
- the first child node added to the parent
-
createDocument
private org.w3c.dom.Document createDocument() throws ConfigurationException
Creates a DOM document from the internal tree of configuration nodes.- Returns:
- the new document
- Throws:
ConfigurationException
- if an error occurs
-
createDocumentBuilder
protected javax.xml.parsers.DocumentBuilder createDocumentBuilder() throws javax.xml.parsers.ParserConfigurationException
Creates theDocumentBuilder
to be used for loading files. This implementation checks whether a specificDocumentBuilder
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 validatingDocumentBuilder
.- Returns:
- the
DocumentBuilder
for loading configuration files - Throws:
javax.xml.parsers.ParserConfigurationException
- if an error occurs- Since:
- 1.2
-
createTransformer
protected javax.xml.transform.Transformer createTransformer() throws ConfigurationException
Creates and initializes the transformer used for save operations. This base implementation initializes all of the default settings like indentation mode and the DOCTYPE. Derived classes may overload this method if they have specific needs.- Returns:
- the transformer to use for a save operation
- Throws:
ConfigurationException
- if an error occurs- Since:
- 1.3
-
getDocument
public org.w3c.dom.Document getDocument()
Gets the XML document this configuration was loaded from. The return value is null if this configuration was not loaded from a XML document.- Returns:
- the XML document this configuration was loaded from
-
getDocumentBuilder
public javax.xml.parsers.DocumentBuilder getDocumentBuilder()
Gets theDocumentBuilder
object that is used for loading documents. If no specific builder has been set, this method returns null.- Returns:
- the
DocumentBuilder
for loading new documents - Since:
- 1.2
-
getDocumentHelper
private XMLDocumentHelper getDocumentHelper()
Gets the helper object for managing the underlying document.- Returns:
- the
XMLDocumentHelper
-
getEntityResolver
public org.xml.sax.EntityResolver getEntityResolver()
Gets the EntityResolver.- Returns:
- The EntityResolver.
- Since:
- 1.7
-
getPublicID
public java.lang.String getPublicID()
Gets the public ID of the DOCTYPE declaration from the loaded XML document. This is null if no document has been loaded yet or if the document does not contain a DOCTYPE declaration with a public ID.- Returns:
- the public ID
- Since:
- 1.3
-
getReferenceHandler
private ReferenceNodeHandler getReferenceHandler()
Gets the extended node handler with support for references.- Returns:
- the
ReferenceNodeHandler
-
getRootElementNameInternal
protected java.lang.String getRootElementNameInternal()
Gets the name of the root element. If this configuration was loaded from a XML document, the name of this document's root element is returned. Otherwise it is possible to set a name for the root element that will be used when this configuration is stored.- Overrides:
getRootElementNameInternal
in classAbstractHierarchicalConfiguration<ImmutableNode>
- Returns:
- the name of the root element
-
getSystemID
public java.lang.String getSystemID()
Gets the system ID of the DOCTYPE declaration from the loaded XML document. This is null if no document has been loaded yet or if the document does not contain a DOCTYPE declaration with a system ID.- Returns:
- the system ID
- Since:
- 1.3
-
initFileLocator
public void initFileLocator(FileLocator loc)
Passes the currentFileLocator
to this object. Note that thisFileLocator
object is only temporarily valid for the following invocation ofread()
orwrite(
. Depending on the state of theFileHandler
and which of its methods was called, the object may not be fully initialized. For instance, if theFileHandler
'sload(InputStream)
method was called, no file information is available, and all methods of theFileLocator
will return null. Stores the passed in locator for the upcoming IO operation.- Specified by:
initFileLocator
in interfaceFileLocatorAware
- Parameters:
loc
- the currentFileLocator
-
initProperties
private void initProperties(XMLDocumentHelper docHelper, boolean elemRefs)
Initializes this configuration from an XML document.- Parameters:
docHelper
- the helper object with the document to be parsedelemRefs
- a flag whether references to the XML elements should be set
-
initRootElementText
private void initRootElementText(org.w3c.dom.Document doc, java.lang.Object value)
Sets the text of the root element of a newly created XML Document.- Parameters:
doc
- the documentvalue
- the new text to be set
-
isSchemaValidation
public boolean isSchemaValidation()
Returns the value of the schemaValidation flag.- Returns:
- the schemaValidation flag
- Since:
- 1.7
-
isValidating
public boolean isValidating()
Returns the value of the validating flag.- Returns:
- the validating flag
- Since:
- 1.2
-
load
private void load(org.xml.sax.InputSource source) throws ConfigurationException
Loads a configuration file from the specified input source.- Parameters:
source
- the input source- Throws:
ConfigurationException
- if an error occurs
-
read
public void read(java.io.InputStream in) throws ConfigurationException, java.io.IOException
Loads the configuration from the given input stream. This is analogous toread(Reader)
, but data is read from a stream. Note that this method will be called most time when reading an XML configuration source. By reading XML documents directly from an input stream, the file's encoding can be correctly dealt with.- Specified by:
read
in interfaceInputStreamSupport
- Parameters:
in
- the input stream- Throws:
ConfigurationException
- if an error occursjava.io.IOException
- if an IO error occurs
-
read
public void read(java.io.Reader in) throws ConfigurationException, java.io.IOException
Loads the configuration from the given reader. Note that theclear()
method is not called, so the properties contained in the loaded file will be added to the current set of properties.- Specified by:
read
in interfaceFileBased
- Parameters:
in
- the reader- Throws:
ConfigurationException
- if an error occursjava.io.IOException
- if an IO error occurs
-
setDocumentBuilder
public void setDocumentBuilder(javax.xml.parsers.DocumentBuilder documentBuilder)
Sets theDocumentBuilder
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.- Parameters:
documentBuilder
- the document builder to be used; if undefined, a default builder will be used- Since:
- 1.2
-
setEntityResolver
public void setEntityResolver(org.xml.sax.EntityResolver resolver)
Sets a new EntityResolver. Setting this will cause RegisterEntityId to have no effect.- Parameters:
resolver
- The EntityResolver to use.- Since:
- 1.7
-
setPublicID
public void setPublicID(java.lang.String publicID)
Sets the public ID of the DOCTYPE declaration. When this configuration is saved, a DOCTYPE declaration will be constructed that contains this public ID.- Parameters:
publicID
- the public ID- Since:
- 1.3
-
setRootElementName
public void setRootElementName(java.lang.String name)
Sets the name of the root element. This name is used when this configuration object is stored in an XML file. Note that setting the name of the root element works only if this configuration has been newly created. If the configuration was loaded from an XML file, the name cannot be changed and anUnsupportedOperationException
exception is thrown. Whether this configuration has been loaded from an XML document or not can be found out using thegetDocument()
method.- Parameters:
name
- the name of the root element
-
setSchemaValidation
public void setSchemaValidation(boolean schemaValidation)
Sets the value of the schemaValidation flag. This flag determines whether DTD or Schema validation should be used. This flag is evaluated only if no customDocumentBuilder
was set. If set to true the XML document must contain a schemaLocation definition that provides resolvable hints to the required schemas.- Parameters:
schemaValidation
- the validating flag- Since:
- 1.7
-
setSystemID
public void setSystemID(java.lang.String systemID)
Sets the system ID of the DOCTYPE declaration. When this configuration is saved, a DOCTYPE declaration will be constructed that contains this system ID.- Parameters:
systemID
- the system ID- Since:
- 1.3
-
setValidating
public void setValidating(boolean validating)
Sets the value of the validating flag. This flag determines whether DTD/Schema validation should be performed when loading XML documents. This flag is evaluated only if no customDocumentBuilder
was set.- Parameters:
validating
- the validating flag- Since:
- 1.2
-
validate
public void validate() throws ConfigurationException
Validate the document against the Schema.- Throws:
ConfigurationException
- if the validation fails.
-
write
public void write(java.io.Writer writer) throws ConfigurationException, java.io.IOException
Saves the configuration to the specified writer.- Specified by:
write
in interfaceFileBased
- Parameters:
writer
- the writer used to save the configuration- Throws:
ConfigurationException
- if an error occursjava.io.IOException
- if an IO error occurs
-
write
public void write(java.io.Writer writer, javax.xml.transform.Transformer transformer) throws ConfigurationException
Saves the configuration to the specified writer.- Parameters:
writer
- the writer used to save the configuration.transformer
- How to transform this configuration.- Throws:
ConfigurationException
- if an error occurs.- Since:
- 2.7.0
-
-