Package ghidra.util.xml
Class XmlUtilities
- java.lang.Object
-
- ghidra.util.xml.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
SimpleSAX error handler
that re-throws anySAXParseException
s as aSAXException
.
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
FEATURE_DISALLOW_DTD
static java.lang.String
FEATURE_EXTERNAL_GENERAL_ENTITIES
static java.lang.String
FEATURE_EXTERNAL_PARAMETER_ENTITIES
-
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 aSAXBuilder
that is not susceptible to XXE.static javax.xml.parsers.SAXParserFactory
createSecureSAXParserFactory(boolean needsDTD)
Create aSAXParserFactory
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 JDOMElement
.static java.util.List<org.jdom.Element>
getChildren(org.jdom.Element ele, java.lang.String childName)
Type-safe way of getting a list ofElement
s 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 anIOException
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 XMLDocument
to aFile
.static void
writePrettyDocToFile(org.jdom.Document doc, java.io.File dest)
static byte[]
xmlToByteArray(org.jdom.Element root)
Converts the specified XML element into a byte array.
-
-
-
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
-
-
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 ofescapeElementEntities(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 JDOMElement
.- 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 XMLDocument
to aFile
.- Parameters:
doc
- JDOM XMLDocument
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
- Parameters:
doc
- JDOM XMLDocument
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 XMLjava.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 XMLjava.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 nulldefaultValue
- 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 digitsminValue
- 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 attributeattrName
- the name of the xml attribute to parseminValue
- 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/orLong.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 digitsminValue
- 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/orLong.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 attributeattrName
- the name of the xml attribute to parseminValue
- 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/orLong.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 attributeattrName
- the name of the xml attribute to parsedefaultValue
- 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 anIOException
with a verbose explanation if the requested attribute is not present or is empty.- Parameters:
ele
- JDOMElement
that contains the attributeattrName
- 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 elementattrName
- name of attributeattrValue
- 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 elementattrName
- name of attributeattrValue
- 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 ofElement
s from JDom.- Parameters:
ele
- the parent elementchildName
- the name of the children elements to return- Returns:
- List<Element> 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 aSAXBuilder
that is not susceptible to XXE. This configures the builder to ignore external entities.- Parameters:
validate
- indicates whether validation should occurneedsDTD
- false to disable doctype declarations altogether- Returns:
- the configured builder
-
createSecureSAXParserFactory
public static javax.xml.parsers.SAXParserFactory createSecureSAXParserFactory(boolean needsDTD)
Create aSAXParserFactory
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
-
-