Package com.adaptris.util

Class XmlUtils

  • public class XmlUtils
extends java.lang.Object
    Class which provides convenience methods for various aspects of XML usage.

    • Constructor Summary

      Constructors 
      Constructor Description
      XmlUtils()  
      XmlUtils​(javax.xml.namespace.NamespaceContext ctx)
      Deprecated.
      XmlUtils​(javax.xml.namespace.NamespaceContext ctx, javax.xml.parsers.DocumentBuilderFactory f)  
      XmlUtils​(org.xml.sax.EntityResolver er)  
      XmlUtils​(org.xml.sax.EntityResolver er, javax.xml.namespace.NamespaceContext ctx, javax.xml.parsers.DocumentBuilderFactory dbf)  
      XmlUtils​(org.xml.sax.EntityResolver er, javax.xml.transform.URIResolver ur)
      Deprecated.
      URIResolver does nothing so use XmlUtils(EntityResolver) instead.
      XmlUtils​(org.xml.sax.EntityResolver er, javax.xml.transform.URIResolver ur, javax.xml.namespace.NamespaceContext ctx)
      Deprecated.
      URIResolver does nothing so use XmlUtils(EntityResolver, NamespaceContext, DocumentBuilderFactory) instead.
      XmlUtils​(org.xml.sax.EntityResolver er, javax.xml.transform.URIResolver ur, javax.xml.namespace.NamespaceContext ctx, javax.xml.parsers.DocumentBuilderFactory dbf)
      Deprecated.
      URIResolver does nothing so use XmlUtils(EntityResolver, NamespaceContext, DocumentBuilderFactory) instead.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void appendNode​(org.w3c.dom.Node newNode, org.w3c.dom.Node parent)
      Convenience method which appends a new Node to the children of a parent
      <T> T castOrFail​(java.lang.Object o, java.lang.Class<T> type, java.lang.String exceptionMsg)  
      org.w3c.dom.Node createNode​(java.lang.String xp)
      Method which will create a Node path based on the supplied XPath
      void deleteAttribute​(java.lang.String name, org.w3c.dom.Node n)
      Method which deletes an attribute from the specified Node, which must be of type org.w3c.dom.Element.
      org.w3c.dom.Document getCurrentDoc()  
      java.lang.String[] getMultipleTextItems​(java.lang.String xp)
      Method which returns an array of String representations of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the Node created by "setSource".
      java.lang.String[] getMultipleTextItems​(java.lang.String xp, org.w3c.dom.Node documentNode)
      Method which returns an array of String representations of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the provided Node.
      org.w3c.dom.NodeList getNodeList​(java.lang.String xp)
      Method which returns a NodeList extracted from the Node created by the setSource method based on the provided xpath String.
      org.w3c.dom.NodeList getNodeList​(java.lang.String xp, org.w3c.dom.Node documentNode)
      Method which returns a NodeList extracted from the provided Node based on the provided xpath String.
      java.lang.String getParseMessage()
      Method which returns the success / fail message generated by the document parser.
      org.w3c.dom.Node getSingleNode​(java.lang.String xp)
      Method which returns a Node by applying the provided, this Node can either be modified directly using the DOM api or by using the convenience methods in this class.
      org.w3c.dom.Node getSingleNode​(java.lang.String xp, org.w3c.dom.Node n)
      Method which returns a Node by applying the provided relative to the specified root Node.
      java.lang.String getSingleTextItem​(java.lang.String xp)
      Method which returns a String representation of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the Node created by "setSource".
      java.lang.String getSingleTextItem​(java.lang.String xp, org.w3c.dom.Node documentNode)
      Method which returns a String representation of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the provided Node.
      void insertNodeBefore​(org.w3c.dom.Node newNode, org.w3c.dom.Node existingNode, org.w3c.dom.Node parent)
      Convenience method which enables a new Node to be added to a parent at a specified position, by specifying the Node to insert before.
      boolean isDocumentValid()
      Method which indicates whether the file was valid
      void removeNode​(org.w3c.dom.Node toBeRemoved, org.w3c.dom.Node parent)
      Convenience method which removes a Node from the children of a parent
      void reset()
      Re-initialises the XmlUtils object.
      void setAttribute​(java.lang.String xp, java.lang.String name, java.lang.String value)
      Method which sets an attribute on the specified Node, which must be of type org.w3c.dom.Element.
      void setAttribute​(java.lang.String name, java.lang.String value, org.w3c.dom.Node n)
      Method which sets an attribute on the specified Node, which must be of type org.w3c.dom.Element.
      void setNodeValue​(java.lang.String xp, java.lang.String value)
      Method which modifies the value of the Node returned by the XPath query specified.
      void setNodeValue​(java.lang.String xp, java.lang.String v, org.w3c.dom.Node root)
      Method which modifies the value of the Node returned by the XPath query specified, relative to the provided parent node.
      void setNodeValue​(java.lang.String value, org.w3c.dom.Node n)
      Method which updates the Text value of a specified Node
      void setSchema​(java.lang.String uri)
      Method added to specify the Schema to Validate against.
      void setSource​(java.io.InputStream xml)
      Method which sets the source XML document for this class.
      void setSource​(java.io.Reader xml)
      Method which sets the source XML document for this class.
      void setSource​(org.w3c.dom.Node node)
      Method which sets the source XML document for this class.
      void setSource​(org.xml.sax.InputSource xml)
      Method which sets the source XML document for this class.
      void writeDocument​(java.io.OutputStream output)
      Method which writes the document set by setSource to the specified OutputStream using ISO-8859-1 encoding
      void writeDocument​(java.io.OutputStream output, java.lang.String encoding)
      Method which writes a Document Node to the specified OutputStream using the specified encoding
      void writeDocument​(java.io.Writer output)
      Method which writes the document set by setSource to the specified Writer using ISO-8859-1 encoding
      void writeDocument​(java.io.Writer output, java.lang.String encoding)
      Method which writes a Document Node to the specified Writer using the specified encoding
      void writeDocument​(org.w3c.dom.Node node, java.io.OutputStream output)
      Method which writes a Document Node to the specified Writer using ISO-8859-1 encoding
      void writeDocument​(org.w3c.dom.Node node, java.io.OutputStream output, java.lang.String encoding)
      Method which writes a Document Node to the specified Writer using the specified encoding
      void writeDocument​(org.w3c.dom.Node node, java.io.Writer writer)
      Method which writes a Document Node to the specified OutputStream using the specified encoding
      void writeDocument​(org.w3c.dom.Node node, java.io.Writer writer, java.lang.String encoding)
      Write the node to the specified writer.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • XmlUtils

        public XmlUtils()

      • XmlUtils

        public XmlUtils​(org.xml.sax.EntityResolver er)

      • XmlUtils

        @Deprecated
