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 provideInputStream
s for certain XML schemas.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static String
avoidUndeclaredNamespaces(String xml)
Replaces NS:tag with NS_tag for undeclared namespacesstatic DocumentBuilder
createBuilder()
static Document
createDocument()
CallsDocumentBuilder.newDocument()
on anew builder
.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 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.
-
-
-
Method Detail
-
createBuilder
public static DocumentBuilder createBuilder()
- Returns:
- the default
DocumentBuilder
instance
-
createDocument
public static Document createDocument()
CallsDocumentBuilder.newDocument()
on anew 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 createdSAXException
- if there is an error parsing the XMLIOException
- 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.- Parameters:
xml
- XML data- Returns:
- a
Document
reflecting the XML string - Throws:
ParserConfigurationException
- if the XML parser cannot be createdSAXException
- if there is an error parsing the XMLIOException
- 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
- theInputStream
containing XML- Returns:
- a
Document
representing the XML - Throws:
ParserConfigurationException
- if the XML parser cannot be createdSAXException
- if there is an error parsing the XMLIOException
- 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
- theDocument
representing the XML- Returns:
- a string representation of the XML
- Throws:
TransformerConfigurationException
- if there is an error initializing the conversionTransformerException
- 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.
-
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
- theDocument
representing the XML to be writtenr
- theElement
to use for adding the schema locationincludeXMLDeclaration
- false if the XML declaration should be omitted, seeOutputKeys.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 formatspacing
- 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 formatpreserveCData
- 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 formatspacing
- the number of spaces by which to indentpreserveCData
- true if CDATA nodes should be preserved with no indenting- Returns:
- the formatted XML string
-
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
- theInputStream
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 XMLhandler
- theDefaultHandler
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
- theRandomAccessInputStream
representing the XMLhandler
- theDefaultHandler
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 XMLhandler
- theDefaultHandler
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
- theInputStream
representing the XMLhandler
- theDefaultHandler
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
- theOutputStream
to which XML should be writtendoc
- theDocument
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
- theOutputStream
to which XML should be writtendoc
- theDocument
representing the XML to writeincludeXMLDeclaration
- false if the XML declaration should be omitted, seeOutputKeys.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
- theResult
to which XML should be writtendoc
- theDocument
representing the XML to writeincludeXMLDeclaration
- false if the XML declaration should be omitted, seeOutputKeys.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 resourcesourceClass
- 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 transformedxslt
- theTemplates
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
- theSource
object representing the XML to be transformedxslt
- theTemplates
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 benull
- Returns:
- whether or not validation was successful.
-
-