Package loci.common.xml

Class XMLTools

java.lang.Object

loci.common.xml.XMLTools

public final class XMLTools
extends Object

A utility class for working with XML.

Author:

Curtis Rueden ctrueden at wisc.edu, Chris Allan callan at blackcat.ca, Melissa Linkert melissa at glencoesoftware.com

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	XMLTools.SchemaReader	A schema reader can provide InputStreams for certain XML schemas.

Method Summary

Modifier and Type	Method	Description
static String	avoidUndeclaredNamespaces(String xml)	Replaces NS:tag with NS_tag for undeclared namespaces
static DocumentBuilder	createBuilder()	Creates a new DocumentBuilder via DocumentBuilderFactory or logs and throws a RuntimeException.
static Document	createDocument()	Calls DocumentBuilder.newDocument() on a new builder.
static SAXParser	createSAXParser()	Create a new SAX parser.
static String	dumpXML(String schemaLocation, Document doc, Element r)	Dumps the given OME-XML DOM tree to a string.
static String	dumpXML(String schemaLocation, Document doc, Element r, boolean includeXMLDeclaration)	Dumps the given OME-XML DOM tree to a string.
static String	escapeXML(String s)	Escape special characters.
static Templates	getStylesheet(String resourcePath, Class<?> sourceClass)	Gets an XSLT template from the given resource location.
static String	getXML(Document doc)	Converts the given DOM back to a string.
static String	indentXML(String xml)	Indents XML to be more readable.
static String	indentXML(String xml, boolean preserveCData)	Indents XML to be more readable, avoiding any whitespace injection into CDATA if the preserveCData flag is set.
static String	indentXML(String xml, int spacing)	Indents XML by the given spacing to be more readable.
static String	indentXML(String xml, int spacing, boolean preserveCData)	Indents XML by the given spacing to be more readable, avoiding any whitespace injection into CDATA if the preserveCData flag is set.
static Document	parseDOM(File file)	Parses a DOM from the given XML file on disk.
static Document	parseDOM(InputStream is)	Parses a DOM from the given XML input stream.
static Document	parseDOM(String xml)	Parses a DOM from the given XML string, using UTF-8 encoding.
static Document	parseDOM(String xml, String encoding)	Parses a DOM from the given XML string, using the given encoding.
static void	parseXML(byte[] xml, DefaultHandler handler)	Parses the XML contained in the given byte array into using the specified XML handler.
static void	parseXML(InputStream xml, DefaultHandler handler)	Parses the XML contained in the given InputStream using the specified XML handler.
static Hashtable<String,String>	parseXML(String xml)	Parses the given XML string into a list of key/value pairs.
static void	parseXML(String xml, DefaultHandler handler)	Parses the given XML string using the specified XML handler.
static void	parseXML(RandomAccessInputStream stream, DefaultHandler handler)	Parses the XML contained in the given input stream into using the specified XML handler.
static String	sanitizeXML(String s)	Remove invalid characters from an XML string.
static String	transformXML(String xml, Templates xslt)	Transforms the given XML string using the specified XSLT stylesheet.
static String	transformXML(Source xmlSource, Templates xslt)	Transforms the given XML data using the specified XSLT stylesheet.
static boolean	validateXML(String xml)	Attempts to validate the given XML string using Java's XML validation facility.
static boolean	validateXML(String xml, String label)	Attempts to validate the given XML string using Java's XML validation facility.
static boolean	validateXML(String xml, String label, XMLTools.SchemaReader schemaReader)	Attempts to validate the given XML string using Java's XML validation facility.
static void	writeXML(OutputStream os, Document doc)	Writes the specified DOM to the given output stream.
static void	writeXML(OutputStream os, Document doc, boolean includeXMLDeclaration)	Writes the specified DOM to the given output stream.
static void	writeXML(Result output, Document doc, boolean includeXMLDeclaration)	Writes the specified DOM to the given stream.

Methods inherited from class java.lang.Object

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

Method Detail

createBuilder

public static DocumentBuilder createBuilder()

Creates a new DocumentBuilder via DocumentBuilderFactory or logs and throws a RuntimeException.

Returns:

the default DocumentBuilder instance

createDocument

public static Document createDocument()

Calls DocumentBuilder.newDocument() on a new builder.

Returns:

an empty Document

parseDOM

public static Document parseDOM(File file)
                         throws ParserConfigurationException,
                                SAXException,
                                IOException

Parses a DOM from the given XML file on disk.

Parameters:

file - a file on disk that contains XML

Returns:

a Document reflecting the contents of the file

Throws:

ParserConfigurationException - if the XML parser cannot be created

SAXException - if there is an error parsing the XML

IOException - if there is an error reading from the file

parseDOM

