Class XMLDocumentHelper
- java.lang.Object
-
- org.apache.commons.configuration2.XMLDocumentHelper
-
final class XMLDocumentHelper extends java.lang.Object
An internally used helper class for dealing with XML documents.
This class is used by
XMLConfiguration
. It provides some basic functionality for processing DOM documents and dealing with elements. The main idea is that an instance holds the XML document associated with a XML configuration object. When the configuration is to be saved the document has to be manipulated according to the changes made on the configuration. To ensure that this is possible even under concurrent access, a new temporary instance is created as a copy of the original instance. Then, on this copy, the changes of the configuration are applied. The resulting document can then be serialized.Nodes of an
XMLConfiguration
that was read from a file are associated with the XML elements they represent. In order to apply changes on the copied document, it is necessary to establish a mapping between the elements of the old document and the elements of the copied document. This is also handled by this class.- Since:
- 2.0
-
-
Field Summary
Fields Modifier and Type Field Description private org.w3c.dom.Document
document
Stores the document managed by this instance.private java.util.Map<org.w3c.dom.Node,org.w3c.dom.Node>
elementMapping
The element mapping to the source document.private java.lang.String
sourcePublicID
Stores the public ID of the source document.private java.lang.String
sourceSystemID
Stores the system ID of the source document.
-
Constructor Summary
Constructors Constructor Description XMLDocumentHelper(org.w3c.dom.Document doc, java.util.Map<org.w3c.dom.Node,org.w3c.dom.Node> elemMap, java.lang.String pubID, java.lang.String sysID)
Creates a new instance ofXMLDocumentHelper
and initializes it with the given XML document.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private static org.w3c.dom.Document
copyDocument(org.w3c.dom.Document doc)
Creates a copy of the specified document.XMLDocumentHelper
createCopy()
Creates a copy of this object.(package private) static javax.xml.parsers.DocumentBuilder
createDocumentBuilder(javax.xml.parsers.DocumentBuilderFactory factory)
Creates a newDocumentBuilder
using the specified factory.private static javax.xml.parsers.DocumentBuilderFactory
createDocumentBuilderFactory()
Creates a newDocumentBuilderFactory
instance.private static java.util.Map<org.w3c.dom.Node,org.w3c.dom.Node>
createElementMapping(org.w3c.dom.Document doc1, org.w3c.dom.Document doc2)
Creates the element mapping for the specified documents.private static void
createElementMappingForNodes(org.w3c.dom.Node n1, org.w3c.dom.Node n2, java.util.Map<org.w3c.dom.Node,org.w3c.dom.Node> mapping)
Creates the element mapping for the specified nodes and all their child nodes.static javax.xml.transform.Transformer
createTransformer()
Creates a newTransformer
object.(package private) static javax.xml.transform.Transformer
createTransformer(javax.xml.transform.TransformerFactory factory)
Creates aTransformer
using the specified factory.(package private) static javax.xml.transform.TransformerFactory
createTransformerFactory()
Creates a newTransformerFactory
.private static java.util.Map<org.w3c.dom.Node,org.w3c.dom.Node>
emptyElementMapping()
Creates an empty element mapping.static XMLDocumentHelper
forNewDocument(java.lang.String rootElementName)
Creates a new instance ofXMLDocumentHelper
and initializes it with a newly created, emptyDocument
.static XMLDocumentHelper
forSourceDocument(org.w3c.dom.Document srcDoc)
Creates a new instance ofXMLDocumentHelper
and initializes it with a source document.org.w3c.dom.Document
getDocument()
Gets theDocument
managed by this helper.java.util.Map<org.w3c.dom.Node,org.w3c.dom.Node>
getElementMapping()
Gets the element mapping to the source document.java.lang.String
getSourcePublicID()
Gets the public ID of the source document.java.lang.String
getSourceSystemID()
Gets the system ID of the source document.static void
transform(javax.xml.transform.Transformer transformer, javax.xml.transform.Source source, javax.xml.transform.Result result)
Performs an XSL transformation on the passed in operands.
-
-
-
Field Detail
-
document
private final org.w3c.dom.Document document
Stores the document managed by this instance.
-
elementMapping
private final java.util.Map<org.w3c.dom.Node,org.w3c.dom.Node> elementMapping
The element mapping to the source document.
-
sourcePublicID
private final java.lang.String sourcePublicID
Stores the public ID of the source document.
-
sourceSystemID
private final java.lang.String sourceSystemID
Stores the system ID of the source document.
-
-
Constructor Detail
-
XMLDocumentHelper
XMLDocumentHelper(org.w3c.dom.Document doc, java.util.Map<org.w3c.dom.Node,org.w3c.dom.Node> elemMap, java.lang.String pubID, java.lang.String sysID)
Creates a new instance ofXMLDocumentHelper
and initializes it with the given XML document. Note: This constructor is package private only for testing purposes. Instances should be created using the static factory methods.- Parameters:
doc
- theDocument
elemMap
- the element mappingpubID
- the public ID of the source documentsysID
- the system ID of the source document
-
-
Method Detail
-
copyDocument
private static org.w3c.dom.Document copyDocument(org.w3c.dom.Document doc) throws ConfigurationException
Creates a copy of the specified document.- Parameters:
doc
- theDocument
- Returns:
- the copy of this document
- Throws:
ConfigurationException
- if an error occurs
-
createDocumentBuilder
static javax.xml.parsers.DocumentBuilder createDocumentBuilder(javax.xml.parsers.DocumentBuilderFactory factory) throws ConfigurationException
Creates a newDocumentBuilder
using the specified factory. Exceptions are rethrown asConfigurationException
exceptions.- Parameters:
factory
- theDocumentBuilderFactory
- Returns:
- the newly created
DocumentBuilder
- Throws:
ConfigurationException
- if an error occurs
-
createDocumentBuilderFactory
private static javax.xml.parsers.DocumentBuilderFactory createDocumentBuilderFactory()
Creates a newDocumentBuilderFactory
instance.- Returns:
- the new factory object
-
createElementMapping
private static java.util.Map<org.w3c.dom.Node,org.w3c.dom.Node> createElementMapping(org.w3c.dom.Document doc1, org.w3c.dom.Document doc2)
Creates the element mapping for the specified documents. For each node in the source document an entry is created pointing to the corresponding node in the destination object.- Parameters:
doc1
- the source documentdoc2
- the destination document- Returns:
- the element mapping
-
createElementMappingForNodes
private static void createElementMappingForNodes(org.w3c.dom.Node n1, org.w3c.dom.Node n2, java.util.Map<org.w3c.dom.Node,org.w3c.dom.Node> mapping)
Creates the element mapping for the specified nodes and all their child nodes.- Parameters:
n1
- node 1n2
- node 2mapping
- the mapping to be filled
-
createTransformer
public static javax.xml.transform.Transformer createTransformer() throws ConfigurationException
Creates a newTransformer
object. No initializations are performed on the new instance.- Returns:
- the new
Transformer
- Throws:
ConfigurationException
- if theTransformer
could not be created
-
createTransformer
static javax.xml.transform.Transformer createTransformer(javax.xml.transform.TransformerFactory factory) throws ConfigurationException
Creates aTransformer
using the specified factory.- Parameters:
factory
- theTransformerFactory
- Returns:
- the newly created
Transformer
- Throws:
ConfigurationException
- if an error occurs
-
createTransformerFactory
static javax.xml.transform.TransformerFactory createTransformerFactory()
Creates a newTransformerFactory
.- Returns:
- the
TransformerFactory
-
emptyElementMapping
private static java.util.Map<org.w3c.dom.Node,org.w3c.dom.Node> emptyElementMapping()
Creates an empty element mapping.- Returns:
- the empty mapping
-
forNewDocument
public static XMLDocumentHelper forNewDocument(java.lang.String rootElementName) throws ConfigurationException
Creates a new instance ofXMLDocumentHelper
and initializes it with a newly created, emptyDocument
. The new document has a root element with the given element name. This element has no further child nodes.- Parameters:
rootElementName
- the name of the root element- Returns:
- the newly created instance
- Throws:
ConfigurationException
- if an error occurs when creating the document
-
forSourceDocument
public static XMLDocumentHelper forSourceDocument(org.w3c.dom.Document srcDoc) throws ConfigurationException
Creates a new instance ofXMLDocumentHelper
and initializes it with a source document. This is a document created from a configuration file. It is kept in memory so that the configuration can be saved with the same format. Note that already a copy of this document is created. This is done for the following reasons:- It is a defensive copy.
- An identity transformation on a document may change certain nodes, e.g. CDATA sections. When later on again copies of this document are created it has to be ensured that these copies have the same structure than the original document stored in this instance.
- Parameters:
srcDoc
- the source document- Returns:
- the newly created instance
- Throws:
ConfigurationException
- if an error occurs
-
transform
public static void transform(javax.xml.transform.Transformer transformer, javax.xml.transform.Source source, javax.xml.transform.Result result) throws ConfigurationException
Performs an XSL transformation on the passed in operands. All possible exceptions are caught and redirected asConfigurationException
exceptions.- Parameters:
transformer
- the transformersource
- the sourceresult
- the result- Throws:
ConfigurationException
- if an error occurs
-
createCopy
public XMLDocumentHelper createCopy() throws ConfigurationException
Creates a copy of this object. This copy contains a copy of the document and an element mapping which allows mapping elements from the source document to elements of the copied document.- Returns:
- the copy
- Throws:
ConfigurationException
- if an error occurs
-
getDocument
public org.w3c.dom.Document getDocument()
Gets theDocument
managed by this helper.- Returns:
- the wrapped
Document
-
getElementMapping
public java.util.Map<org.w3c.dom.Node,org.w3c.dom.Node> getElementMapping()
Gets the element mapping to the source document. This map can be used to obtain elements in the managed document which correspond to elements in the source document. If this instance has not been created from a source document, the mapping is empty.- Returns:
- the element mapping to the source document
-
getSourcePublicID
public java.lang.String getSourcePublicID()
Gets the public ID of the source document.- Returns:
- the public ID of the source document
-
getSourceSystemID
public java.lang.String getSourceSystemID()
Gets the system ID of the source document.- Returns:
- the system ID of the source document
-
-