Package loci.common.xml

Class XMLTools

java.lang.Object
loci.common.xml.XMLTools
public final class XMLTools
extends java.lang.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 java.lang.String avoidUndeclaredNamespaces​(java.lang.String xml)
    Replaces NS:tag with NS_tag for undeclared namespaces
    static javax.xml.parsers.DocumentBuilder createBuilder()
    Creates a new DocumentBuilder via DocumentBuilderFactory or logs and throws a RuntimeException.
    static org.w3c.dom.Document createDocument()
    Calls DocumentBuilder.newDocument() on a new builder.
    static java.lang.String dumpXML​(java.lang.String schemaLocation, org.w3c.dom.Document doc, org.w3c.dom.Element r)
    Dumps the given OME-XML DOM tree to a string.
    static java.lang.String dumpXML​(java.lang.String schemaLocation, org.w3c.dom.Document doc, org.w3c.dom.Element r, boolean includeXMLDeclaration)
    Dumps the given OME-XML DOM tree to a string.
    static java.lang.String escapeXML​(java.lang.String s)
    Escape special characters.
    static javax.xml.transform.Templates getStylesheet​(java.lang.String resourcePath, java.lang.Class<?> sourceClass)
    Gets an XSLT template from the given resource location.
    static java.lang.String getXML​(org.w3c.dom.Document doc)
    Converts the given DOM back to a string.
    static java.lang.String indentXML​(java.lang.String xml)
    Indents XML to be more readable.
    static java.lang.String indentXML​(java.lang.String xml, boolean preserveCData)
    Indents XML to be more readable, avoiding any whitespace injection into CDATA if the preserveCData flag is set.
    static java.lang.String indentXML​(java.lang.String xml, int spacing)
    Indents XML by the given spacing to be more readable.
    static java.lang.String indentXML​(java.lang.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 org.w3c.dom.Document parseDOM​(java.io.File file)
    Parses a DOM from the given XML file on disk.
    static org.w3c.dom.Document parseDOM​(java.io.InputStream is)
    Parses a DOM from the given XML input stream.
    static org.w3c.dom.Document parseDOM​(java.lang.String xml)
    Parses a DOM from the given XML string.
    static void parseXML​(byte[] xml, org.xml.sax.helpers.DefaultHandler handler)
    Parses the XML contained in the given byte array into using the specified XML handler.
    static void parseXML​(java.io.InputStream xml, org.xml.sax.helpers.DefaultHandler handler)
    Parses the XML contained in the given InputStream using the specified XML handler.
    static java.util.Hashtable<java.lang.String,​java.lang.String> parseXML​(java.lang.String xml)
    Parses the given XML string into a list of key/value pairs.
    static void parseXML​(java.lang.String xml, org.xml.sax.helpers.DefaultHandler handler)
    Parses the given XML string using the specified XML handler.
    static void parseXML​(RandomAccessInputStream stream, org.xml.sax.helpers.DefaultHandler handler)
    Parses the XML contained in the given input stream into using the specified XML handler.
    static java.lang.String sanitizeXML​(java.lang.String s)
    Remove invalid characters from an XML string.
    static java.lang.String transformXML​(java.lang.String xml, javax.xml.transform.Templates xslt)
    Transforms the given XML string using the specified XSLT stylesheet.
    static java.lang.String transformXML​(javax.xml.transform.Source xmlSource, javax.xml.transform.Templates xslt)
    Transforms the given XML data using the specified XSLT stylesheet.
    static boolean validateXML​(java.lang.String xml)
    Attempts to validate the given XML string using Java's XML validation facility.
    static boolean validateXML​(java.lang.String xml, java.lang.String label)
    Attempts to validate the given XML string using Java's XML validation facility.
    static boolean validateXML​(java.lang.String xml, java.lang.String label, XMLTools.SchemaReader schemaReader)
    Attempts to validate the given XML string using Java's XML validation facility.
    static void writeXML​(java.io.OutputStream os, org.w3c.dom.Document doc)
    Writes the specified DOM to the given output stream.
    static void writeXML​(java.io.OutputStream os, org.w3c.dom.Document doc, boolean includeXMLDeclaration)
    Writes the specified DOM to the given output stream.
    static void writeXML​(javax.xml.transform.Result output, org.w3c.dom.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 Details

    • createBuilder

      public static javax.xml.parsers.DocumentBuilder createBuilder()
      Creates a new DocumentBuilder via DocumentBuilderFactory or logs and throws a RuntimeException.
      Returns:
      the default DocumentBuilder instance

    • createDocument

      public static org.w3c.dom.Document createDocument()
      Calls DocumentBuilder.newDocument() on a new builder.
      Returns:
      an empty Document

    • parseDOM

      public static org.w3c.dom.Document parseDOM​(java.io.File file) throws javax.xml.parsers.ParserConfigurationException, org.xml.sax.SAXException, java.io.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:
      javax.xml.parsers.ParserConfigurationException - if the XML parser cannot be created
      org.xml.sax.SAXException - if there is an error parsing the XML
      java.io.IOException - if there is an error reading from the file

    • parseDOM

      public static org.w3c.dom.Document parseDOM​(java.lang.String xml) throws javax.xml.parsers.ParserConfigurationException, org.xml.sax.SAXException, java.io.IOException
      Parses a DOM from the given XML string.
      Parameters:
      xml - XML data
      Returns:
      a Document reflecting the XML string
      Throws:
      javax.xml.parsers.ParserConfigurationException - if the XML parser cannot be created
      org.xml.sax.SAXException - if there is an error parsing the XML
      java.io.IOException - if there is an error reading from the file

    • parseDOM

      public static org.w3c.dom.Document parseDOM​(java.io.InputStream is) throws javax.xml.parsers.ParserConfigurationException, org.xml.sax.SAXException, java.io.IOException
      Parses a DOM from the given XML input stream.
      Parameters:
      is - the InputStream containing XML
      Returns:
      a Document representing the XML
      Throws:
      javax.xml.parsers.ParserConfigurationException - if the XML parser cannot be created
      org.xml.sax.SAXException - if there is an error parsing the XML
      java.io.IOException - if there is an error reading from the stream

    • getXML

      public static java.lang.String getXML​(org.w3c.dom.Document doc) throws javax.xml.transform.TransformerConfigurationException, javax.xml.transform.TransformerException
      Converts the given DOM back to a string.
      Parameters:
      doc - the Document representing the XML
      Returns:
      a string representation of the XML
      Throws:
      javax.xml.transform.TransformerConfigurationException - if there is an error initializing the conversion
      javax.xml.transform.TransformerException - if there is an error during writing

    • dumpXML

      public static java.lang.String dumpXML​(java.lang.String schemaLocation, org.w3c.dom.Document doc, org.w3c.dom.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 java.lang.String dumpXML​(java.lang.String schemaLocation, org.w3c.dom.Document doc, org.w3c.dom.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 java.lang.String escapeXML​(java.lang.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 java.lang.String sanitizeXML​(java.lang.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 java.lang.String indentXML​(java.lang.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 java.lang.String indentXML​(java.lang.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 java.lang.String indentXML​(java.lang.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 java.lang.String indentXML​(java.lang.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

    • parseXML

      public static java.util.Hashtable<java.lang.String,​java.lang.String> parseXML​(java.lang.String xml) throws java.io.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:
      java.io.IOException - if there is an error during parsing
      See Also:
      MetadataHandler

    • parseXML

      public static void parseXML​(java.lang.String xml, org.xml.sax.helpers.DefaultHandler handler) throws java.io.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:
      java.io.IOException - if there is an error during parsing

    • parseXML

      public static void parseXML​(RandomAccessInputStream stream, org.xml.sax.helpers.DefaultHandler handler) throws java.io.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:
      java.io.IOException - if there is an error during parsing

    • parseXML

      public static void parseXML​(byte[] xml, org.xml.sax.helpers.DefaultHandler handler) throws java.io.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:
      java.io.IOException - if there is an error during parsing

    • parseXML

      public static void parseXML​(java.io.InputStream xml, org.xml.sax.helpers.DefaultHandler handler) throws java.io.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:
      java.io.IOException - if there is an error during parsing

    • writeXML

      public static void writeXML​(java.io.OutputStream os, org.w3c.dom.Document doc) throws javax.xml.transform.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:
      javax.xml.transform.TransformerException - if there is an error during writing

    • writeXML

      public static void writeXML​(java.io.OutputStream os, org.w3c.dom.Document doc, boolean includeXMLDeclaration) throws javax.xml.transform.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:
      javax.xml.transform.TransformerException - if there is an error during writing

    • writeXML

      public static void writeXML​(javax.xml.transform.Result output, org.w3c.dom.Document doc, boolean includeXMLDeclaration) throws javax.xml.transform.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:
      javax.xml.transform.TransformerException - if there is an error during writing

    • getStylesheet

      public static javax.xml.transform.Templates getStylesheet​(java.lang.String resourcePath, java.lang.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 java.lang.String avoidUndeclaredNamespaces​(java.lang.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 java.lang.String transformXML​(java.lang.String xml, javax.xml.transform.Templates xslt) throws java.io.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:
      java.io.IOException - if there is an error parsing the XML
      See Also:
      getStylesheet(String, Class)

    • transformXML

      public static java.lang.String transformXML​(javax.xml.transform.Source xmlSource, javax.xml.transform.Templates xslt) throws java.io.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:
      java.io.IOException - if there is an error parsing the XML
      See Also:
      getStylesheet(String, Class)

    • validateXML

      public static boolean validateXML​(java.lang.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​(java.lang.String xml, java.lang.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​(java.lang.String xml, java.lang.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.