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 and Description
static interface	XMLTools.SchemaReader A schema reader can provide InputStreams for certain XML schemas.
(package private) static class	XMLTools.XMLListener ErrorListener implementation that logs errors and warnings using SLF4J.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) static org.slf4j.Logger	LOGGER
private static ThreadLocal<HashMap<URI,Schema>>	schemas
private static TransformerFactory	transformFactory
private static String	XML_SCHEMA_PATH
private static String	XSI_NS

Constructor Summary

Constructors

Modifier	Constructor and Description
private	XMLTools()

Method Summary

Methods

Modifier and Type	Method and Description
static String	avoidUndeclaredNamespaces(String xml) Replaces NS:tag with NS_tag for undeclared namespaces
private static void	checkUTF8(InputStream is) Checks the given stream for a UTF-8 BOM header, skipping it if present.
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.
private static TransformerFactory	createTransformFactory()
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.
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 void	parseXML(RandomAccessInputStream stream, DefaultHandler handler) Parses the XML contained in the given input stream into 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 String	sanitizeXML(String s) Remove invalid characters from an XML string.
static String	transformXML(Source xmlSource, Templates xslt) Transforms the given XML data using the specified XSLT stylesheet.
static String	transformXML(String xml, Templates xslt) Transforms the given XML string 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

Field Detail

LOGGER

static final org.slf4j.Logger LOGGER

XSI_NS

private static final String XSI_NS

See Also:

Constant Field Values

XML_SCHEMA_PATH

private static final String XML_SCHEMA_PATH

See Also:

Constant Field Values

transformFactory

private static final TransformerFactory transformFactory

schemas

private static ThreadLocal<HashMap<URI,Schema>> schemas

Constructor Detail

XMLTools

private XMLTools()

Method Detail

createTransformFactory

private static TransformerFactory createTransformFactory()

createBuilder

public static DocumentBuilder createBuilder()

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

createDocument

public static Document createDocument()

Calls DocumentBuilder.newDocument() on a new builder.

parseDOM

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

Parses a DOM from the given XML file on disk.

Throws:

ParserConfigurationException

SAXException

IOException

parseDOM

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

Parses a DOM from the given XML string.

Throws:

ParserConfigurationException

SAXException

IOException

parseDOM

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

Parses a DOM from the given XML input stream.

Throws:

ParserConfigurationException

SAXException

IOException

getXML

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

Converts the given DOM back to a string.

Throws:

TransformerConfigurationException

TransformerException

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.

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.

Returns:

OME-XML as a string.

escapeXML

public static String escapeXML(String s)

Escape special characters.

sanitizeXML

public static String sanitizeXML(String s)

Remove invalid characters from an XML string.

indentXML

public static String indentXML(String xml)

Indents XML to be more readable.

indentXML

public static String indentXML(String xml,
               int spacing)

Indents XML by the given spacing to be more readable.

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.

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.

parseXML

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

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

Throws:

IOException

parseXML

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

Parses the given XML string using the specified XML handler.

Throws:

IOException

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.

Throws:

IOException

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.

Throws:

IOException

parseXML

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

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

Throws:

IOException

writeXML

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

Writes the specified DOM to the given output stream.

Throws:

TransformerException

writeXML

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

Writes the specified DOM to the given output stream.

Throws:

TransformerException

writeXML

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

Writes the specified DOM to the given stream.

Throws:

TransformerException

getStylesheet

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

Gets an XSLT template from the given resource location.

avoidUndeclaredNamespaces

public static String avoidUndeclaredNamespaces(String xml)

Replaces NS:tag with NS_tag for undeclared namespaces

transformXML

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

Transforms the given XML string using the specified XSLT stylesheet.

Throws:

IOException

transformXML

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

Transforms the given XML data using the specified XSLT stylesheet.

Throws:

IOException

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.

checkUTF8

private static void checkUTF8(InputStream is)
                       throws IOException

Checks the given stream for a UTF-8 BOM header, skipping it if present. If no UTF-8 BOM is present, the position of the stream is unchanged.

We must discard this character because Java does not handle it correctly.

Throws:

IOException