Class XMLDocumentHelper
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 -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate static Document
copyDocument
(Document doc) Creates a copy of the specified document.Creates a copy of this object.(package private) static DocumentBuilder
Creates a newDocumentBuilder
using the specified factory.private static DocumentBuilderFactory
Creates a newDocumentBuilderFactory
instance.createElementMapping
(Document doc1, Document doc2) Creates the element mapping for the specified documents.private static void
Creates the element mapping for the specified nodes and all their child nodes.static Transformer
Creates a newTransformer
object.(package private) static Transformer
createTransformer
(TransformerFactory factory) Creates aTransformer
using the specified factory.(package private) static TransformerFactory
Creates a newTransformerFactory
.Creates an empty element mapping.static XMLDocumentHelper
forNewDocument
(String rootElementName) Creates a new instance ofXMLDocumentHelper
and initializes it with a newly created, emptyDocument
.static XMLDocumentHelper
forSourceDocument
(Document srcDoc) Creates a new instance ofXMLDocumentHelper
and initializes it with a source document.Gets theDocument
managed by this helper.Gets the element mapping to the source document.Gets the public ID of the source document.Gets the system ID of the source document.static void
transform
(Transformer transformer, Source source, Result result) Performs an XSL transformation on the passed in operands.
-
Field Details
-
document
Stores the document managed by this instance. -
elementMapping
The element mapping to the source document. -
sourcePublicID
Stores the public ID of the source document. -
sourceSystemID
Stores the system ID of the source document.
-
-
Constructor Details
-
XMLDocumentHelper
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 Details
-
copyDocument
Creates a copy of the specified document.- Parameters:
doc
- theDocument
- Returns:
- the copy of this document
- Throws:
ConfigurationException
- if an error occurs
-
createDocumentBuilder
static DocumentBuilder createDocumentBuilder(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
Creates a newDocumentBuilderFactory
instance.- Returns:
- the new factory object
-
createElementMapping
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
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
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
Creates aTransformer
using the specified factory.- Parameters:
factory
- theTransformerFactory
- Returns:
- the newly created
Transformer
- Throws:
ConfigurationException
- if an error occurs
-
createTransformerFactory
Creates a newTransformerFactory
.- Returns:
- the
TransformerFactory
-
emptyElementMapping
Creates an empty element mapping.- Returns:
- the empty mapping
-
forNewDocument
public static XMLDocumentHelper forNewDocument(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
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(Transformer transformer, Source source, 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
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
Gets theDocument
managed by this helper.- Returns:
- the wrapped
Document
-
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
Gets the public ID of the source document.- Returns:
- the public ID of the source document
-
getSourceSystemID
Gets the system ID of the source document.- Returns:
- the system ID of the source document
-