public XmlUtils​(javax.xml.namespace.NamespaceContext ctx)
        Deprecated.

      • XmlUtils

        public XmlUtils​(javax.xml.namespace.NamespaceContext ctx,
                javax.xml.parsers.DocumentBuilderFactory f)

      • XmlUtils

        @Deprecated
@Removal(version="4.0.0")
public XmlUtils​(org.xml.sax.EntityResolver er,
                javax.xml.transform.URIResolver ur)
        Deprecated.
        URIResolver does nothing so use XmlUtils(EntityResolver) instead.

      • XmlUtils

        @Deprecated
@Removal(version="4.0.0")
public XmlUtils​(org.xml.sax.EntityResolver er,
                javax.xml.transform.URIResolver ur,
                javax.xml.namespace.NamespaceContext ctx,
                javax.xml.parsers.DocumentBuilderFactory dbf)
        Deprecated.
        URIResolver does nothing so use XmlUtils(EntityResolver, NamespaceContext, DocumentBuilderFactory) instead.

      • XmlUtils

        public XmlUtils​(org.xml.sax.EntityResolver er,
                javax.xml.namespace.NamespaceContext ctx,
                javax.xml.parsers.DocumentBuilderFactory dbf)

    • Method Detail

      • setSchema

        public void setSchema​(java.lang.String uri)
               throws java.lang.Exception
        Method added to specify the Schema to Validate against. If not set, document will not be validated.
        Parameters:
        uri - the URI to validate against.
        Throws:
        java.lang.Exception - on error.

      • setSource

        public void setSource​(org.xml.sax.InputSource xml)
        Method which sets the source XML document for this class. Source document must be specified before any additional methods can be successfully called.

        This method not only receives the document, but it is immediately compiled into a DOM Object.

        Parameters:
        xml - the InputSource

      • setSource

        public void setSource​(java.io.Reader xml)
        Method which sets the source XML document for this class. Source document must be specified before any additional methods can be successfully called.

        This method not only receives the document, but it is immediately compiled into a DOM Object.

        Parameters:
        xml - the Reader

      • setSource

        public void setSource​(java.io.InputStream xml)
        Method which sets the source XML document for this class. Source document must be specified before any additional methods can be successfully called.

        This method not only receives the document, but it is immediately compiled into a DOM Object.

        Parameters:
        xml - the inputstream for the source

      • setSource

        public void setSource​(org.w3c.dom.Node node)
        Method which sets the source XML document for this class. Source document must be specified before any additional methods can be successfully called.

        Parameters:
        node - a Node object of type Document

      • getSingleTextItem

        public java.lang.String getSingleTextItem​(java.lang.String xp,
                                          org.w3c.dom.Node documentNode)
        Method which returns a String representation of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the provided Node.

        Null will be returned if the provided XPath fails to retrieve a Node of the above types.

        The provided String is compiled into an XPath and stored for future use.

        Parameters:
        xp - the Xpath query
        documentNode - the Node to operate on.
        Returns:
        the text string returned by the Xpath

      • getSingleTextItem

        public java.lang.String getSingleTextItem​(java.lang.String xp)
        Method which returns a String representation of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the Node created by "setSource".

        Null will be returned if the provided XPath fails to retrieve a Node of the above types.

        The provided String is compiled into an XPath and stored for future use.

        Parameters:
        xp - the Xpath
        Returns:
        the string representing the text item returned by the query

      • getMultipleTextItems

        public java.lang.String[] getMultipleTextItems​(java.lang.String xp,
                                               org.w3c.dom.Node documentNode)
        Method which returns an array of String representations of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the provided Node.

        Null will be returned if the provided XPath fails to retrieve any Nodes of the above types.

        The provided String is compiled into an XPath and stored for future use.

        Parameters:
        xp - the xpath
        documentNode - the starting node.
        Returns:
        an array of String objects that were returned by the query.

      • getMultipleTextItems

        public java.lang.String[] getMultipleTextItems​(java.lang.String xp)
        Method which returns an array of String representations of either a TEXT_NODE or an ATTRIBUTE_NODE, extracted from the Node created by "setSource".

        Null will be returned if the provided XPath fails to retrieve any Nodes of the above types.

        The provided String is compiled into an XPath and stored for future use.

        Parameters:
        xp - the Xpath query.
        Returns:
        an array of String objects returned by the query.

      • getNodeList

        public org.w3c.dom.NodeList getNodeList​(java.lang.String xp,
                                        org.w3c.dom.Node documentNode)
        Method which returns a NodeList extracted from the provided Node based on the provided xpath String. An example of the functionality of this would be to extract multiple documents from within an envelope structure and then to use the extracted Nodes to perform more granular queries on the extracted data.
        Parameters:
        xp - the Xpath query
        documentNode - the Node to search on.
        Returns:
        the NodeList returned by the query.

      • getNodeList

        public org.w3c.dom.NodeList getNodeList​(java.lang.String xp)
        Method which returns a NodeList extracted from the Node created by the setSource method based on the provided xpath String. An example of the functionality of this would be to extract multiple documents from within an envelope structure and then to use the extracted Nodes to perform more granular queries on the extracted data.
        Parameters:
        xp - the Xpath query
        Returns:
        the NodeList returned by the query.

      • getSingleNode

        public org.w3c.dom.Node getSingleNode​(java.lang.String xp)
        Method which returns a Node by applying the provided, this Node can either be modified directly using the DOM api or by using the convenience methods in this class.
        Parameters:
        xp - the XPath which will return the Node
        Returns:
        the Node.

      • getSingleNode

        public org.w3c.dom.Node getSingleNode​(java.lang.String xp,
                                      org.w3c.dom.Node n)
        Method which returns a Node by applying the provided relative to the specified root Node. This Nodecan either be modified directly using the DOM api or by using the convenience methods in this class.
        Parameters:
        xp - the XPath which will return the Node
        n - the root node to apply the XPath to
        Returns:
        The Node.

      • reset

        public void reset()
           throws java.lang.Exception
        Re-initialises the XmlUtils object. Clears down parsed XML message and compiled XPaths
        Throws:
        java.lang.Exception - on any error.

      • isDocumentValid

        public boolean isDocumentValid()
        Method which indicates whether the file was valid
        Returns:
        true if the document is valid

      • getParseMessage

        public java.lang.String getParseMessage()
        Method which returns the success / fail message generated by the document parser.
        Returns:
        the error message.

      • createNode

        public org.w3c.dom.Node createNode​(java.lang.String xp)
                            throws java.lang.Exception
        Method which will create a Node path based on the supplied XPath
        Parameters:
        xp - the xpath.
        Returns:
        the Node that was constructed from the xpath.
        Throws:
        java.lang.Exception - on error.

      • setNodeValue

        public void setNodeValue​(java.lang.String xp,
                         java.lang.String value)
                  throws java.lang.Exception
        Method which modifies the value of the Node returned by the XPath query specified.
        Parameters:
        xp - the XPath which will return the Node to be updated
        value - the new value to set the node to
        Throws:
        java.lang.Exception - on error.

      • setNodeValue

        public void setNodeValue​(java.lang.String xp,
                         java.lang.String v,
                         org.w3c.dom.Node root)
                  throws java.lang.Exception
        Method which modifies the value of the Node returned by the XPath query specified, relative to the provided parent node.
        Parameters:
        xp - the XPath which will return the Node to be updated
        v - the new value to set the node to
        root - the root node to apply the XPath to
        Throws:
        java.lang.Exception - on error.

      • setNodeValue

        public void setNodeValue​(java.lang.String value,
                         org.w3c.dom.Node n)
                  throws java.lang.Exception
        Method which updates the Text value of a specified Node
        Parameters:
        value - the new Text value
        n - the node to be modified
        Throws:
        java.lang.Exception - on error.

      • setAttribute

        public void setAttribute​(java.lang.String xp,
                         java.lang.String name,
                         java.lang.String value)
                  throws java.lang.Exception
        Method which sets an attribute on the specified Node, which must be of type org.w3c.dom.Element. If the attribute already exists, it will be updated with the new value.
        Parameters:
        xp - to retrieve the node to be modified
        name - the attribute name
        value - the new value
        Throws:
        java.lang.Exception - on error.

      • setAttribute

        public void setAttribute​(java.lang.String name,
                         java.lang.String value,
                         org.w3c.dom.Node n)
                  throws java.lang.Exception
        Method which sets an attribute on the specified Node, which must be of type org.w3c.dom.Element. If the attribute already exists, it will be updated with the new value.
        Parameters:
        name - the attribute name
        value - the new value
        n - the node to be modified
        Throws:
        java.lang.Exception - on error.

      • deleteAttribute

        public void deleteAttribute​(java.lang.String name,
                            org.w3c.dom.Node n)
                     throws java.lang.Exception
        Method which deletes an attribute from the specified Node, which must be of type org.w3c.dom.Element.
        Parameters:
        name - the attribute name
        n - the node to be modified
        Throws:
        java.lang.Exception - on error.

      • insertNodeBefore

        public void insertNodeBefore​(org.w3c.dom.Node newNode,
                             org.w3c.dom.Node existingNode,
                             org.w3c.dom.Node parent)
                      throws java.lang.Exception
        Convenience method which enables a new Node to be added to a parent at a specified position, by specifying the Node to insert before. Here is a sample of how to use: 
          

   // Example of how to insert a Node as the 3rd child of a parent
   Node p  = xmlUtils.getSingleNode("/mydoc/parent");
   Node c   = xmlUtils.getSingleNode("/mydoc/parent/child[4]");
   Node n = // Node creation code here;
   xmlUtils.insertNodeBefore(newNode, child, parent);
        Parameters:
        newNode - the Node to be added
        existingNode - the Node to insert before
        parent - the parent Node
        Throws:
        java.lang.Exception - on error.

      • appendNode

        public void appendNode​(org.w3c.dom.Node newNode,
                       org.w3c.dom.Node parent)
                throws java.lang.Exception
        Convenience method which appends a new Node to the children of a parent
        Parameters:
        newNode - the Node to be added
        parent - the parent Node
        Throws:
        java.lang.Exception - on error.

      • removeNode

        public void removeNode​(org.w3c.dom.Node toBeRemoved,
                       org.w3c.dom.Node parent)
                throws java.lang.Exception
        Convenience method which removes a Node from the children of a parent
        Parameters:
        toBeRemoved - the Node to be Removed
        parent - the parent Node
        Throws:
        java.lang.Exception - on error.

      • writeDocument

        public void writeDocument​(java.io.OutputStream output)
                   throws java.lang.Exception
        Method which writes the document set by setSource to the specified OutputStream using ISO-8859-1 encoding
        Parameters:
        output - the Outputstream
        Throws:
        java.lang.Exception - on error.

      • writeDocument

        public void writeDocument​(java.io.Writer output)
                   throws java.lang.Exception
        Method which writes the document set by setSource to the specified Writer using ISO-8859-1 encoding
        Parameters:
        output - the Outputstream
        Throws:
        java.lang.Exception - on error.

      • writeDocument

        public void writeDocument​(java.io.OutputStream output,
                          java.lang.String encoding)
                   throws java.lang.Exception
        Method which writes a Document Node to the specified OutputStream using the specified encoding
        Parameters:
        encoding - the encoding type.
        output - the Outputstream
        Throws:
        java.lang.Exception - on error.

      • writeDocument

        public void writeDocument​(java.io.Writer output,
                          java.lang.String encoding)
                   throws java.lang.Exception
        Method which writes a Document Node to the specified Writer using the specified encoding
        Parameters:
        encoding - the encoding type.
        output - the Outputstream
        Throws:
        java.lang.Exception - on error.

      • writeDocument

        public void writeDocument​(org.w3c.dom.Node node,
                          java.io.OutputStream output)
                   throws java.lang.Exception
        Method which writes a Document Node to the specified Writer using ISO-8859-1 encoding
        Parameters:
        node - the Node to write.
        output - the Outputstream to use.
        Throws:
        java.lang.Exception - on error.

      • writeDocument

        public void writeDocument​(org.w3c.dom.Node node,
                          java.io.Writer writer)
                   throws java.lang.Exception
        Method which writes a Document Node to the specified OutputStream using the specified encoding
        Parameters:
        node - the node to write.
        writer - the Writer
        Throws:
        java.lang.Exception - on error.

      • writeDocument

        public void writeDocument​(org.w3c.dom.Node node,
                          java.io.OutputStream output,
                          java.lang.String encoding)
                   throws java.lang.Exception
        Method which writes a Document Node to the specified Writer using the specified encoding
        Parameters:
        node - the Node to write.
        output - the Outputstream to use.
        encoding - the Encoding.
        Throws:
        java.lang.Exception - on error.

      • writeDocument

        public void writeDocument​(org.w3c.dom.Node node,
                          java.io.Writer writer,
                          java.lang.String encoding)
                   throws java.lang.Exception
        Write the node to the specified writer.
        Parameters:
        node - a Document object
        writer - the writer to use.
        encoding - the encoding format.
        Throws:
        java.lang.Exception - on error.

      • getCurrentDoc

        public org.w3c.dom.Document getCurrentDoc()

      • castOrFail

        public <T> T castOrFail​(java.lang.Object o,
                        java.lang.Class<T> type,
                        java.lang.String exceptionMsg)
                 throws java.lang.Exception
        Throws:
        java.lang.Exception