Package com.jamesmurty.utils

Class XMLBuilder

  • public class XMLBuilder
extends java.lang.Object
    XML Builder is a utility that creates simple XML documents using relatively sparse Java code. It is intended to allow for quick and painless creation of XML documents where you might otherwise be tempted to use concatenated strings, rather than face the tedium and verbosity of coding with JAXP (http://jaxp.dev.java.net/).

    Internally, XML Builder uses JAXP to build a standard W3C Document model (DOM) that you can easily export as a string, or access and manipulate further if you have special requirements.

    The XMLBuilder class serves as a wrapper of Element nodes, and provides a number of utility methods that make it simple to manipulate the underlying element and the document to which it belongs. In essence, this class performs dual roles: it represents a specific XML node, and also allows manipulation of the entire underlying XML document. The platform's default DocumentBuilderFactory and DocumentBuilder classes are used to build the document.

    Author:
    James Murty

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected XMLBuilder​(org.w3c.dom.Document xmlDocument)
      Construct a new builder object that wraps the given XML document.
      protected XMLBuilder​(org.w3c.dom.Element myElement, org.w3c.dom.Element parentElement)
      Construct a new builder object that wraps the given XML document and element element.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      XMLBuilder a​(java.lang.String name, java.lang.String value)
      Synonym for attribute(String, String).
      protected void assertCurrentElementHasNoTextNodes()  
      java.lang.String asString()
      Serialize the XML document to a string excluding the XML declaration.
      java.lang.String asString​(java.util.Properties outputProperties)
      Serialize the XML document to a string by delegating to the toWriter(Writer, Properties) method.
      XMLBuilder attr​(java.lang.String name, java.lang.String value)
      Synonym for attribute(String, String).
      XMLBuilder attribute​(java.lang.String name, java.lang.String value)
      Add a named attribute value to the element represented by this builder node, and return the node representing the element to which the attribute was added (not the new attribute node).
      XMLBuilder c​(java.lang.String comment)
      Synonym for comment(String).
      XMLBuilder cdata​(byte[] data)
      Add a CDATA value to the element represented by this builder node, and return the node representing the element to which the data was added (not the new CDATA node).
      XMLBuilder cmnt​(java.lang.String comment)
      Synonym for comment(String).
      XMLBuilder comment​(java.lang.String comment)
      Add a comment to the element represented by this builder node, and return the node representing the element to which the comment was added (not the new comment node).
      static XMLBuilder create​(java.lang.String name)
      Construct a builder for new XML document.
      XMLBuilder d​(byte[] data)
      Synonym for #cdata(String).
      XMLBuilder data​(byte[] data)
      Synonym for #cdata(String).
      XMLBuilder e​(java.lang.String name)
      Synonym for element(String).
      XMLBuilder elem​(java.lang.String name)
      Synonym for element(String).
      XMLBuilder element​(java.lang.String name)
      Add a named XML element to the document as a child of this builder node, and return the builder node representing the new child.
      boolean equals​(java.lang.Object obj)  
      org.w3c.dom.Document getDocument()  
      org.w3c.dom.Element getElement()  
      XMLBuilder i​(java.lang.String target, java.lang.String data)
      Synonym for instruction(String, String).
      XMLBuilder importXMLBuilder​(XMLBuilder builder)
      Imports another XMLBuilder document into this document at the current position.
      XMLBuilder inst​(java.lang.String target, java.lang.String data)
      Synonym for instruction(String, String).
      XMLBuilder instruction​(java.lang.String target, java.lang.String data)
      Add an instruction to the element represented by this builder node, and return the node representing the element to which the instruction was added (not the new instruction node).
      static XMLBuilder parse​(org.xml.sax.InputSource inputSource)
      Construct a builder from an existing XML document.
      XMLBuilder r​(java.lang.String name)
      Synonym for reference(String).
      XMLBuilder ref​(java.lang.String name)
      Synonym for reference(String).
      XMLBuilder reference​(java.lang.String name)
      Add a reference to the element represented by this builder node, and return the node representing the element to which the reference was added (not the new reference node).
      XMLBuilder root()  
      XMLBuilder t​(java.lang.String value)
      Synonmy for text(String).
      XMLBuilder text​(java.lang.String value)
      Add a text value to the element represented by this builder node, and return the node representing the element to which the text was added (not the new text node).
      void toWriter​(java.io.Writer writer, java.util.Properties outputProperties)
      Serialize the XML document to the given writer using the default TransformerFactory and Transformer classes.
      XMLBuilder up()
      Return the builder node representing the parent of the current node.
      XMLBuilder up​(int steps)
      Return the builder node representing the nth ancestor element of this node, or the root node if n exceeds the document's depth.
      XMLBuilder xpathFind​(java.lang.String xpath)
      Find the first element in the builder's DOM matching the given XPath expression.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • XMLBuilder

        protected XMLBuilder​(org.w3c.dom.Document xmlDocument)
        Construct a new builder object that wraps the given XML document. This constructor is for internal use only.
        Parameters:
        xmlDocument - an XML document that the builder will manage and manipulate.

      • XMLBuilder

        protected XMLBuilder​(org.w3c.dom.Element myElement,
                     org.w3c.dom.Element parentElement)
        Construct a new builder object that wraps the given XML document and element element. This constructor is for internal use only.
        Parameters:
        myElement - the XML element that this builder node will wrap. This element may be part of the XML document, or it may be a new element that is to be added to the document.
        parentElement - If not null, the given myElement will be appended as child node of the parentElement node.

    • Method Detail

      • create

        public static XMLBuilder create​(java.lang.String name)
                         throws javax.xml.parsers.ParserConfigurationException,
                                javax.xml.parsers.FactoryConfigurationError
        Construct a builder for new XML document. The document will be created with the given root element, and the builder returned by this method will serve as the starting-point for any further document additions.
        Parameters:
        name - the name of the document's root element.
        Returns:
        a builder node that can be used to add more nodes to the XML document.
        Throws:
        javax.xml.parsers.FactoryConfigurationError
        javax.xml.parsers.ParserConfigurationException

      • parse

        public static XMLBuilder parse​(org.xml.sax.InputSource inputSource)
                        throws javax.xml.parsers.ParserConfigurationException,
                               org.xml.sax.SAXException,
                               java.io.IOException
        Construct a builder from an existing XML document. The provided XML document will be parsed and an XMLBuilder object referencing the document's root element will be returned.
        Parameters:
        inputSource - an XML document input source that will be parsed into a DOM.
        Returns:
        a builder node that can be used to add more nodes to the XML document.
        Throws:
        javax.xml.parsers.ParserConfigurationException
        javax.xml.parsers.FactoryConfigurationError
        javax.xml.parsers.ParserConfigurationException
        java.io.IOException
        org.xml.sax.SAXException

      • importXMLBuilder

        public XMLBuilder importXMLBuilder​(XMLBuilder builder)
        Imports another XMLBuilder document into this document at the current position. The entire document provided is imported.
        Parameters:
        builder - the XMLBuilder document to be imported.
        Returns:
        a builder node at the same location as before the import, but now containing the entire document tree provided.

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
        Returns:
        true if the XML Document and Element objects wrapped by this builder are equal to the other's wrapped objects.

      • getElement

        public org.w3c.dom.Element getElement()
        Returns:
        the XML element that this builder node will manipulate.

      • root

        public XMLBuilder root()
        Returns:
        the builder node representing the root element of the XML document. In other words, the same builder node returned by the initial create(String) or parse(InputSource) method.

      • getDocument

        public org.w3c.dom.Document getDocument()
        Returns:
        the XML document constructed by all builder nodes.

      • xpathFind

        public XMLBuilder xpathFind​(java.lang.String xpath)
                     throws javax.xml.xpath.XPathExpressionException
        Find the first element in the builder's DOM matching the given XPath expression.
        Parameters:
        xpath - An XPath expression that *must* resolve to an existing Element within the document object model.
        Returns:
        a builder node representing the first Element that matches the XPath expression.
        Throws:
        javax.xml.xpath.XPathExpressionException - If the XPath is invalid, or if does not resolve to at least one Node.ELEMENT_NODE.

      • element

        public XMLBuilder element​(java.lang.String name)
        Add a named XML element to the document as a child of this builder node, and return the builder node representing the new child.
        Parameters:
        name - the name of the XML element.
        Returns:
        a builder node representing the new child.
        Throws:
        java.lang.IllegalStateException - if you attempt to add a child element to an XML node that already contains a text node value.

      • elem

        public XMLBuilder elem​(java.lang.String name)
        Synonym for element(String).
        Parameters:
        name - the name of the XML element.
        Returns:
        a builder node representing the new child.
        Throws:
        java.lang.IllegalStateException - if you attempt to add a child element to an XML node that already contains a text node value.

      • e

        public XMLBuilder e​(java.lang.String name)
        Synonym for element(String).
        Parameters:
        name - the name of the XML element.
        Returns:
        a builder node representing the new child.
        Throws:
        java.lang.IllegalStateException - if you attempt to add a child element to an XML node that already contains a text node value.

      • attribute

        public XMLBuilder attribute​(java.lang.String name,
                            java.lang.String value)
        Add a named attribute value to the element represented by this builder node, and return the node representing the element to which the attribute was added (not the new attribute node).
        Parameters:
        name - the attribute's name.
        value - the attribute's value.
        Returns:
        the builder node representing the element to which the attribute was added.

      • attr

        public XMLBuilder attr​(java.lang.String name,
                       java.lang.String value)
        Synonym for attribute(String, String).
        Parameters:
        name - the attribute's name.
        value - the attribute's value.
        Returns:
        the builder node representing the element to which the attribute was added.

      • a

        public XMLBuilder a​(java.lang.String name,
                    java.lang.String value)
        Synonym for attribute(String, String).
        Parameters:
        name - the attribute's name.
        value - the attribute's value.
        Returns:
        the builder node representing the element to which the attribute was added.

      • text

        public XMLBuilder text​(java.lang.String value)
        Add a text value to the element represented by this builder node, and return the node representing the element to which the text was added (not the new text node).
        Parameters:
        value - the text value to add to the element.
        Returns:
        the builder node representing the element to which the text was added.

      • t

        public XMLBuilder t​(java.lang.String value)
        Synonmy for text(String).
        Parameters:
        value - the text value to add to the element.
        Returns:
        the builder node representing the element to which the text was added.

      • cdata

        public XMLBuilder cdata​(byte[] data)
        Add a CDATA value to the element represented by this builder node, and return the node representing the element to which the data was added (not the new CDATA node).
        Parameters:
        data - the data value that will be Base64-encoded and added to a CDATA element.
        Returns:
        the builder node representing the element to which the data was added.

      • data

        public XMLBuilder data​(byte[] data)
        Synonym for #cdata(String).
        Parameters:
        data - the data value to add to the element.
        Returns:
        the builder node representing the element to which the data was added.

      • d

        public XMLBuilder d​(byte[] data)
        Synonym for #cdata(String).
        Parameters:
        data - the data value to add to the element.
        Returns:
        the builder node representing the element to which the data was added.

      • comment

        public XMLBuilder comment​(java.lang.String comment)
        Add a comment to the element represented by this builder node, and return the node representing the element to which the comment was added (not the new comment node).
        Parameters:
        comment - the comment to add to the element.
        Returns:
        the builder node representing the element to which the comment was added.

      • cmnt

        public XMLBuilder cmnt​(java.lang.String comment)
        Synonym for comment(String).
        Parameters:
        comment - the comment to add to the element.
        Returns:
        the builder node representing the element to which the comment was added.

      • c

        public XMLBuilder c​(java.lang.String comment)
        Synonym for comment(String).
        Parameters:
        comment - the comment to add to the element.
        Returns:
        the builder node representing the element to which the comment was added.

      • instruction

        public XMLBuilder instruction​(java.lang.String target,
                              java.lang.String data)
        Add an instruction to the element represented by this builder node, and return the node representing the element to which the instruction was added (not the new instruction node).
        Parameters:
        target - the target value for the instruction.
        data - the data value for the instruction
        Returns:
        the builder node representing the element to which the instruction was added.

      • inst

        public XMLBuilder inst​(java.lang.String target,
                       java.lang.String data)
        Synonym for instruction(String, String).
        Parameters:
        target - the target value for the instruction.
        data - the data value for the instruction
        Returns:
        the builder node representing the element to which the instruction was added.

      • i

        public XMLBuilder i​(java.lang.String target,
                    java.lang.String data)
        Synonym for instruction(String, String).
        Parameters:
        target - the target value for the instruction.
        data - the data value for the instruction
        Returns:
        the builder node representing the element to which the instruction was added.

      • reference

        public XMLBuilder reference​(java.lang.String name)
        Add a reference to the element represented by this builder node, and return the node representing the element to which the reference was added (not the new reference node).
        Parameters:
        name - the name value for the reference.
        Returns:
        the builder node representing the element to which the reference was added.

      • ref

        public XMLBuilder ref​(java.lang.String name)
        Synonym for reference(String).
        Parameters:
        name - the name value for the reference.
        Returns:
        the builder node representing the element to which the reference was added.

      • r

        public XMLBuilder r​(java.lang.String name)
        Synonym for reference(String).
        Parameters:
        name - the name value for the reference.
        Returns:
        the builder node representing the element to which the reference was added.

      • up

        public XMLBuilder up​(int steps)
        Return the builder node representing the nth ancestor element of this node, or the root node if n exceeds the document's depth.
        Parameters:
        steps - the number of parent elements to step over while navigating up the chain of node ancestors. A steps value of 1 will find a node's parent, 2 will find its grandparent etc.
        Returns:
        the nth ancestor of this node, or the root node if this is reached before the nth parent is found.

      • up

        public XMLBuilder up()
        Return the builder node representing the parent of the current node.
        Returns:
        the parent of this node, or the root node if this method is called on the root node.

      • assertCurrentElementHasNoTextNodes

        protected void assertCurrentElementHasNoTextNodes()
        Throws:
        java.lang.IllegalStateException - if the current element contains any child text nodes.

      • toWriter

        public void toWriter​(java.io.Writer writer,
                     java.util.Properties outputProperties)
              throws javax.xml.transform.TransformerException
        Serialize the XML document to the given writer using the default TransformerFactory and Transformer classes. If output options are provided, these options are provided to the Transformer serializer.
        Parameters:
        writer - a writer to which the serialized document is written.
        outputProperties - settings for the Transformer serializer. This parameter may be null or an empty Properties object, in which case the default output properties will be applied.
        Throws:
        javax.xml.transform.TransformerException

      • asString

        public java.lang.String asString​(java.util.Properties outputProperties)
                          throws javax.xml.transform.TransformerException
        Serialize the XML document to a string by delegating to the toWriter(Writer, Properties) method. If output options are provided, these options are provided to the Transformer serializer.
        Parameters:
        outputProperties - settings for the Transformer serializer. This parameter may be null or an empty Properties object, in which case the default output properties will be applied.
        Returns:
        the XML document as a string
        Throws:
        javax.xml.transform.TransformerException

      • asString

        public java.lang.String asString()
                          throws javax.xml.transform.TransformerException
        Serialize the XML document to a string excluding the XML declaration.
        Returns:
        the XML document as a string without the XML declaration at the beginning of the output.
        Throws:
        javax.xml.transform.TransformerException