Package ghidra.util.xml

Class XmlUtilities

  • public class XmlUtilities
extends java.lang.Object
    A set of utility methods for working with XML.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  XmlUtilities.ThrowingErrorHandler
      Simple SAX error handler that re-throws any SAXParseExceptions as a SAXException.

    • Constructor Summary

      Constructors 
      Constructor Description
      XmlUtilities()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static org.jdom.Element byteArrayToXml​(byte[] bytes)
      Converts the specified byte array into an XML element.
      static org.jdom.input.SAXBuilder createSecureSAXBuilder​(boolean validate, boolean needsDTD)
      Create a SAXBuilder that is not susceptible to XXE.
      static javax.xml.parsers.SAXParserFactory createSecureSAXParserFactory​(boolean needsDTD)
      Create a SAXParserFactory that is not susceptible to XXE.
      static java.lang.String escapeElementEntities​(java.lang.String xml)
      Converts any special or reserved characters in the specified XML string into the equivalent Unicode encoding.
      static org.jdom.Element fromString​(java.lang.String s)
      Convert a String into a JDOM Element.
      static java.util.List<org.jdom.Element> getChildren​(org.jdom.Element ele, java.lang.String childName)
      Type-safe way of getting a list of Elements from JDom.
      static boolean hasInvalidXMLCharacters​(java.lang.String s)
      Tests a string for characters that would cause a problem if added to an xml attribute or element.
      static boolean parseBoolean​(java.lang.String boolStr)
      Parses the given string into a boolean value.
      static int parseBoundedInt​(java.lang.String intStr, int minValue, int maxValue)
      Parses the specified string as a decimal number, returning its integer value.
      static int parseBoundedIntAttr​(org.jdom.Element ele, java.lang.String attrName, int minValue, int maxValue)
      Parses the required attribute as a decimal number, returning its integer value.
      static long parseBoundedLong​(java.lang.String longStr, long minValue, long maxValue)
      Parses the specified string as a decimal number, returning its long integer value.
      static long parseBoundedLongAttr​(org.jdom.Element ele, java.lang.String attrName, long minValue, long maxValue)
      Parses the required attribute as a decimal number, returning its long integer value.
      static int parseInt​(java.lang.String intStr)
      Parse the given string as either a hex number (if it starts with 0x) or a decimal number.
      static int parseInt​(java.lang.String intStr, int defaultValue)
      Parses the optional specified string as a decimal number, returning its integer value.
      static long parseLong​(java.lang.String longStr)
      Parse the given string as either a hex number (if it starts with 0x) or a decimal number.
      static boolean parseOptionalBooleanAttr​(org.jdom.Element ele, java.lang.String attrName, boolean defaultValue)
      Parses the optional attribute as a boolean value, returning its value or the specified defaultValue if missing.
      static int parseOptionalBoundedInt​(java.lang.String intStr, int defaultValue, int minValue, int maxValue)
      Parses the optional specified string as a decimal number, returning its integer value, or defaultValue if the string is null.
      static int parseOptionalBoundedIntAttr​(org.jdom.Element ele, java.lang.String attrName, int defaultValue, int minValue, int maxValue)
      Parses an optional attribute as a decimal number, returning its integer value, or the defaultValue if the attribute is null.
      static long parseOptionalBoundedLongAttr​(org.jdom.Element ele, java.lang.String attrName, long defaultValue, long minValue, long maxValue)
      Parses the required attribute as a decimal number, returning its long integer value.
      static java.lang.String parseOverlayName​(java.lang.String addrStr)
      Parses the overlay name from the specified address string.
      static org.jdom.Document readDocFromFile​(ResourceFile f)
      Read a File and convert to jdom xml doc.
      static org.jdom.Document readDocFromFile​(java.io.File f)
      Read a File and convert to jdom xml doc.
      static java.lang.String requireStringAttr​(org.jdom.Element ele, java.lang.String attrName)
      Throws an IOException with a verbose explanation if the requested attribute is not present or is empty.
      static void setIntAttr​(org.jdom.Element ele, java.lang.String attrName, int attrValue)
      Sets an integer attribute on the specified element.
      static void setStringAttr​(org.jdom.Element ele, java.lang.String attrName, java.lang.String attrValue)
      Sets a string attribute on the specified element.
      static java.lang.String toString​(org.jdom.Element root)
      Converts the specified XML element into a String.
      static java.lang.String unEscapeElementEntities​(java.lang.String escapedXMLString)
      Converts any escaped character entities into their unescaped character equivalents.
      static void writeDocToFile​(org.jdom.Document doc, java.io.File dest)
      Writes a JDOM XML Document to a File.
      static void writePrettyDocToFile​(org.jdom.Document doc, java.io.File dest)
      Writes a JDOM XML Document to a File, with a prettier format than writeDocToFile(Document, File).
      static byte[] xmlToByteArray​(org.jdom.Element root)
      Converts the specified XML element into a byte array.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • FEATURE_DISALLOW_DTD

        public static final java.lang.String FEATURE_DISALLOW_DTD
        See Also:
        Constant Field Values

      • FEATURE_EXTERNAL_GENERAL_ENTITIES

        public static final java.lang.String FEATURE_EXTERNAL_GENERAL_ENTITIES
        See Also:
        Constant Field Values

      • FEATURE_EXTERNAL_PARAMETER_ENTITIES

        public static final java.lang.String FEATURE_EXTERNAL_PARAMETER_ENTITIES
        See Also:
        Constant Field Values

    • Constructor Detail

      • XmlUtilities

        public XmlUtilities()

    • Method Detail

      • escapeElementEntities

        public static java.lang.String escapeElementEntities​(java.lang.String xml)
        Converts any special or reserved characters in the specified XML string into the equivalent Unicode encoding.
        Parameters:
        xml - the XML string
        Returns:
        the encoded XML string

      • unEscapeElementEntities

        public static java.lang.String unEscapeElementEntities​(java.lang.String escapedXMLString)
        Converts any escaped character entities into their unescaped character equivalents. This method is designed to be compatible with the output of escapeElementEntities(String).
        Parameters:
        escapedXMLString - The string with escaped data
        Returns:
        the unescaped string

      • xmlToByteArray

        public static byte[] xmlToByteArray​(org.jdom.Element root)
        Converts the specified XML element into a byte array.
        Parameters:
        root - the root element
        Returns:
        the byte array translation of the given element

      • toString

        public static java.lang.String toString​(org.jdom.Element root)
        Converts the specified XML element into a String.
        Parameters:
        root - the root element
        Returns:
        String translation of the given element

      • fromString

        public static org.jdom.Element fromString​(java.lang.String s)
                                   throws org.jdom.JDOMException,
                                          java.io.IOException
        Convert a String into a JDOM Element.

        Parameters:
        s -
        Returns:
        Throws:
        org.jdom.JDOMException
        java.io.IOException

      • writeDocToFile

        public static void writeDocToFile​(org.jdom.Document doc,
                                  java.io.File dest)
                           throws java.io.IOException
        Writes a JDOM XML Document to a File.

        Parameters:
        doc - JDOM XML Document to write.
        dest - File to write to.
        Throws:
        java.io.IOException - if error when writing file.

      • writePrettyDocToFile

        public static void writePrettyDocToFile​(org.jdom.Document doc,
                                        java.io.File dest)
                                 throws java.io.IOException
        Writes a JDOM XML Document to a File, with a prettier format than writeDocToFile(Document, File).

        Parameters:
        doc - JDOM XML Document to write.
        dest - File to write to.
        Throws:
        java.io.IOException - if error when writing file.

      • readDocFromFile

        public static org.jdom.Document readDocFromFile​(java.io.File f)
                                         throws org.jdom.JDOMException,
                                                java.io.IOException
        Read a File and convert to jdom xml doc.

        Parameters:
        f - File to read
        Returns:
        JDOM Document
        Throws:
        org.jdom.JDOMException - if text in file isn't valid XML
        java.io.IOException - if IO error when reading file.

      • readDocFromFile

        public static org.jdom.Document readDocFromFile​(ResourceFile f)
                                         throws org.jdom.JDOMException,
                                                java.io.IOException
        Read a File and convert to jdom xml doc.

        Parameters:
        f - ResourceFile to read
        Returns:
        JDOM Document
        Throws:
        org.jdom.JDOMException - if text in file isn't valid XML
        java.io.IOException - if IO error when reading file.

      • byteArrayToXml

        public static org.jdom.Element byteArrayToXml​(byte[] bytes)
        Converts the specified byte array into an XML element.
        Parameters:
        bytes - the XML bytes
        Returns:
        an XML element

      • parseOverlayName

        public static java.lang.String parseOverlayName​(java.lang.String addrStr)
        Parses the overlay name from the specified address string. Returns null if the address string does appear to represent an overlay.
        Parameters:
        addrStr - the address string
        Returns:
        the overlay name or null

      • parseInt

        public static int parseInt​(java.lang.String intStr)
        Parse the given string as either a hex number (if it starts with 0x) or a decimal number.
        Parameters:
        intStr - the string to parse into an integer
        Returns:
        the parsed integer.
        Throws:
        java.lang.NumberFormatException - if the given string does not represent a valid integer.

      • parseInt

        public static int parseInt​(java.lang.String intStr,
                           int defaultValue)
                    throws java.lang.NumberFormatException
        Parses the optional specified string as a decimal number, returning its integer value.

        Parameters:
        intStr - string with integer digits, or empty or null
        defaultValue - value to return if intStr is missing
        Returns:
        integer value of the intStr
        Throws:
        java.lang.NumberFormatException - if intStr could not be parsed or the string specifies a value outside the range of a signed 32 bit integer.

      • parseOptionalBoundedInt

        public static int parseOptionalBoundedInt​(java.lang.String intStr,
                                          int defaultValue,
                                          int minValue,
                                          int maxValue)
                                   throws java.lang.NumberFormatException
        Parses the optional specified string as a decimal number, returning its integer value, or defaultValue if the string is null.

        Parameters:
        intStr - string with integer digits, or null.
        defaultValue - value to return if intStr is null.
        minValue - minimum value allowed (inclusive).
        maxValue - maximum value allowed (inclusive).
        Returns:
        integer value of the intStr.
        Throws:
        java.lang.NumberFormatException - if intStr could not be parsed or is out of range.

      • parseBoundedInt

        public static int parseBoundedInt​(java.lang.String intStr,
                                  int minValue,
                                  int maxValue)
                           throws java.lang.NumberFormatException
        Parses the specified string as a decimal number, returning its integer value.

        Parameters:
        intStr - String with integer digits
        minValue - minimum value allowed (inclusive)
        maxValue - maximum value allowed (inclusive)
        Returns:
        integer value of the intStr
        Throws:
        java.lang.NumberFormatException - if intStr is null or empty or could not be parsed or is out of range.

      • parseBoundedIntAttr

        public static int parseBoundedIntAttr​(org.jdom.Element ele,
                                      java.lang.String attrName,
                                      int minValue,
                                      int maxValue)
                               throws java.lang.NumberFormatException
        Parses the required attribute as a decimal number, returning its integer value.

        Parameters:
        ele - JDom element that contains the attribute
        attrName - the name of the xml attribute to parse
        minValue - minimum value allowed (inclusive)
        maxValue - maximum value allowed (inclusive)
        Returns:
        integer value of the attribute
        Throws:
        java.lang.NumberFormatException - if intStr could not be parsed or is out of range.

      • parseOptionalBoundedIntAttr

        public static int parseOptionalBoundedIntAttr​(org.jdom.Element ele,
                                              java.lang.String attrName,
                                              int defaultValue,
                                              int minValue,
                                              int maxValue)
                                       throws java.lang.NumberFormatException
        Parses an optional attribute as a decimal number, returning its integer value, or the defaultValue if the attribute is null.

        Parameters:
        ele - JDOM element that contains the attribute.
        attrName - the name of the xml attribute to parse.
        defaultValue - the default value to return if attribute is missing.
        minValue - minimum value allowed (inclusive).
        maxValue - maximum value allowed (inclusive).
        Returns:
        integer value of the attribute.
        Throws:
        java.lang.NumberFormatException - if the attribute value could not be parsed or is out of range.

      • parseLong

        public static long parseLong​(java.lang.String longStr)
        Parse the given string as either a hex number (if it starts with 0x) or a decimal number.
        Parameters:
        longStr - the string to parse into an long
        Returns:
        the parsed long.
        Throws:
        java.lang.NumberFormatException - if the given string does not represent a valid long.

      • parseBoundedLong

        public static long parseBoundedLong​(java.lang.String longStr,
                                    long minValue,
                                    long maxValue)
                             throws java.lang.NumberFormatException
        Parses the specified string as a decimal number, returning its long integer value.

        Note, using Long.MIN_VALUE and/or Long.MAX_VALUE as lower and upper bounds is problematic and should be avoided as the range check will become a NO-OP and always succeed.

        Parameters:
        longStr - String with integer digits
        minValue - minimum value allowed (inclusive)
        maxValue - maximum value allowed (inclusive)
        Returns:
        long integer value of the longStr
        Throws:
        java.lang.NumberFormatException - if intStr is null or empty or could not be parsed or is out of range.

      • parseBoundedLongAttr

        public static long parseBoundedLongAttr​(org.jdom.Element ele,
                                        java.lang.String attrName,
                                        long minValue,
                                        long maxValue)
                                 throws java.lang.NumberFormatException
        Parses the required attribute as a decimal number, returning its long integer value.

        Note, using Long.MIN_VALUE and/or Long.MAX_VALUE as lower and upper bounds is problematic and should be avoided as the range check will become a NO-OP and always succeed.

        Parameters:
        ele - JDom element that contains the attribute
        attrName - the name of the xml attribute to parse
        minValue - minimum value allowed (inclusive)
        maxValue - maximum value allowed (inclusive)
        Returns:
        long integer value of the attribute
        Throws:
        java.lang.NumberFormatException - if intStr could not be parsed or is out of range.

      • parseOptionalBoundedLongAttr

        public static long parseOptionalBoundedLongAttr​(org.jdom.Element ele,
                                                java.lang.String attrName,
                                                long defaultValue,
                                                long minValue,
                                                long maxValue)
                                         throws java.lang.NumberFormatException
        Parses the required attribute as a decimal number, returning its long integer value.

        Note, using Long.MIN_VALUE and/or Long.MAX_VALUE as lower and upper bounds is problematic and should be avoided as the range check will become a NO-OP and always succeed.

        Parameters:
        ele - JDom element that contains the attribute.
        attrName - the name of the xml attribute to parse.
        defaultValue - the default value to return if attribute is missing.
        minValue - minimum value allowed (inclusive).
        maxValue - maximum value allowed (inclusive).
        Returns:
        long integer value of the attribute.
        Throws:
        java.lang.NumberFormatException - if intStr could not be parsed or is out of range.

      • parseBoolean

        public static boolean parseBoolean​(java.lang.String boolStr)
        Parses the given string into a boolean value. Acceptable inputs are y,n,true,fase. A null input string will return false (useful if optional boolean attribute is false by default)
        Parameters:
        boolStr - the string to parse into a boolean value
        Returns:
        the boolean result.
        Throws:
        XmlAttributeException - if the string in not one of y,n,true,false or null.

      • parseOptionalBooleanAttr

        public static boolean parseOptionalBooleanAttr​(org.jdom.Element ele,
                                               java.lang.String attrName,
                                               boolean defaultValue)
                                        throws java.io.IOException
        Parses the optional attribute as a boolean value, returning its value or the specified defaultValue if missing.
        Parameters:
        ele - JDom element that contains the attribute
        attrName - the name of the xml attribute to parse
        defaultValue - boolean value to return if the attribute is not defined
        Returns:
        boolean equiv of the attribute string value ("y", "true"/"n", "false")
        Throws:
        java.io.IOException - if attribute value is not valid boolean string

      • requireStringAttr

        public static java.lang.String requireStringAttr​(org.jdom.Element ele,
                                                 java.lang.String attrName)
                                          throws java.io.IOException
        Throws an IOException with a verbose explanation if the requested attribute is not present or is empty.

        Parameters:
        ele - JDOM Element that contains the attribute
        attrName - the attribute name
        Returns:
        String value of the attribute (never null or empty)
        Throws:
        java.io.IOException - if attribute is missing or empty

      • setStringAttr

        public static void setStringAttr​(org.jdom.Element ele,
                                 java.lang.String attrName,
                                 java.lang.String attrValue)
        Sets a string attribute on the specified element.
        Parameters:
        ele - JDom element
        attrName - name of attribute
        attrValue - value of attribute, null ok

      • setIntAttr

        public static void setIntAttr​(org.jdom.Element ele,
                              java.lang.String attrName,
                              int attrValue)
        Sets an integer attribute on the specified element.
        Parameters:
        ele - JDom element
        attrName - name of attribute
        attrValue - value of attribute

      • getChildren

        public static java.util.List<org.jdom.Element> getChildren​(org.jdom.Element ele,
                                                           java.lang.String childName)
        Type-safe way of getting a list of Elements from JDom.
        Parameters:
        ele - the parent element
        childName - the name of the children elements to return
        Returns:
        List of elements

      • hasInvalidXMLCharacters

        public static boolean hasInvalidXMLCharacters​(java.lang.String s)
        Tests a string for characters that would cause a problem if added to an xml attribute or element.
        Parameters:
        s - a string
        Returns:
        boolean true if the string will cause a problem if added to an xml attribute or element.

      • createSecureSAXBuilder

        public static org.jdom.input.SAXBuilder createSecureSAXBuilder​(boolean validate,
                                                               boolean needsDTD)
        Create a SAXBuilder that is not susceptible to XXE. This configures the builder to ignore external entities.
        Parameters:
        validate - indicates whether validation should occur
        needsDTD - false to disable doctype declarations altogether
        Returns:
        the configured builder

      • createSecureSAXParserFactory

        public static javax.xml.parsers.SAXParserFactory createSecureSAXParserFactory​(boolean needsDTD)
        Create a SAXParserFactory that is not susceptible to XXE. This configures the factory to ignore external entities.
        Parameters:
        needsDTD - false to disable doctype declarations altogether
        Returns:
        the configured factory