public static Document parseDOM(String xml)
                         throws ParserConfigurationException,
                                SAXException,
                                IOException

Parses a DOM from the given XML string, using UTF-8 encoding.

Parameters:

xml - XML data

Returns:

a Document reflecting the XML string

Throws:

ParserConfigurationException - if the XML parser cannot be created

SAXException - if there is an error parsing the XML

IOException - if there is an error reading from the file

parseDOM

public static Document parseDOM(String xml,
                                String encoding)
                         throws ParserConfigurationException,
                                SAXException,
                                IOException

Parses a DOM from the given XML string, using the given encoding.

Parameters:

xml - XML data

encoding - charset name

Returns:

a Document reflecting the XML string

Throws:

ParserConfigurationException - if the XML parser cannot be created

SAXException - if there is an error parsing the XML

IOException - if there is an error reading from the file

parseDOM

public static Document parseDOM(InputStream is)
                         throws ParserConfigurationException,
                                SAXException,
                                IOException

Parses a DOM from the given XML input stream.

Parameters:

is - the InputStream containing XML

Returns:

a Document representing the XML

Throws:

ParserConfigurationException - if the XML parser cannot be created

SAXException - if there is an error parsing the XML

IOException - if there is an error reading from the stream

getXML

public static String getXML(Document doc)
                     throws TransformerConfigurationException,
                            TransformerException

Converts the given DOM back to a string.

Parameters:

doc - the Document representing the XML

Returns:

a string representation of the XML

Throws:

TransformerConfigurationException - if there is an error initializing the conversion

TransformerException - if there is an error during writing

dumpXML

public static String dumpXML(String schemaLocation,
                             Document doc,
                             Element r)

Dumps the given OME-XML DOM tree to a string.

Parameters:

schemaLocation - if null, no xmlns attribute will be added.

doc - the Document representing the XML to be written

r - the Element to use for adding the schema location

Returns:

OME-XML as a string.

dumpXML

public static String dumpXML(String schemaLocation,
                             Document doc,
                             Element r,
                             boolean includeXMLDeclaration)

Dumps the given OME-XML DOM tree to a string.

Parameters:

schemaLocation - if null, no xmlns attribute will be added.

doc - the Document representing the XML to be written

r - the Element to use for adding the schema location

includeXMLDeclaration - false if the XML declaration should be omitted, see OutputKeys.OMIT_XML_DECLARATION

Returns:

OME-XML as a string.

escapeXML

public static String escapeXML(String s)

Escape special characters. Replaces quotes, ampersands, and angle brackets with the escaped equivalent.

Parameters:

s - input string containing characters to escape

Returns:

copy of the input string with characters escaped as described above

sanitizeXML

public static String sanitizeXML(String s)

Remove invalid characters from an XML string.

Parameters:

s - the input string from which to remove invalid characters

Returns:

a copy of the input string with CR, LF, tab, and control characters replaced by a single space

indentXML

public static String indentXML(String xml)

Indents XML to be more readable. Uses 3 spaces to indent, and may indent CDATA.

Parameters:

xml - the XML string to format

Returns:

the formatted XML string

See Also:

indentXML(String, int, boolean)

indentXML

public static String indentXML(String xml,
                               int spacing)

Indents XML by the given spacing to be more readable. CDATA may be indented.

Parameters:

xml - the XML string to format

spacing - the number of spaces by which to indent

Returns:

the formatted XML string

See Also:

indentXML(String, int, boolean)

indentXML

public static String indentXML(String xml,
                               boolean preserveCData)

Indents XML to be more readable, avoiding any whitespace injection into CDATA if the preserveCData flag is set. Uses 3 spaces to indent.

Parameters:

xml - the XML string to format

preserveCData - true if CDATA nodes should be preserved with no indenting

Returns:

the formatted XML string

See Also:

indentXML(String, int, boolean)

indentXML

public static String indentXML(String xml,
                               int spacing,
                               boolean preserveCData)

Indents XML by the given spacing to be more readable, avoiding any whitespace injection into CDATA if the preserveCData flag is set.

Parameters:

xml - the XML string to format

spacing - the number of spaces by which to indent

preserveCData - true if CDATA nodes should be preserved with no indenting

Returns:

the formatted XML string

createSAXParser

public static SAXParser createSAXParser()
                                 throws ParserConfigurationException,
                                        SAXException

Create a new SAX parser.

Throws:

ParserConfigurationException

SAXException

parseXML

public static Hashtable<String,String> parseXML(String xml)
                                               throws IOException

Parses the given XML string into a list of key/value pairs.

Parameters:

xml - the InputStream representing the XML

Returns:

a hashtable of key/value pairs representing the XML

Throws:

IOException - if there is an error during parsing

See Also:

MetadataHandler

