Class 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 of XMLDocumentHelper 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 new DocumentBuilder using the specified factory.
      private static javax.xml.parsers.DocumentBuilderFactory createDocumentBuilderFactory()
      Creates a new DocumentBuilderFactory 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 new Transformer object.
      (package private) static javax.xml.transform.Transformer createTransformer​(javax.xml.transform.TransformerFactory factory)
      Creates a Transformer using the specified factory.
      (package private) static javax.xml.transform.TransformerFactory createTransformerFactory()
      Creates a new TransformerFactory.
      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 of XMLDocumentHelper and initializes it with a newly created, empty Document.
      static XMLDocumentHelper forSourceDocument​(org.w3c.dom.Document srcDoc)
      Creates a new instance of XMLDocumentHelper and initializes it with a source document.
      org.w3c.dom.Document getDocument()
      Gets the Document 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.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • 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 of XMLDocumentHelper 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 - the Document
        elemMap - the element mapping
        pubID - the public ID of the source document
        sysID - 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 - the Document
        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 new DocumentBuilder using the specified factory. Exceptions are rethrown as ConfigurationException exceptions.
        Parameters:
        factory - the DocumentBuilderFactory
        Returns:
        the newly created DocumentBuilder
        Throws:
        ConfigurationException - if an error occurs
      • createDocumentBuilderFactory

        private static javax.xml.parsers.DocumentBuilderFactory createDocumentBuilderFactory()
        Creates a new DocumentBuilderFactory 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 document
        doc2 - 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 1
        n2 - node 2
        mapping - the mapping to be filled
      • createTransformer

        public static javax.xml.transform.Transformer createTransformer()
                                                                 throws ConfigurationException
        Creates a new Transformer object. No initializations are performed on the new instance.
        Returns:
        the new Transformer
        Throws:
        ConfigurationException - if the Transformer could not be created
      • createTransformer

        static javax.xml.transform.Transformer createTransformer​(javax.xml.transform.TransformerFactory factory)
                                                          throws ConfigurationException
        Creates a Transformer using the specified factory.
        Parameters:
        factory - the TransformerFactory
        Returns:
        the newly created Transformer
        Throws:
        ConfigurationException - if an error occurs
      • createTransformerFactory

        static javax.xml.transform.TransformerFactory createTransformerFactory()
        Creates a new TransformerFactory.
        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 of XMLDocumentHelper and initializes it with a newly created, empty Document. 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 of XMLDocumentHelper 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 as ConfigurationException exceptions.
        Parameters:
        transformer - the transformer
        source - the source
        result - 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 the Document 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