public final class XmlHelper
extends java.lang.Object
Generally, all XML-related processing should use this class for document object model creation, parsing, and serialization. This ensures that the same XML support implementation is used consistently, since assumptions are made in several methods herein as to the underlying implementation classes.
Methods which rely on a vendor-specific Document
implementation are:
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
LINE_NUMBER_KEY
The key to element user data that holds the element's file location when
parseWithPositions(InputStream, boolean, String, boolean) is used. |
static java.lang.String |
MAP_ATTR_KEY
Attribute name for a map entry key.
|
static java.lang.String |
MAP_ATTR_VALUE
Attribute name for a map entry value.
|
static java.lang.String |
MAP_ELEM_ENTRY
Element name for a map entry.
|
static java.lang.String |
MAP_ELEM_ROOT
Element name for the map root.
|
private static java.lang.ThreadLocal<java.lang.ref.SoftReference<javax.xml.parsers.DocumentBuilderFactory>> |
nonValidatingFactory
Thread-local, non-validating, document builder factory.
|
private static java.lang.ThreadLocal<java.lang.ref.SoftReference<javax.xml.parsers.DocumentBuilderFactory>> |
validatingFactory
Thread-local, validating, document builder factory.
|
Modifier | Constructor and Description |
---|---|
private |
XmlHelper()
Private constructor to prevent instances of this class from being
created.
|
Modifier and Type | Method and Description |
---|---|
static java.lang.String |
convertBytesToHex(byte[] bytes)
To enable XML to handle binary data or to handle the case where a
string including invalid characters must be encoded in XML, this method
will convert an entire byte array into a hexidecimal string form where
each byte is represented by an equivalent two character hexidecimal
encoding.
|
static byte[] |
convertHexToBytes(java.lang.String hex)
To enable XML to handle binary data or to handle the case where a
string including invalid characters must be encoded in XML, this method
will convert an encoded hexidecimal string into the corresponding
byte array.
|
static java.lang.String |
convertInvalidCharsToNcr(java.lang.String text)
Converts the set of ASCII characters which are invalid (to be stored in
the text of an XML attribute) into the associated valid representation
using the 'Numeric Character Reference' or NCR.
|
static java.lang.String |
convertNcrToAscii(java.lang.String text)
Converts certain 'Numeric Character References' or NCRs into the
into the associated valid ASCII representation.
|
static java.lang.String |
getAttribute(org.w3c.dom.Element elem,
java.lang.String key)
Extract the value of an attribute from an XML element, decoding it
from hex format first if necessary.
|
static boolean |
getAttributeBoolean(org.w3c.dom.Element elem,
java.lang.String name,
boolean defVal)
Get the specified attribute and convert it to a boolean value.
|
static int |
getAttributeInt(org.w3c.dom.Element elem,
java.lang.String name,
int defVal)
Get the specified attribute and convert it to an integer.
|
static long |
getAttributeLong(org.w3c.dom.Element elem,
java.lang.String name,
long defVal)
Get the specified attribute and convert it to a 64-bit integer.
|
(package private) static javax.xml.parsers.DocumentBuilderFactory |
getDocumentBuilderFactory(boolean validating,
boolean isNamespaceAware)
Get a document builder factory for the current thread.
|
static java.lang.String |
getText(org.w3c.dom.Node node)
Get the string data, if any, from a node, whether it is wrapped in a
CDATA section or not.
|
static void |
loadStringMap(java.util.Map<java.lang.String,java.lang.String> map,
java.lang.String filename,
boolean force)
Load the given map with entries read from the given filename.
|
static boolean |
needsConversionToHex(byte[] bytes)
Detects the presence of any character from the set of ASCII characters
which are invalid for storage as part of a readable string (this
is the same as not being able to be directly stored in an XML file).
|
static org.w3c.dom.Document |
newDocument()
Create and return a new, empty
Document XML node. |
static org.w3c.dom.Document |
newDocument(java.lang.String qualifiedName,
java.lang.String publicId,
java.lang.String systemId)
Create an XML document with an optional DOCTYPE tag (if the proper
information is supplied).
|
static org.w3c.dom.Document |
newDocument(java.lang.String qualifiedName,
java.lang.String publicId,
java.lang.String systemId,
java.lang.String namespaceURI)
Create an XML document with an optional DOCTYPE tag (if the proper
information is supplied).
|
static org.w3c.dom.Document |
parse(java.io.File file)
Parse the specified XML file into a document object model (DOM) using a
non-validating parser.
|
static org.w3c.dom.Document |
parse(java.io.File file,
boolean validate,
java.lang.String systemId)
Parse the specified XML file into a document object model (DOM).
|
static org.w3c.dom.Document |
parse(java.io.InputStream in)
Parse the specified input stream into a document object model (DOM)
using a non-validating parser.
|
static org.w3c.dom.Document |
parse(java.io.InputStream in,
boolean validate,
boolean isNamespaceAware,
logical success)
Parse the specified input stream into a document object model (DOM), optionally validating
the document.
|
static org.w3c.dom.Document |
parse(java.io.InputStream in,
boolean validate,
org.xml.sax.EntityResolver resolver,
org.xml.sax.ErrorHandler handler)
Parse the specified input stream into a document object model (DOM),
optionally validating the document.
|
static org.w3c.dom.Document |
parse(java.io.InputStream in,
boolean validate,
java.lang.String systemId)
Parse the specified input stream into a document object model (DOM),
optionally validating the document.
|
static org.w3c.dom.Document |
parse(java.io.InputStream in,
boolean validate,
java.lang.String systemId,
boolean isNamespaceAware)
Parse the specified input stream into a document object model (DOM),
optionally validating the document.
|
static org.w3c.dom.Document |
parse(java.lang.String filename)
Parse the XML file represented by
filename into a document
object model (DOM) using a non-validating parser. |
static org.w3c.dom.Document |
parse(java.lang.String filename,
boolean validate,
java.lang.String systemId,
boolean isNamespaceAware)
Parse the XML file represented by
filename into a document
object model (DOM). |
static org.w3c.dom.Document |
parseWithPositions(java.io.InputStream in,
boolean validate,
java.lang.String systemId,
boolean isNamespaceAware)
Parse the specified input stream into a document object model (DOM),
optionally validating the document.
|
static void |
setAttribute(org.w3c.dom.Element elem,
java.lang.String key,
java.lang.String value)
Set a value into an element's attribute, encoding it into a safe format
first if it contains non-printing characters.
|
static void |
setDoctype(org.w3c.dom.Document dom,
java.lang.String publicId,
java.lang.String systemId,
java.lang.String internalSubset)
Deprecated.
|
static void |
write(org.w3c.dom.Document dom,
java.io.File file)
Serialize the content in the specified XML document in a pretty printed
text format to the specified file.
|
static void |
write(org.w3c.dom.Document dom,
java.io.OutputStream os)
Serialize the content in the specified XML document in a pretty printed
text format to the specified writer.
|
static void |
write(org.w3c.dom.Document dom,
java.io.OutputStream os,
boolean pretty)
Serialize the content in the specified XML document in text form to the
specified output stream, optionally applying pretty print formatting.
|
static void |
write(org.w3c.dom.Document dom,
java.io.OutputStream os,
boolean pretty,
boolean omitXMLDec)
Serialize the content in the specified XML document in text form to the
specified output stream, optionally applying pretty print formatting.
|
static void |
write(org.w3c.dom.Document dom,
java.lang.String filename)
Serialize the content in the specified XML document in a pretty printed
text format to the file with the specified name.
|
public static final java.lang.String LINE_NUMBER_KEY
parseWithPositions(InputStream, boolean, String, boolean)
is used.public static final java.lang.String MAP_ELEM_ROOT
public static final java.lang.String MAP_ELEM_ENTRY
public static final java.lang.String MAP_ATTR_KEY
public static final java.lang.String MAP_ATTR_VALUE
private static final java.lang.ThreadLocal<java.lang.ref.SoftReference<javax.xml.parsers.DocumentBuilderFactory>> validatingFactory
private static final java.lang.ThreadLocal<java.lang.ref.SoftReference<javax.xml.parsers.DocumentBuilderFactory>> nonValidatingFactory
private XmlHelper()
public static org.w3c.dom.Document newDocument(java.lang.String qualifiedName, java.lang.String publicId, java.lang.String systemId, java.lang.String namespaceURI) throws javax.xml.parsers.ParserConfigurationException
qualifiedName
- Name of the document type to be created. May be
null
.publicId
- PUBLIC
portion of doctype. If null
,
the !DOCTYPE
element will be empty.systemId
- Optional system portion of doctype. If null
, only
the publicId
will be used.namespaceURI
- Namespace URI of root node. If null
, then node creates without
namespace URI.javax.xml.parsers.ParserConfigurationException
- if the XML document builder has been configured incorrectly.public static org.w3c.dom.Document newDocument(java.lang.String qualifiedName, java.lang.String publicId, java.lang.String systemId) throws javax.xml.parsers.ParserConfigurationException
qualifiedName
- Name of the document type to be created. May be
null
.publicId
- PUBLIC
portion of doctype. If null
,
the !DOCTYPE
element will be empty.systemId
- Optional system portion of doctype. If null
, only
the publicId
will be used.javax.xml.parsers.ParserConfigurationException
- if the XML document builder has been configured incorrectly.public static org.w3c.dom.Document newDocument() throws javax.xml.parsers.ParserConfigurationException
Document
XML node.javax.xml.parsers.ParserConfigurationException
- if the XML parser has been configured incorrectly.public static void setDoctype(org.w3c.dom.Document dom, java.lang.String publicId, java.lang.String systemId, java.lang.String internalSubset) throws java.lang.UnsupportedOperationException
DOCTYPE
element for an XML DOM which is built up
programmatically (as opposed to one which is created by parsing an
existing document). Since editing the DOCTYPE
is not
supported by the standard Document
interface, this method
makes the assumption that dom
is an object which was
created by this helper class (either by parsing an existing document
or via the newDocument
method).dom
- Document which will have its doctype set.publicId
- PUBLIC
portion of doctype. If null
,
the !DOCTYPE
element will be empty.systemId
- Optional system portion of doctype. If null
, only
the publicId
will be used.internalSubset
- Optional, internal subset portion of doctype.java.lang.UnsupportedOperationException
- always; this method is deprecated because it could not be
implemented in a vendor-neutral manner.public static org.w3c.dom.Document parse(java.lang.String filename) throws javax.xml.parsers.ParserConfigurationException, java.io.IOException, org.xml.sax.SAXException
filename
into a document
object model (DOM) using a non-validating parser. Delegates to the
parse(InputStream,boolean,String)
method.filename
- XML data filename.javax.xml.parsers.ParserConfigurationException
- if the XML parser has been configured incorrectly.java.io.IOException
- if an I/O error occurs during parsing or stream cleanup.org.xml.sax.SAXException
- if an error occurs parsing the XML within the specified file.public static org.w3c.dom.Document parse(java.lang.String filename, boolean validate, java.lang.String systemId, boolean isNamespaceAware) throws javax.xml.parsers.ParserConfigurationException, java.io.IOException, org.xml.sax.SAXException
filename
into a document
object model (DOM). Delegates to the parse(InputStream,boolean,String)
method.filename
- XML data filename.validate
- true
to use a validating parser,
false
to parse the document without validation.systemId
- A base for resolving relative URIs. Used if validating with
a system DOCTYPE which specifies a relative URI for the DTD.isNamespaceAware
- true if the parser produced will provide support for XML namespaces;
false otherwise.javax.xml.parsers.ParserConfigurationException
- if the XML parser has been configured incorrectly.java.io.IOException
- if an I/O error occurs during parsing or stream cleanup.org.xml.sax.SAXException
- if an error occurs parsing the XML within the specified file.public static org.w3c.dom.Document parse(java.io.File file) throws javax.xml.parsers.ParserConfigurationException, java.io.IOException, org.xml.sax.SAXException
parse(InputStream,boolean,String)
method.file
- A file of XML data.javax.xml.parsers.ParserConfigurationException
- if the XML parser has been configured incorrectly.java.io.IOException
- if an I/O error occurs during parsing or stream cleanup.org.xml.sax.SAXException
- if an error occurs parsing the XML within file
.public static org.w3c.dom.Document parse(java.io.File file, boolean validate, java.lang.String systemId) throws javax.xml.parsers.ParserConfigurationException, java.io.IOException, org.xml.sax.SAXException
parse(InputStream,boolean,String)
method.file
- A file of XML data.validate
- true
to use a validating parser,
false
to parse the document without validation.systemId
- A base for resolving relative URIs. Used if validating with
a system DOCTYPE which specifies a relative URI for the DTD.javax.xml.parsers.ParserConfigurationException
- if the XML parser has been configured incorrectly.java.io.IOException
- if an I/O error occurs during parsing or stream cleanup.org.xml.sax.SAXException
- if an error occurs parsing the XML within file
.public static org.w3c.dom.Document parse(java.io.InputStream in) throws javax.xml.parsers.ParserConfigurationException, java.io.IOException, org.xml.sax.SAXException
parse(InputStream,boolean,String)
method.in
- An input stream of XML data.javax.xml.parsers.ParserConfigurationException
- if the XML parser has been configured incorrectly.java.io.IOException
- if an I/O error occurs during parsing or stream cleanup.org.xml.sax.SAXException
- if an error occurs parsing the XML within in
.public static org.w3c.dom.Document parse(java.io.InputStream in, boolean validate, java.lang.String systemId) throws javax.xml.parsers.ParserConfigurationException, java.io.IOException, org.xml.sax.SAXException
in
- An input stream of XML data.validate
- true
to use a validating parser,
false
to parse the document without validation.systemId
- A base for resolving relative URIs. Used if validating with
a system DOCTYPE which specifies a relative URI for the DTD.javax.xml.parsers.ParserConfigurationException
- if the XML parser has been configured incorrectly.java.io.IOException
- if an I/O error occurs during parsing or stream cleanup.org.xml.sax.SAXException
- if an error occurs parsing the XML within in
.public static org.w3c.dom.Document parse(java.io.InputStream in, boolean validate, java.lang.String systemId, boolean isNamespaceAware) throws javax.xml.parsers.ParserConfigurationException, java.io.IOException, org.xml.sax.SAXException
in
- An input stream of XML data.validate
- true
to use a validating parser,
false
to parse the document without validation.systemId
- A base for resolving relative URIs. Used if validating with
a system DOCTYPE which specifies a relative URI for the DTD.isNamespaceAware
- true if the parser produced will provide support for XML namespaces;
false otherwise.javax.xml.parsers.ParserConfigurationException
- if the XML parser has been configured incorrectly.java.io.IOException
- if an I/O error occurs during parsing or stream cleanup.org.xml.sax.SAXException
- if an error occurs parsing the XML within in
.public static org.w3c.dom.Document parse(java.io.InputStream in, boolean validate, boolean isNamespaceAware, logical success) throws javax.xml.parsers.ParserConfigurationException, java.io.IOException, org.xml.sax.SAXException
in
- An input stream of XML data.validate
- true
to use a validating parser, false
to parse the document
without validation.isNamespaceAware
- true if the parser produced will provide support for XML namespaces;
false otherwise.success
- Output parameter. May be null
The method will initialize it to true
only if the parsing was successful. If xml stream failed validation or any other
fatal error is encountered, the value is set to false
.validate = true
but the document failed validation, it is still returned,
provided there were no fatal errors. However, the success
output parameter
will be set to false
.javax.xml.parsers.ParserConfigurationException
- if the XML parser has been configured incorrectly.java.io.IOException
- if an I/O error occurs during parsing or stream cleanup.org.xml.sax.SAXException
- if an error occurs parsing the XML within in
.public static org.w3c.dom.Document parse(java.io.InputStream in, boolean validate, org.xml.sax.EntityResolver resolver, org.xml.sax.ErrorHandler handler) throws javax.xml.parsers.ParserConfigurationException, java.io.IOException, org.xml.sax.SAXException
EntityResolver
, which may be necessary for certain parsing
cases. For example, a specialized entity resolver may be used to
resolve a locally provided DTD which is referred to by a public URL in
the XML document's DOCTYPE node, to avoid using the incorrect (public)
version of the DTD.in
- An input stream of XML data.validate
- true
to use a validating parser,
false
to parse the document without validation.resolver
- Object which provides custom resolution for external entities
during SAX parsing.handler
- Custom SAX error handler.javax.xml.parsers.ParserConfigurationException
- if the XML parser has been configured incorrectly.java.io.IOException
- if an I/O error occurs during parsing or stream cleanup.org.xml.sax.SAXException
- if an error occurs parsing the XML within in
.public static org.w3c.dom.Document parseWithPositions(java.io.InputStream in, boolean validate, java.lang.String systemId, boolean isNamespaceAware) throws java.io.IOException, org.xml.sax.SAXException, javax.xml.parsers.ParserConfigurationException
This parsing method stores the element's line number in the source stream
in the element's user data under the key LINE_NUMBER_KEY
.
in
- An input stream of XML data.validate
- true
to use a validating parser,
false
to parse the document without validation.systemId
- A base for resolving relative URIs. Used if validating with
a system DOCTYPE which specifies a relative URI for the DTD.isNamespaceAware
- true if the parser produced will provide support for XML namespaces;
false otherwise.javax.xml.parsers.ParserConfigurationException
- if the XML parser has been configured incorrectly.java.io.IOException
- if an I/O error occurs during parsing or stream cleanup.org.xml.sax.SAXException
- if an error occurs parsing the XML within in
.public static void loadStringMap(java.util.Map<java.lang.String,java.lang.String> map, java.lang.String filename, boolean force)
<map> <entry key="a" value="b"/> <entry key="c" value="d"/> </map>
Any failure aborts silently.
map
- The map to load.filename
- The file to read from.force
- Force map keys to lowercase.public static java.lang.String getText(org.w3c.dom.Node node)
node
- Node which presumably contains string data directly in a text
node child or in a CDATA section grandchild.null
if none is found.public static void write(org.w3c.dom.Document dom, java.io.OutputStream os) throws java.io.IOException
dom
- Document object model to be serialized.os
- Target character output stream.java.io.IOException
- if an error occurs writing to writer
or cleaning
up streams.public static void write(org.w3c.dom.Document dom, java.io.OutputStream os, boolean pretty) throws java.io.IOException
dom
- Document object model to be serialized.os
- Target character output stream.pretty
- if true
, this method will attempt to format the
XML using line breaks and hierarchical indents; else the
output will contain no special formatting.java.io.IOException
- if an error occurs writing to writer
or cleaning
up streams.public static void write(org.w3c.dom.Document dom, java.io.OutputStream os, boolean pretty, boolean omitXMLDec) throws java.io.IOException
dom
- Document object model to be serialized.os
- Target character output stream.pretty
- if true
, this method will attempt to format the
XML using line breaks and hierarchical indents; else the
output will contain no special formatting.omitXMLDec
- Flag indicating if the XML declaration should be omitted.java.io.IOException
- if an error occurs writing to writer
or cleaning
up streams.public static void write(org.w3c.dom.Document dom, java.io.File file) throws java.io.IOException
dom
- Document object model to be serialized.file
- Target file.java.io.IOException
- if an error occurs writing to file
or cleaning
up streams.public static void write(org.w3c.dom.Document dom, java.lang.String filename) throws java.io.IOException
dom
- Document object model to be serialized.filename
- Target filename.java.io.IOException
- if an error occurs writing to filename
or cleaning
up streams.public static java.lang.String convertInvalidCharsToNcr(java.lang.String text)
The following ASCII character ranges are escaped as described above (since they cannot otherwise be represented in the text of an XML attribute): 0x00 - 0x08, 0x0B - 0x0C, 0x0E - 0x1F.
Note that other invalid XML characters exist outside of the ASCII range. This method does not handle such characters.
text
- The string which may contain invalid characters.public static java.lang.String convertNcrToAscii(java.lang.String text)
The following ASCII character ranges are escaped as described above (since they cannot otherwise be represented in the text of an XML attribute): 0x00 - 0x08, 0x0B - 0x0C, 0x0E - 0x1F.
Note that other invalid XML characters exist outside of the ASCII range. This method does not handle such characters.
WARNING: This method is intended to be the counterpart to the
convertInvalidCharsToNcr(java.lang.String)
method used on output to safely
store certain characters. Since it is possible to actually have a
literal '&#xHH;' coding inside the original text passed to the
convertInvalidCharsToNcr
, there is no way to
symmetrically remove only those NCRs that were added by this class
(without storing additional meta-information listing the exact NCRs
that were added, which would allow the differentiation of these with
any that were in the original string).
text
- The string which may contain NCRs.public static boolean needsConversionToHex(byte[] bytes)
The following ASCII character ranges are detected: 0x00 - 0x08, 0x0B - 0x0C, 0x0E - 0x1F.
Note that other invalid XML characters exist outside of the ASCII range. This method does not handle such characters.
bytes
- The byte array which may contain invalid characters.true
if the array contains any invalid
character, false
otherwisepublic static java.lang.String convertBytesToHex(byte[] bytes)
All bytes are encoded using this technique, generally this is
only done if needsConversionToHex(byte[])
returns true
.
WARNING: When using this method where the input array is string data, the same character encoding must be used by the encoding side as is used by the decoding side. Otherwise, the results are undefined.
bytes
- The byte array to be encoded.public static byte[] convertHexToBytes(java.lang.String hex)
WARNING: When using this method where the output array is string data, the same character encoding must be used by the encoding side as is used by the decoding side. Otherwise, the results are undefined.
hex
- The string to be decoded.public static java.lang.String getAttribute(org.w3c.dom.Element elem, java.lang.String key)
elem
- The XML element containing the attribute to be extracted.key
- The attribute's name. If no attribute is found under this
name, the key is prefixed with a leading underscore
(_
). If an attribute is found under this form
of the key, it is assumed the value is encoded in hex
format, and the value is decoded before it is returned.null
if no attribute match could be found for
either form of key
.public static void setAttribute(org.w3c.dom.Element elem, java.lang.String key, java.lang.String value)
elem
- DOM element to be updated.key
- Attribute name.value
- Value to be written, as a string, into the attribute. If
null
, no attribute is added to the element.public static int getAttributeInt(org.w3c.dom.Element elem, java.lang.String name, int defVal)
elem
- The node to search for the attribute.name
- The attribute name for which to search.defVal
- The default value to return if no attribute of that name is
found OR if there is any error.public static long getAttributeLong(org.w3c.dom.Element elem, java.lang.String name, long defVal)
elem
- The node to search for the attribute.name
- The attribute name for which to search.defVal
- The default value to return if no attribute of that name is
found OR if there is any error.public static boolean getAttributeBoolean(org.w3c.dom.Element elem, java.lang.String name, boolean defVal)
elem
- The node to search for the attribute.name
- The attribute name for which to search.defVal
- The default value to return if no attribute of that name is
found OR if there is any error.static javax.xml.parsers.DocumentBuilderFactory getDocumentBuilderFactory(boolean validating, boolean isNamespaceAware)
DocumentBuilderFactory
is not thread-safe. Since this is
not a critical resource to cache, soft references are used to store
the factories, allowing the GC to collect them if memory is constrained.validating
- true
to get a factory for validating document
builders; false
to get a factory for
non-validating document builders.isNamespaceAware
- true if the parser produced will provide support for XML namespaces;
false otherwise.