parseXML

public static void parseXML(String xml,
                            DefaultHandler handler)
                     throws IOException

Parses the given XML string using the specified XML handler.

Parameters:

xml - the string representing the XML

handler - the DefaultHandler to use for parsing

Throws:

IOException - if there is an error during parsing

parseXML

public static void parseXML(RandomAccessInputStream stream,
                            DefaultHandler handler)
                     throws IOException

Parses the XML contained in the given input stream into using the specified XML handler. Be very careful, as 'stream' will be closed by the SAX parser.

Parameters:

stream - the RandomAccessInputStream representing the XML

handler - the DefaultHandler to use for parsing

Throws:

IOException - if there is an error during parsing

parseXML

public static void parseXML(byte[] xml,
                            DefaultHandler handler)
                     throws IOException

Parses the XML contained in the given byte array into using the specified XML handler.

Parameters:

xml - the byte array representing the XML

handler - the DefaultHandler to use for parsing

Throws:

IOException - if there is an error during parsing

parseXML

public static void parseXML(InputStream xml,
                            DefaultHandler handler)
                     throws IOException

Parses the XML contained in the given InputStream using the specified XML handler.

Parameters:

xml - the InputStream representing the XML

handler - the DefaultHandler to use for parsing

Throws:

IOException - if there is an error during parsing

writeXML

public static void writeXML(OutputStream os,
                            Document doc)
                     throws TransformerException

Writes the specified DOM to the given output stream.

Parameters:

os - the OutputStream to which XML should be written

doc - the Document representing the XML to write

Throws:

TransformerException - if there is an error during writing

writeXML

public static void writeXML(OutputStream os,
                            Document doc,
                            boolean includeXMLDeclaration)
                     throws TransformerException

Writes the specified DOM to the given output stream.

Parameters:

os - the OutputStream to which XML should be written

doc - the Document representing the XML to write

includeXMLDeclaration - false if the XML declaration should be omitted, see OutputKeys.OMIT_XML_DECLARATION

Throws:

TransformerException - if there is an error during writing

writeXML

public static void writeXML(Result output,
                            Document doc,
                            boolean includeXMLDeclaration)
                     throws TransformerException

Writes the specified DOM to the given stream.

Parameters:

output - the Result to which XML should be written

doc - the Document representing the XML to write

includeXMLDeclaration - false if the XML declaration should be omitted, see OutputKeys.OMIT_XML_DECLARATION

Throws:

TransformerException - if there is an error during writing

getStylesheet

public static Templates getStylesheet(String resourcePath,
                                      Class<?> sourceClass)

Gets an XSLT template from the given resource location.

Parameters:

resourcePath - the name of the stylesheet resource

sourceClass - the class to use when searching for the resource

Returns:

a Templates object representing the stylesheet

avoidUndeclaredNamespaces

public static String avoidUndeclaredNamespaces(String xml)

Replaces NS:tag with NS_tag for undeclared namespaces

Parameters:

xml - the XML string whose namespaces need to be replaced

Returns:

a copy of the input string with NS:tag replaced by NS_tag for any undeclared namespaces

transformXML

public static String transformXML(String xml,
                                  Templates xslt)
                           throws IOException

Transforms the given XML string using the specified XSLT stylesheet.

Parameters:

xml - the XML string to be transformed

xslt - the Templates object representing an XSLT stylesheet

Returns:

the XML string that results from applying the stylesheet

Throws:

IOException - if there is an error parsing the XML

See Also:

getStylesheet(String, Class)

transformXML

public static String transformXML(Source xmlSource,
                                  Templates xslt)
                           throws IOException

Transforms the given XML data using the specified XSLT stylesheet.

Parameters:

xmlSource - the Source object representing the XML to be transformed

xslt - the Templates object representing an XSLT stylesheet

Returns:

the XML string that results from applying the stylesheet

Throws:

IOException - if there is an error parsing the XML

See Also:

getStylesheet(String, Class)

validateXML

public static boolean validateXML(String xml)

Attempts to validate the given XML string using Java's XML validation facility.

Parameters:

xml - The XML string to validate.

Returns:

whether or not validation was successful.

validateXML

public static boolean validateXML(String xml,
                                  String label)

Attempts to validate the given XML string using Java's XML validation facility.

Parameters:

xml - The XML string to validate.

label - String describing the type of XML being validated.

Returns:

whether or not validation was successful.

validateXML

public static boolean validateXML(String xml,
                                  String label,
                                  XMLTools.SchemaReader schemaReader)

Attempts to validate the given XML string using Java's XML validation facility.

Parameters:

xml - The XML string to validate.

label - String describing the type of XML being validated.

schemaReader - turns schema system IDs into input streams, may be null

Returns:

whether or not validation was successful.