Package loci.common.xml
Class XMLTools
java.lang.Object
loci.common.xml.XMLTools
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 ClassesModifier and TypeClassDescriptionstatic interfaceA schema reader can provideInputStreams for certain XML schemas. -
Method Summary
Modifier and TypeMethodDescriptionstatic StringReplaces NS:tag with NS_tag for undeclared namespacesstatic DocumentBuilderstatic DocumentCallsDocumentBuilder.newDocument()on anew builder.static StringDumps the given OME-XML DOM tree to a string.static StringDumps the given OME-XML DOM tree to a string.static StringEscape special characters.static TemplatesgetStylesheet(String resourcePath, Class<?> sourceClass) Gets an XSLT template from the given resource location.static StringConverts the given DOM back to a string.static StringIndents XML to be more readable.static StringIndents XML to be more readable, avoiding any whitespace injection into CDATA if the preserveCData flag is set.static StringIndents XML by the given spacing to be more readable.static StringIndents XML by the given spacing to be more readable, avoiding any whitespace injection into CDATA if the preserveCData flag is set.static DocumentParses a DOM from the given XML file on disk.static DocumentparseDOM(InputStream is) Parses a DOM from the given XML input stream.static DocumentParses a DOM from the given XML string.static voidparseXML(byte[] xml, DefaultHandler handler) Parses the XML contained in the given byte array into using the specified XML handler.static voidparseXML(InputStream xml, DefaultHandler handler) Parses the XML contained in the given InputStream using the specified XML handler.Parses the given XML string into a list of key/value pairs.static voidparseXML(String xml, DefaultHandler handler) Parses the given XML string using the specified XML handler.static voidparseXML(RandomAccessInputStream stream, DefaultHandler handler) Parses the XML contained in the given input stream into using the specified XML handler.static StringRemove invalid characters from an XML string.static StringtransformXML(String xml, Templates xslt) Transforms the given XML string using the specified XSLT stylesheet.static StringtransformXML(Source xmlSource, Templates xslt) Transforms the given XML data using the specified XSLT stylesheet.static booleanvalidateXML(String xml) Attempts to validate the given XML string using Java's XML validation facility.static booleanvalidateXML(String xml, String label) Attempts to validate the given XML string using Java's XML validation facility.static booleanvalidateXML(String xml, String label, XMLTools.SchemaReader schemaReader) Attempts to validate the given XML string using Java's XML validation facility.static voidwriteXML(OutputStream os, Document doc) Writes the specified DOM to the given output stream.static voidwriteXML(OutputStream os, Document doc, boolean includeXMLDeclaration) Writes the specified DOM to the given output stream.static voidWrites the specified DOM to the given stream.
-
Method Details
-
createBuilder
- Returns:
- the default
DocumentBuilderinstance
-
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
Documentreflecting 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
Documentreflecting 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- theInputStreamcontaining XML- Returns:
- a
Documentrepresenting 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- theDocumentrepresenting 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
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- theDocumentrepresenting the XML to be writtenr- theElementto 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
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
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
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
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
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
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
Parses the given XML string into a list of key/value pairs.- Parameters:
xml- theInputStreamrepresenting 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
Parses the given XML string using the specified XML handler.- Parameters:
xml- the string representing the XMLhandler- theDefaultHandlerto 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- theRandomAccessInputStreamrepresenting the XMLhandler- theDefaultHandlerto use for parsing- Throws:
IOException- if there is an error during parsing
-
parseXML
Parses the XML contained in the given byte array into using the specified XML handler.- Parameters:
xml- the byte array representing the XMLhandler- theDefaultHandlerto use for parsing- Throws:
IOException- if there is an error during parsing
-
parseXML
Parses the XML contained in the given InputStream using the specified XML handler.- Parameters:
xml- theInputStreamrepresenting the XMLhandler- theDefaultHandlerto use for parsing- Throws:
IOException- if there is an error during parsing
-
writeXML
Writes the specified DOM to the given output stream.- Parameters:
os- theOutputStreamto which XML should be writtendoc- theDocumentrepresenting 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- theOutputStreamto which XML should be writtendoc- theDocumentrepresenting 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- theResultto which XML should be writtendoc- theDocumentrepresenting 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
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
Templatesobject representing the stylesheet
-
avoidUndeclaredNamespaces
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
Transforms the given XML string using the specified XSLT stylesheet.- Parameters:
xml- the XML string to be transformedxslt- theTemplatesobject 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:
-
transformXML
Transforms the given XML data using the specified XSLT stylesheet.- Parameters:
xmlSource- theSourceobject representing the XML to be transformedxslt- theTemplatesobject 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:
-
validateXML
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
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
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.
-