Package com.jamesmurty.utils

Class XMLBuilder

  • public final class XMLBuilder
extends BaseXMLBuilder
    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 Detail

      • XMLBuilder

        protected XMLBuilder​(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​(Node myNode,
                     Node parentNode)
        Construct a new builder object that wraps the given XML document and node. This constructor is for internal use only.
        Parameters:
        myNode - the XML node that this builder node will wrap. This node may be part of the XML document, or it may be a new element that is to be added to the document.
        parentNode - If not null, the given myElement will be appended as child node of the parentNode node.

    • Method Detail

      • create

        public static XMLBuilder create​(String name,
                                String namespaceURI,
                                boolean enableExternalEntities,
                                boolean isNamespaceAware)
                         throws ParserConfigurationException,
                                FactoryConfigurationError
        Construct a builder for new XML document with a default namespace. 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.
        namespaceURI - default namespace URI for document, ignored if null or empty.
        enableExternalEntities - enable external entities; beware of XML External Entity (XXE) injection.
        isNamespaceAware - enable or disable namespace awareness in the underlying DocumentBuilderFactory
        Returns:
        a builder node that can be used to add more nodes to the XML document.
        Throws:
        FactoryConfigurationError - xyz
        ParserConfigurationException - xyz

      • create

        public static XMLBuilder create​(String name,
                                boolean enableExternalEntities,
                                boolean isNamespaceAware)
                         throws ParserConfigurationException,
                                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.
        enableExternalEntities - enable external entities; beware of XML External Entity (XXE) injection.
        isNamespaceAware - enable or disable namespace awareness in the underlying DocumentBuilderFactory
        Returns:
        a builder node that can be used to add more nodes to the XML document.
        Throws:
        FactoryConfigurationError - xyz
        ParserConfigurationException - xyz

      • create

        public static XMLBuilder create​(String name,
                                String namespaceURI)
                         throws ParserConfigurationException,
                                FactoryConfigurationError
        Construct a builder for new XML document with a default namespace. 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.
        namespaceURI - default namespace URI for document, ignored if null or empty.
        Returns:
        a builder node that can be used to add more nodes to the XML document.
        Throws:
        FactoryConfigurationError - xyz
        ParserConfigurationException - xyz

      • stripWhitespaceOnlyTextNodes

        public XMLBuilder stripWhitespaceOnlyTextNodes()
                                        throws XPathExpressionException
        Description copied from class: BaseXMLBuilder
        Find and delete from the underlying Document any text nodes that contain nothing but whitespace, such as newlines and tab or space characters used to indent or pretty-print an XML document. Uses approach I documented on StackOverflow: http://stackoverflow.com/a/979606/4970
        Specified by:
        stripWhitespaceOnlyTextNodes in class BaseXMLBuilder
        Returns:
        a builder node at the same location as before the operation.
        Throws:
        XPathExpressionException - xyz

      • importXMLBuilder

        public XMLBuilder importXMLBuilder​(BaseXMLBuilder builder)
        Description copied from class: BaseXMLBuilder
        Imports another XMLBuilder document into this document at the current position. The entire document provided is imported.
        Specified by:
        importXMLBuilder in class BaseXMLBuilder
        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.

      • root

        public XMLBuilder root()
        Specified by:
        root in class BaseXMLBuilder
        Returns:
        the builder node representing the root element of the XML document.

      • xpathFind

        public XMLBuilder xpathFind​(String xpath,
                            NamespaceContext nsContext)
                     throws XPathExpressionException
        Description copied from class: BaseXMLBuilder
        Find the first element in the builder's DOM matching the given XPath expression, where the expression may include namespaces if a NamespaceContext is provided.
        Specified by:
        xpathFind in class BaseXMLBuilder
        Parameters:
        xpath - An XPath expression that *must* resolve to an existing Element within the document object model.
        nsContext - a mapping of prefixes to namespace URIs that allows the XPath expression to use namespaces.
        Returns:
        a builder node representing the first Element that matches the XPath expression.
        Throws:
        XPathExpressionException - If the XPath is invalid, or if does not resolve to at least one Node.ELEMENT_NODE.

      • xpathFind

        public XMLBuilder xpathFind​(String xpath)
                     throws XPathExpressionException
        Description copied from class: BaseXMLBuilder
        Find the first element in the builder's DOM matching the given XPath expression.
        Specified by:
        xpathFind in class BaseXMLBuilder
        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:
        XPathExpressionException - If the XPath is invalid, or if does not resolve to at least one Node.ELEMENT_NODE.

      • element

        public XMLBuilder element​(String name)
        Description copied from class: BaseXMLBuilder
        Add a named XML element to the document as a child of this builder node, and return the builder node representing the new child. When adding an element to a namespaced document, the new node will be assigned a namespace matching it's qualified name prefix (if any) or the document's default namespace. NOTE: If the element has a prefix that does not match any known namespaces, the element will be created without any namespace.
        Specified by:
        element in class BaseXMLBuilder
        Parameters:
        name - the name of the XML element.
        Returns:
        a builder node representing the new child.

      • element

        public XMLBuilder element​(String name,
                          String namespaceURI)
        Description copied from class: BaseXMLBuilder
        Add a named and namespaced XML element to the document as a child of this builder node, and return the builder node representing the new child.
        Specified by:
        element in class BaseXMLBuilder
        Parameters:
        name - the name of the XML element.
        namespaceURI - a namespace URI
        Returns:
        a builder node representing the new child.

      • elementBefore

        public XMLBuilder elementBefore​(String name)
        Description copied from class: BaseXMLBuilder
        Add a named XML element to the document as a sibling element that precedes the position of this builder node, and return the builder node representing the new child. When adding an element to a namespaced document, the new node will be assigned a namespace matching it's qualified name prefix (if any) or the document's default namespace. NOTE: If the element has a prefix that does not match any known namespaces, the element will be created without any namespace.
        Specified by:
        elementBefore in class BaseXMLBuilder
        Parameters:
        name - the name of the XML element.
        Returns:
        a builder node representing the new child.

      • elementBefore

        public XMLBuilder elementBefore​(String name,
                                String namespaceURI)
        Description copied from class: BaseXMLBuilder
        Add a named and namespaced XML element to the document as a sibling element that precedes the position of this builder node, and return the builder node representing the new child.
        Specified by:
        elementBefore in class BaseXMLBuilder
        Parameters:
        name - the name of the XML element.
        namespaceURI - a namespace URI
        Returns:
        a builder node representing the new child.

      • attribute

        public XMLBuilder attribute​(String name,
                            String value)
        Description copied from class: BaseXMLBuilder
        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).
        Specified by:
        attribute in class BaseXMLBuilder
        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​(String value,
                       boolean replaceText)
        Description copied from class: BaseXMLBuilder
        Add or replace the text value of an element represented by this builder node, and return the node representing the element to which the text was added (not the new text node).
        Specified by:
        text in class BaseXMLBuilder
        Parameters:
        value - the text value to set or add to the element.
        replaceText - if True any existing text content of the node is replaced with the given text value, if the given value is appended to any existing text.
        Returns:
        the builder node representing the element to which the text was added.

      • text

        public XMLBuilder text​(String value)
        Description copied from class: BaseXMLBuilder
        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).
        Specified by:
        text in class BaseXMLBuilder
        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​(String data)
        Description copied from class: BaseXMLBuilder
        Add a CDATA node with String content 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).
        Specified by:
        cdata in class BaseXMLBuilder
        Parameters:
        data - the String value that will be added to a CDATA element.
        Returns:
        the builder node representing the element to which the data was added.

      • cdata

        public XMLBuilder cdata​(byte[] data)
        Description copied from class: BaseXMLBuilder
        Add a CDATA node with Base64-encoded byte data content 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).
        Specified by:
        cdata in class BaseXMLBuilder
        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)
        Description copied from class: BaseXMLBuilder
        Synonym for BaseXMLBuilder.cdata(byte[]).
        Specified by:
        data in class BaseXMLBuilder
        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.

      • d

        public XMLBuilder d​(byte[] data)
        Description copied from class: BaseXMLBuilder
        Synonym for BaseXMLBuilder.cdata(byte[]).
        Specified by:
        d in class BaseXMLBuilder
        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.

      • comment

        public XMLBuilder comment​(String comment)
        Description copied from class: BaseXMLBuilder
        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).
        Specified by:
        comment in class BaseXMLBuilder
        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​(String target,
                              String data)
        Description copied from class: BaseXMLBuilder
        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).
        Specified by:
        instruction in class BaseXMLBuilder
        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.

      • insertInstruction

        public XMLBuilder insertInstruction​(String target,
                                    String data)
        Description copied from class: BaseXMLBuilder
        Insert an instruction before the element represented by this builder node, and return the node representing that same element (not the new instruction node).
        Specified by:
        insertInstruction in class BaseXMLBuilder
        Parameters:
        target - the target value for the instruction.
        data - the data value for the instruction
        Returns:
        the builder node representing the element before which the instruction was inserted.

      • reference

        public XMLBuilder reference​(String name)
        Description copied from class: BaseXMLBuilder
        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).
        Specified by:
        reference in class BaseXMLBuilder
        Parameters:
        name - the name value for the reference.
        Returns:
        the builder node representing the element to which the reference was added.

      • namespace

        public XMLBuilder namespace​(String prefix,
                            String namespaceURI)
        Description copied from class: BaseXMLBuilder
        Add an XML namespace attribute to this builder's element node.
        Specified by:
        namespace in class BaseXMLBuilder
        Parameters:
        prefix - a prefix for the namespace URI within the document, may be null or empty in which case a default "xmlns" attribute is created.
        namespaceURI - a namespace uri
        Returns:
        the builder node representing the element to which the attribute was added.

      • ns

        public XMLBuilder ns​(String prefix,
                     String namespaceURI)
        Description copied from class: BaseXMLBuilder
        Synonym for BaseXMLBuilder.namespace(String, String).
        Specified by:
        ns in class BaseXMLBuilder
        Parameters:
        prefix - a prefix for the namespace URI within the document, may be null or empty in which case a default xmlns attribute is created.
        namespaceURI - a namespace uri
        Returns:
        the builder node representing the element to which the attribute was added.

      • namespace

        public XMLBuilder namespace​(String namespaceURI)
        Description copied from class: BaseXMLBuilder
        Add an XML namespace attribute to this builder's element node without a prefix.
        Specified by:
        namespace in class BaseXMLBuilder
        Parameters:
        namespaceURI - a namespace uri
        Returns:
        the builder node representing the element to which the attribute was added.

      • up

        public XMLBuilder up​(int steps)
        Description copied from class: BaseXMLBuilder
        Return the builder node representing the nth ancestor element of this node, or the root node if n exceeds the document's depth.
        Specified by:
        up in class BaseXMLBuilder
        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()
        Description copied from class: BaseXMLBuilder
        Return the builder node representing the parent of the current node.
        Specified by:
        up in class BaseXMLBuilder
        Returns:
        the parent of this node, or the root node if this method is called on the root node.

      • document

        public XMLBuilder document()
        Description copied from class: BaseXMLBuilder
        BEWARE: The builder returned by this method represents a Document node, not an Element node as is usually the case, so attempts to use the attribute or namespace methods on this builder will likely fail.
        Specified by:
        document in class BaseXMLBuilder
        Returns:
        the builder node representing the root XML document.