Class XmlToolkit


  • public final class XmlToolkit
    extends java.lang.Object
    Class containing helper methods for XML processing.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static java.util.regex.Pattern AMP  
      private static java.util.regex.Pattern APOS  
      private static java.util.regex.Pattern CR  
      private static java.util.regex.Pattern GT  
      private static java.util.logging.Logger LOGGER  
      private static java.util.regex.Pattern LT  
      private static java.util.regex.Pattern NL  
      private static java.util.regex.Pattern QUOT  
      private static java.util.regex.Pattern TAB  
      private static java.lang.String XML_PARSER_DISALLOW_DOCTYPE_ATTRIBUTE  
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private XmlToolkit()
      The constructor is private since no instances should ever be created.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static javax.xml.parsers.DocumentBuilderFactory createDocumentBuildFactoryInstance()
      Create a document builder factory with safe settings.
      static org.w3c.dom.Element createElement​(org.w3c.dom.Element parentNode, java.lang.String tagName)
      Adds a child element with the name tagName to the parent and returns the new child element.
      static org.w3c.dom.Document createNewDocument​(java.lang.String rootElementName)
      Creates a new empty XML document.
      static javax.xml.parsers.SAXParserFactory createSAXParserFactory()
      Create a SAX parser factory with safe settings.
      static javax.xml.transform.TransformerFactory createTransformerFactory()
      Create a transformer factory with safe settings.
      static java.lang.String escapeAll​(java.lang.String s)  
      static java.lang.String escapeTagContent​(java.lang.String s)  
      static org.w3c.dom.Element getChildElementOrNull​(org.w3c.dom.Element parent, java.lang.String name)
      Returns the child element with the specified tag name of the specified parent node.
      static java.util.List<org.w3c.dom.Element> getChildElementsByTag​(org.w3c.dom.Node contextNode, java.lang.String tag)
      Returns all the children from a node with a tag matching the tag argument.
      private static javax.xml.parsers.DocumentBuilder getDocumentBuilder()
      Returns a document builder for XML documents.
      static org.w3c.dom.Element getOrCreateElement​(org.w3c.dom.Element parentNode, java.lang.String tagName)
      Returns the child element with the specified tag name of the specified parent node.
      static java.lang.String getSetting​(org.w3c.dom.Element parent, java.lang.String settingName, java.lang.String defaultValue)
      Returns the value of the setting with the specified name or a default value if the setting had no value.
      static java.lang.String getStringValue​(org.w3c.dom.Element element)
      Returns the content between the tags of the element, for example <tag>hello </tag> where the value is "hello".
      static org.w3c.dom.Document loadDocumentFromFile​(java.io.File file)
      Loads an XML document from the specified file.
      static org.w3c.dom.Document loadDocumentFromStream​(java.io.InputStream stream)
      Loads an XML document from the specified stream.
      static org.w3c.dom.Document loadDocumentFromString​(java.lang.String doc)
      Loads an XML document from its string representation.
      static java.lang.String prettyPrint​(org.w3c.dom.Element node)
      Pretty prints an XML document to a string, starting from the specified element.
      static void prettyPrint​(org.w3c.dom.Element node, java.io.Writer wrt)
      Pretty prints an XML document to a writer, starting from the specified element.
      static void setSetting​(org.w3c.dom.Element parentNode, java.lang.String settingName, java.lang.String settingValue)
      Sets the value of a a "setting" element.
      static void setStringValue​(org.w3c.dom.Element element, java.lang.String value)
      Sets the text value as a text node child of a an element.
      static void storeDocumentToFile​(org.w3c.dom.Document doc, java.io.File file)
      Stores an XML document in a file.
      static java.lang.String storeDocumentToString​(org.w3c.dom.Document doc)
      Stores an XML document as a string.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • XML_PARSER_DISALLOW_DOCTYPE_ATTRIBUTE

        private static final java.lang.String XML_PARSER_DISALLOW_DOCTYPE_ATTRIBUTE
        See Also:
        Constant Field Values
      • LOGGER

        private static final java.util.logging.Logger LOGGER
      • AMP

        private static final java.util.regex.Pattern AMP
      • LT

        private static final java.util.regex.Pattern LT
      • GT

        private static final java.util.regex.Pattern GT
      • QUOT

        private static final java.util.regex.Pattern QUOT
      • APOS

        private static final java.util.regex.Pattern APOS
      • CR

        private static final java.util.regex.Pattern CR
      • NL

        private static final java.util.regex.Pattern NL
      • TAB

        private static final java.util.regex.Pattern TAB
    • Constructor Detail

      • XmlToolkit

        private XmlToolkit()
        The constructor is private since no instances should ever be created.
    • Method Detail

      • getOrCreateElement

        public static org.w3c.dom.Element getOrCreateElement​(org.w3c.dom.Element parentNode,
                                                             java.lang.String tagName)
        Returns the child element with the specified tag name of the specified parent node. If no such child element is found, a new element with the specified tag name is created and returned.
        Parameters:
        parentNode - parent node for the wanted element
        tagName - name of the wanted element
        Returns:
        the child element
        See Also:
        getChildElementOrNull(Element, String)
      • createElement

        public static org.w3c.dom.Element createElement​(org.w3c.dom.Element parentNode,
                                                        java.lang.String tagName)
        Adds a child element with the name tagName to the parent and returns the new child element.
        Parameters:
        parentNode - parent node to add the new element to
        tagName - the name of the new child element
        Returns:
        the new child element
      • setSetting

        public static void setSetting​(org.w3c.dom.Element parentNode,
                                      java.lang.String settingName,
                                      java.lang.String settingValue)
        Sets the value of a a "setting" element. If it already exists it will be updated. If it does not exist it will be created. If the setting element already exists, then there must not be any child elements to it other than a text value.
        Parameters:
        parentNode - parent node of the setting element
        settingName - tag name of the setting element
        settingValue - the value to set
      • createNewDocument

        public static org.w3c.dom.Document createNewDocument​(java.lang.String rootElementName)
                                                      throws java.io.IOException
        Creates a new empty XML document.
        Parameters:
        rootElementName - the name of the root element
        Returns:
        an empty document
        Throws:
        java.io.IOException - if there is a problem creating the XML document
      • createSAXParserFactory

        public static javax.xml.parsers.SAXParserFactory createSAXParserFactory()
                                                                         throws org.xml.sax.SAXNotRecognizedException,
                                                                                org.xml.sax.SAXNotSupportedException,
                                                                                javax.xml.parsers.ParserConfigurationException
        Create a SAX parser factory with safe settings.

        See OWASP XXE cheat sheet.

        Returns:
        a new SAX parser factory
        Throws:
        org.xml.sax.SAXNotRecognizedException
        org.xml.sax.SAXNotSupportedException
        javax.xml.parsers.ParserConfigurationException
      • createDocumentBuildFactoryInstance

        public static javax.xml.parsers.DocumentBuilderFactory createDocumentBuildFactoryInstance()
                                                                                           throws javax.xml.parsers.ParserConfigurationException
        Create a document builder factory with safe settings.

        See OWASP XXE cheat sheet.

        Returns:
        a new document builder factory
        Throws:
        javax.xml.parsers.ParserConfigurationException
      • createTransformerFactory

        public static javax.xml.transform.TransformerFactory createTransformerFactory()
                                                                               throws javax.xml.transform.TransformerFactoryConfigurationError,
                                                                                      javax.xml.transform.TransformerConfigurationException
        Create a transformer factory with safe settings.

        See OWASP XXE cheat sheet.

        Returns:
        a new transformer factory
        Throws:
        javax.xml.transform.TransformerFactoryConfigurationError
        javax.xml.transform.TransformerConfigurationException
      • setStringValue

        public static void setStringValue​(org.w3c.dom.Element element,
                                          java.lang.String value)
        Sets the text value as a text node child of a an element. The element must not have any other child elements.
        Parameters:
        element - the element to set the text value for
        value - the new value to set
      • getSetting

        public static java.lang.String getSetting​(org.w3c.dom.Element parent,
                                                  java.lang.String settingName,
                                                  java.lang.String defaultValue)
        Returns the value of the setting with the specified name or a default value if the setting had no value.

        Since everything should have a default value, no other version of get setting exists. This method implicitly builds the setting node with a default value if none is found.

        Parameters:
        parent - the parent element whose children to search for the settings node.
        settingName - name of the setting
        defaultValue - default value to return if setting is empty
        Returns:
        see above.
      • getStringValue

        public static java.lang.String getStringValue​(org.w3c.dom.Element element)
        Returns the content between the tags of the element, for example <tag>hello </tag> where the value is "hello". If the element itself or its child is null, null will be returned. This method will only return a non-null String if the child node of the element is a text node.
        Parameters:
        element - the element from which to extract the text node.
        Returns:
        the String value of the text node.
      • prettyPrint

        public static java.lang.String prettyPrint​(org.w3c.dom.Element node)
        Pretty prints an XML document to a string, starting from the specified element.
        Parameters:
        node - node from which to start pretty printing
        Returns:
        a string containing the pretty printed document
      • prettyPrint

        public static void prettyPrint​(org.w3c.dom.Element node,
                                       java.io.Writer wrt)
        Pretty prints an XML document to a writer, starting from the specified element.
        Parameters:
        node - node from which to start pretty printing
        wrt - writer to write the document to
      • getChildElementsByTag

        public static java.util.List<org.w3c.dom.Element> getChildElementsByTag​(org.w3c.dom.Node contextNode,
                                                                                java.lang.String tag)
        Returns all the children from a node with a tag matching the tag argument.
        Parameters:
        contextNode - node whose children to search
        tag - the tag to search for
        Returns:
        A list of elements with the found nodes. Will return an empty list if no matching element could be found.
      • getDocumentBuilder

        private static javax.xml.parsers.DocumentBuilder getDocumentBuilder()
        Returns a document builder for XML documents.
        Returns:
        a new document builder
      • loadDocumentFromFile

        public static org.w3c.dom.Document loadDocumentFromFile​(java.io.File file)
                                                         throws org.xml.sax.SAXException,
                                                                java.io.IOException
        Loads an XML document from the specified file.
        Parameters:
        file - the file from which to read the document
        Returns:
        the parsed XML document
        Throws:
        org.xml.sax.SAXException - if the document could not be parsed
        java.io.IOException - if the stream could not be read
      • loadDocumentFromStream

        public static org.w3c.dom.Document loadDocumentFromStream​(java.io.InputStream stream)
                                                           throws org.xml.sax.SAXException,
                                                                  java.io.IOException
        Loads an XML document from the specified stream.
        Parameters:
        stream - the input stream from which to read the document
        Returns:
        the parsed XML document
        Throws:
        org.xml.sax.SAXException - if the document could not be parsed
        java.io.IOException - if the stream could not be read
      • loadDocumentFromString

        public static org.w3c.dom.Document loadDocumentFromString​(java.lang.String doc)
                                                           throws org.xml.sax.SAXException
        Loads an XML document from its string representation.
        Parameters:
        doc - the string to read from
        Returns:
        the parsed XML document
        Throws:
        org.xml.sax.SAXException - if the document could not be parsed
        java.lang.NullPointerException - if the input string is null
      • storeDocumentToFile

        public static void storeDocumentToFile​(org.w3c.dom.Document doc,
                                               java.io.File file)
                                        throws java.io.IOException
        Stores an XML document in a file.
        Parameters:
        doc - the XML document to store
        file - the file to store it in
        Throws:
        java.io.IOException - if the file could not written
      • storeDocumentToString

        public static java.lang.String storeDocumentToString​(org.w3c.dom.Document doc)
        Stores an XML document as a string.
        Parameters:
        doc - the XML document to store
        Returns:
        the XML document as a string
      • getChildElementOrNull

        public static org.w3c.dom.Element getChildElementOrNull​(org.w3c.dom.Element parent,
                                                                java.lang.String name)
        Returns the child element with the specified tag name of the specified parent node. If no such child element is found, null is returned.
        Parameters:
        parent - parent node for the wanted element
        name - name of the wanted element
        Returns:
        the child element, or null if no such element exists
        See Also:
        getOrCreateElement(Element, String)
      • escapeAll

        public static java.lang.String escapeAll​(java.lang.String s)
      • escapeTagContent

        public static java.lang.String escapeTagContent​(java.lang.String s)