Package org.apache.commons.configuration2

Class XMLDocumentHelper

java.lang.Object
org.apache.commons.configuration2.XMLDocumentHelper
final class XMLDocumentHelper extends 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 Details

    • document

      private final Document document
      Stores the document managed by this instance.

    • elementMapping

      private final Map<Node,Node> elementMapping
      The element mapping to the source document.

    • sourcePublicID

      private final String sourcePublicID
      Stores the public ID of the source document.

    • sourceSystemID

      private final String sourceSystemID
      Stores the system ID of the source document.

  • Constructor Details

    • XMLDocumentHelper

      XMLDocumentHelper(Document doc, Map<Node,Node> elemMap, String pubID, 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 Details

    • copyDocument

      private static Document copyDocument(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 DocumentBuilder createDocumentBuilder(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 DocumentBuilderFactory createDocumentBuilderFactory()
      Creates a new DocumentBuilderFactory instance.
      Returns:
      the new factory object

    • createElementMapping

      private static Map<Node,Node> createElementMapping(Document doc1, 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(Node n1, Node n2, Map<Node,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 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 Transformer createTransformer(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 TransformerFactory createTransformerFactory()
      Creates a new TransformerFactory.
      Returns:
      the TransformerFactory

    • emptyElementMapping

      private static Map<Node,Node> emptyElementMapping()
      Creates an empty element mapping.
      Returns:
      the empty mapping

    • forNewDocument

      public static XMLDocumentHelper forNewDocument(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(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(Transformer transformer, Source source, 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 Document getDocument()
      Gets the Document managed by this helper.
      Returns:
      the wrapped Document

    • getElementMapping

      public Map<Node,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 String getSourcePublicID()
      Gets the public ID of the source document.
      Returns:
      the public ID of the source document

    • getSourceSystemID

      public String getSourceSystemID()
      Gets the system ID of the source document.
      Returns:
      the system ID of the source document