Package ghidra.util.xml

Class XmlUtilities

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

  • Field Details

  • Constructor Details

    • XmlUtilities

      public XmlUtilities()

  • Method Details

    • escapeElementEntities

      public static String escapeElementEntities(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 String unEscapeElementEntities(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 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(String s) throws org.jdom.JDOMException, IOException
      Convert a String into a JDOM Element.

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

    • writeDocToFile

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

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

    • writePrettyDocToFile

      public static void writePrettyDocToFile(org.jdom.Document doc, File dest) throws 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:
      IOException - if error when writing file.

    • readDocFromFile

      public static org.jdom.Document readDocFromFile(File f) throws org.jdom.JDOMException, 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
      IOException - if IO error when reading file.

    • readDocFromFile

      public static org.jdom.Document readDocFromFile(ResourceFile f) throws org.jdom.JDOMException, 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
      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 String parseOverlayName(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(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:
      NumberFormatException - if the given string does not represent a valid integer.

    • parseInt

      public static int parseInt(String intStr, int defaultValue) throws 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:
      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(String intStr, int defaultValue, int minValue, int maxValue) throws 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:
      NumberFormatException - if intStr could not be parsed or is out of range.

    • parseBoundedInt

      public static int parseBoundedInt(String intStr, int minValue, int maxValue) throws 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:
      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, String attrName, int minValue, int maxValue) throws 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:
      NumberFormatException - if intStr could not be parsed or is out of range.

    • parseOptionalBoundedIntAttr

      public static int parseOptionalBoundedIntAttr(org.jdom.Element ele, String attrName, int defaultValue, int minValue, int maxValue) throws 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:
      NumberFormatException - if the attribute value could not be parsed or is out of range.

    • parseLong

      public static long parseLong(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:
      NumberFormatException - if the given string does not represent a valid long.

    • parseBoundedLong

      public static long parseBoundedLong(String longStr, long minValue, long maxValue) throws 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:
      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, String attrName, long minValue, long maxValue) throws 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:
      NumberFormatException - if intStr could not be parsed or is out of range.

    • parseOptionalBoundedLongAttr

      public static long parseOptionalBoundedLongAttr(org.jdom.Element ele, String attrName, long defaultValue, long minValue, long maxValue) throws 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:
      NumberFormatException - if intStr could not be parsed or is out of range.

    • parseBoolean

      public static boolean parseBoolean(String boolStr) throws XmlAttributeException
      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, String attrName, boolean defaultValue) throws 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:
      IOException - if attribute value is not valid boolean string

    • requireStringAttr

      public static String requireStringAttr(org.jdom.Element ele, String attrName) throws 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:
      IOException - if attribute is missing or empty

    • setStringAttr

      public static void setStringAttr(org.jdom.Element ele, String attrName, 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, 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 List<org.jdom.Element> getChildren(org.jdom.Element ele, 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<Element> of elements

    • hasInvalidXMLCharacters

      public static boolean hasInvalidXMLCharacters(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 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