Package: groovy.xml

## [Java] Class XmlUtil

- groovy.xml.XmlUtil

-     public class XmlUtil
      extends Object

  Used for pretty printing XML content and other XML related utilities. The serialization helpers accept DOM nodes, Groovy XML trees, GPathResult, Writable, and raw XML text.

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public static String` | `escapeControlCharacters(String orig)` Escape control characters (below 0x20) with their XML entities, e.g.
    `` | `public static String` | `escapeXml(String orig)` Escape the following characters {@code " ' & < >} with their XML entities, e.g.
    `` | `public static Stream<XMLEvent>` | `events(Reader reader)` Streams XML events from the supplied Reader using a hardened StAX XMLInputFactory.
    `` | `public static Stream<XMLEvent>` | `events(Reader reader, boolean allowDocTypeDeclaration)` Streams XML events from the supplied Reader using a hardened StAX XMLInputFactory.
    `` | `public static SAXParser` | `newSAXParser(String schemaLanguage, Source schemas)` Factory method to create a SAXParser configured to validate according to a particular schema language and optionally providing the schema sources to validate with.
    `` | `public static SAXParser` | `newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, Source schemas)` Factory method to create a SAXParser configured to validate according to a particular schema language and optionally providing the schema sources to validate with.
    `` | `public static SAXParser` | `newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, boolean allowDoctypeDecl, Source schemas)` Factory method to create a SAXParser configured to validate according to a particular schema language and optionally providing the schema sources to validate with.
    `` | `public static SAXParser` | `newSAXParser(String schemaLanguage, File schema)` Factory method to create a SAXParser configured to validate according to a particular schema language and a File containing the schema to validate against.
    `` | `public static SAXParser` | `newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, File schema)` Factory method to create a SAXParser configured to validate according to a particular schema language and a File containing the schema to validate against.
    `` | `public static SAXParser` | `newSAXParser(String schemaLanguage, URL schema)` Factory method to create a SAXParser configured to validate according to a particular schema language and a URL pointing to the schema to validate against.
    `` | `public static SAXParser` | `newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, URL schema)` Factory method to create a SAXParser configured to validate according to a particular schema language and a URL pointing to the schema to validate against.
    `` | `public static String` | `serialize(Element element)` Return a pretty String version of the Element.
    `` | `public static String` | `serialize(Element element, boolean allowDocTypeDeclaration)` Return a pretty String version of the Element.
    `` | `public static void` | `serialize(Element element, OutputStream os)` Write a pretty version of the Element to the OutputStream.
    `` | `public static void` | `serialize(Element element, OutputStream os, boolean allowDocTypeDeclaration)` Write a pretty version of the Element to the OutputStream.
    `` | `public static void` | `serialize(Element element, Writer w)` Write a pretty version of the Element to the Writer.
    `` | `public static void` | `serialize(Element element, Writer w, boolean allowDocTypeDeclaration)` Write a pretty version of the Element to the Writer.
    `` | `public static String` | `serialize(Node node)` Return a pretty String version of the Node.
    `` | `public static void` | `serialize(Node node, OutputStream os)` Write a pretty version of the Node to the OutputStream.
    `` | `public static void` | `serialize(Node node, Writer w)` Write a pretty version of the Node to the Writer.
    `` | `public static String` | `serialize(GPathResult node)` Return a pretty version of the GPathResult.
    `` | `public static void` | `serialize(GPathResult node, OutputStream os)` Write a pretty version of the GPathResult to the OutputStream.
    `` | `public static void` | `serialize(GPathResult node, Writer w)` Write a pretty version of the GPathResult to the Writer.
    `` | `public static String` | `serialize(Writable writable)` Return a pretty String version of the XML content produced by the Writable.
    `` | `public static void` | `serialize(Writable writable, OutputStream os)` Write a pretty version of the XML content produced by the Writable to the OutputStream.
    `` | `public static void` | `serialize(Writable writable, Writer w)` Write a pretty version of the XML content produced by the Writable to the Writer.
    `` | `public static String` | `serialize(String xmlString)` Return a pretty version of the XML content contained in the given String.
    `` | `public static String` | `serialize(String xmlString, boolean allowDocTypeDeclaration)` Return a pretty version of the XML content contained in the given String.
    `` | `public static void` | `serialize(String xmlString, OutputStream os)` Write a pretty version of the given XML string to the OutputStream.
    `` | `public static void` | `serialize(String xmlString, OutputStream os, boolean allowDocTypeDeclaration)` Write a pretty version of the given XML string to the OutputStream.
    `` | `public static void` | `serialize(String xmlString, Writer w)` Write a pretty version of the given XML string to the Writer.
    `` | `public static void` | `serialize(String xmlString, Writer w, boolean allowDocTypeDeclaration)` Write a pretty version of the given XML string to the Writer.
    `` | `public static String` | `serialize(Element element, SerializeOptions options)` Return a pretty String version of the Element using the specified options.
    `` | `public static void` | `serialize(Element element, OutputStream os, SerializeOptions options)` Write a pretty version of the Element to the OutputStream using the specified options.
    `` | `public static String` | `serialize(Node node, SerializeOptions options)` Return a pretty String version of the Node using the specified options.
    `` | `public static void` | `serialize(Node node, OutputStream os, SerializeOptions options)` Write a pretty version of the Node to the OutputStream using the specified options.
    `` | `public static String` | `serialize(GPathResult node, SerializeOptions options)` Return a pretty String version of the GPathResult using the specified options.
    `` | `public static void` | `serialize(GPathResult node, OutputStream os, SerializeOptions options)` Write a pretty version of the GPathResult to the OutputStream using the specified options.
    `` | `public static String` | `serialize(Writable writable, SerializeOptions options)` Return a pretty String version of the XML content produced by the Writable using the specified options.
    `` | `public static void` | `serialize(Writable writable, OutputStream os, SerializeOptions options)` Write a pretty version of the XML content produced by the Writable to the OutputStream using the specified options.
    `` | `public static String` | `serialize(String xmlString, SerializeOptions options)` Return a pretty version of the XML content contained in the given String using the specified options.
    `` | `public static void` | `serialize(String xmlString, OutputStream os, SerializeOptions options)` Write a pretty version of the given XML string to the OutputStream using the specified options.
    `` | `public static void` | `setFeatureQuietly(TransformerFactory factory, String feature, boolean value)` Attempts to set a feature on the transformer factory and ignores unsupported features.
    `` | `public static void` | `setFeatureQuietly(DocumentBuilderFactory factory, String feature, boolean value)` Attempts to set a feature on the document builder factory and ignores unsupported features.
    `` | `public static void` | `setFeatureQuietly(SAXParserFactory factory, String feature, boolean value)` Attempts to set a feature on the SAX parser factory and ignores unsupported features.
    `` | `public static Stream<Node>` | `streamElements(Reader reader, String localName)` Streams matching subtrees from a (potentially very large) XML document as DOM Nodes.
    `` | `public static Stream<Node>` | `streamElements(Reader reader, String namespaceURI, String localName)` Streams matching subtrees from a (potentially very large) XML document as DOM Nodes.
    `` | `public static Stream<Node>` | `streamElements(Reader reader, String namespaceURI, String localName, boolean allowDocTypeDeclaration)` Streams matching subtrees from a (potentially very large) XML document as DOM Nodes.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### public static String escapeControlCharacters(String orig)

      Escape control characters (below 0x20) with their XML entities, e.g. carriage return (`Ctrl-M or \r`) becomes `` Notes:

      - Does not escape non-ascii characters above 0x7e
      - Does not treat surrogate pairs specially
      - Does not perform Unicode validation on its input
      Parameters:
        `orig` - the original String
      Returns:
        A new string in which all characters that require escaping have been replaced with the corresponding XML entities.
      See Also:
        escapeXml(String)

    - #### public static String escapeXml(String orig)

      Escape the following characters {@code " ' & < >} with their XML entities, e.g. `"bread" & "butter"` becomes `"bread" & "butter"`. Notes:

      - Supports only the five basic XML entities (gt, lt, quot, amp, apos)
      - Does not escape control characters
      - Does not support DTDs or external entities
      - Does not treat surrogate pairs specially
      - Does not perform Unicode validation on its input
      Parameters:
        `orig` - the original String
      Returns:
        A new string in which all characters that require escaping have been replaced with the corresponding XML entities.
      See Also:
        escapeControlCharacters(String)

    - #### public static Stream<XMLEvent> events(Reader reader)

      Streams XML events from the supplied Reader using a hardened StAX XMLInputFactory. The returned stream lazily pulls events; closing the stream closes the underlying reader.

      Equivalent to events(Reader, boolean) events(reader, false).

      Parameters:
        `reader` - the XML source
      Returns:
        a stream of XMLEvents
      Since:
        6.0.0

    - #### public static Stream<XMLEvent> events(Reader reader, boolean allowDocTypeDeclaration)

      Streams XML events from the supplied Reader using a hardened StAX XMLInputFactory. The returned stream lazily pulls events; closing the stream closes the underlying reader.

      Parameters:
        `reader` - the XML source
        `allowDocTypeDeclaration` - whether DOCTYPE declarations are permitted
      Returns:
        a stream of XMLEvents
      Since:
        6.0.0

    - #### public static SAXParser newSAXParser(String schemaLanguage, Source schemas)

      Factory method to create a SAXParser configured to validate according to a particular schema language and optionally providing the schema sources to validate with. The created SAXParser will be namespace-aware and not validate against DTDs.

      throws:
        SAXException
      throws:
        ParserConfigurationException
      Parameters:
        `schemaLanguage` - the schema language used, e.g. XML Schema or RelaxNG (as per the String representation in javax.xml.XMLConstants)
        `schemas` - the schemas to validate against
      Returns:
        the created SAXParser
      See Also:
        newSAXParser(String, boolean, boolean, Source...)
      Since:
        1.8.7

    - #### public static SAXParser newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, Source schemas)

      Factory method to create a SAXParser configured to validate according to a particular schema language and optionally providing the schema sources to validate with.

      throws:
        SAXException
      throws:
        ParserConfigurationException
      Parameters:
        `schemaLanguage` - the schema language used, e.g. XML Schema or RelaxNG (as per the String representation in javax.xml.XMLConstants)
        `namespaceAware` - will the parser be namespace aware
        `validating` - will the parser also validate against DTDs
        `schemas` - the schemas to validate against
      Returns:
        the created SAXParser
      Since:
        1.8.7

    - #### public static SAXParser newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, boolean allowDoctypeDecl, Source schemas)

      Factory method to create a SAXParser configured to validate according to a particular schema language and optionally providing the schema sources to validate with.

      throws:
        SAXException
      throws:
        ParserConfigurationException
      Parameters:
        `schemaLanguage` - the schema language used, e.g. XML Schema or RelaxNG (as per the String representation in javax.xml.XMLConstants)
        `namespaceAware` - will the parser be namespace aware
        `validating` - will the parser also validate against DTDs
        `allowDoctypeDecl` - whether to allow doctype declarations (potentially insecure)
        `schemas` - the schemas to validate against
      Returns:
        the created SAXParser
      Since:
        3.0.11

    - #### public static SAXParser newSAXParser(String schemaLanguage, File schema)

      Factory method to create a SAXParser configured to validate according to a particular schema language and a File containing the schema to validate against. The created SAXParser will be namespace-aware and not validate against DTDs.

      throws:
        SAXException
      throws:
        ParserConfigurationException
      Parameters:
        `schemaLanguage` - the schema language used, e.g. XML Schema or RelaxNG (as per the String representation in javax.xml.XMLConstants)
        `schema` - a file containing the schema to validate against
      Returns:
        the created SAXParser
      See Also:
        newSAXParser(String, boolean, boolean, File)
      Since:
        1.8.7

    - #### public static SAXParser newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, File schema)

      Factory method to create a SAXParser configured to validate according to a particular schema language and a File containing the schema to validate against.

      throws:
        SAXException
      throws:
        ParserConfigurationException
      Parameters:
        `schemaLanguage` - the schema language used, e.g. XML Schema or RelaxNG (as per the String representation in javax.xml.XMLConstants)
        `namespaceAware` - will the parser be namespace aware
        `validating` - will the parser also validate against DTDs
        `schema` - a file containing the schema to validate against
      Returns:
        the created SAXParser
      Since:
        1.8.7

    - #### public static SAXParser newSAXParser(String schemaLanguage, URL schema)

      Factory method to create a SAXParser configured to validate according to a particular schema language and a URL pointing to the schema to validate against. The created SAXParser will be namespace-aware and not validate against DTDs.

      throws:
        SAXException
      throws:
        ParserConfigurationException
      Parameters:
        `schemaLanguage` - the schema language used, e.g. XML Schema or RelaxNG (as per the String representation in javax.xml.XMLConstants)
        `schema` - a URL pointing to the schema to validate against
      Returns:
        the created SAXParser
      See Also:
        newSAXParser(String, boolean, boolean, URL)
      Since:
        1.8.7

    - #### public static SAXParser newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, URL schema)

      Factory method to create a SAXParser configured to validate according to a particular schema language and a URL pointing to the schema to validate against.

      throws:
        SAXException
      throws:
        ParserConfigurationException
      Parameters:
        `schemaLanguage` - the schema language used, e.g. XML Schema or RelaxNG (as per the String representation in javax.xml.XMLConstants)
        `namespaceAware` - will the parser be namespace aware
        `validating` - will the parser also validate against DTDs
        `schema` - a URL pointing to the schema to validate against
      Returns:
        the created SAXParser
      Since:
        1.8.7

    - #### public static String serialize(Element element)

      Return a pretty String version of the Element.

      Parameters:
        `element` - the Element to serialize
      Returns:
        the pretty String representation of the Element

    - #### public static String serialize(Element element, boolean allowDocTypeDeclaration)

      Return a pretty String version of the Element.

      Parameters:
        `element` - the Element to serialize
        `allowDocTypeDeclaration` - whether to allow doctype processing
      Returns:
        the pretty String representation of the Element

    - #### public static void serialize(Element element, OutputStream os)

      Write a pretty version of the Element to the OutputStream.

      Parameters:
        `element` - the Element to serialize
        `os` - the OutputStream to write to

    - #### public static void serialize(Element element, OutputStream os, boolean allowDocTypeDeclaration)

      Write a pretty version of the Element to the OutputStream.

      Parameters:
        `element` - the Element to serialize
        `os` - the OutputStream to write to
        `allowDocTypeDeclaration` - whether to allow doctype processing

    - #### public static void serialize(Element element, Writer w)

      Write a pretty version of the Element to the Writer.

      Parameters:
        `element` - the Element to serialize
        `w` - the Writer to write to

    - #### public static void serialize(Element element, Writer w, boolean allowDocTypeDeclaration)

      Write a pretty version of the Element to the Writer.

      Parameters:
        `element` - the Element to serialize
        `w` - the Writer to write to
        `allowDocTypeDeclaration` - whether to allow doctype processing

    - #### public static String serialize(Node node)

      Return a pretty String version of the Node.

      Parameters:
        `node` - the Node to serialize
      Returns:
        the pretty String representation of the Node

    - #### public static void serialize(Node node, OutputStream os)

      Write a pretty version of the Node to the OutputStream.

      Parameters:
        `node` - the Node to serialize
        `os` - the OutputStream to write to

    - #### public static void serialize(Node node, Writer w)

      Write a pretty version of the Node to the Writer.

      Parameters:
        `node` - the Node to serialize
        `w` - the Writer to write to

    - #### public static String serialize(GPathResult node)

      Return a pretty version of the GPathResult.

      Parameters:
        `node` - a GPathResult to serialize to a String
      Returns:
        the pretty String representation of the GPathResult

    - #### public static void serialize(GPathResult node, OutputStream os)

      Write a pretty version of the GPathResult to the OutputStream.

      Parameters:
        `node` - a GPathResult to serialize
        `os` - the OutputStream to write to

    - #### public static void serialize(GPathResult node, Writer w)

      Write a pretty version of the GPathResult to the Writer.

      Parameters:
        `node` - a GPathResult to serialize
        `w` - the Writer to write to

    - #### public static String serialize(Writable writable)

      Return a pretty String version of the XML content produced by the Writable.

      Parameters:
        `writable` - the Writable to serialize
      Returns:
        the pretty String representation of the content from the Writable

    - #### public static void serialize(Writable writable, OutputStream os)

      Write a pretty version of the XML content produced by the Writable to the OutputStream.

      Parameters:
        `writable` - the Writable to serialize
        `os` - the OutputStream to write to

    - #### public static void serialize(Writable writable, Writer w)

      Write a pretty version of the XML content produced by the Writable to the Writer.

      Parameters:
        `writable` - the Writable to serialize
        `w` - the Writer to write to

    - #### public static String serialize(String xmlString)

      Return a pretty version of the XML content contained in the given String.

      Parameters:
        `xmlString` - the String to serialize
      Returns:
        the pretty String representation of the original content

    - #### public static String serialize(String xmlString, boolean allowDocTypeDeclaration)

      Return a pretty version of the XML content contained in the given String.

      Parameters:
        `xmlString` - the String to serialize
        `allowDocTypeDeclaration` - whether to allow doctype processing
      Returns:
        the pretty String representation of the original content

    - #### public static void serialize(String xmlString, OutputStream os)

      Write a pretty version of the given XML string to the OutputStream.

      Parameters:
        `xmlString` - the String to serialize
        `os` - the OutputStream to write to

    - #### public static void serialize(String xmlString, OutputStream os, boolean allowDocTypeDeclaration)

      Write a pretty version of the given XML string to the OutputStream.

      Parameters:
        `xmlString` - the String to serialize
        `allowDocTypeDeclaration` - whether to allow doctype processing
        `os` - the OutputStream to write to

    - #### public static void serialize(String xmlString, Writer w)

      Write a pretty version of the given XML string to the Writer.

      Parameters:
        `xmlString` - the String to serialize
        `w` - the Writer to write to

    - #### public static void serialize(String xmlString, Writer w, boolean allowDocTypeDeclaration)

      Write a pretty version of the given XML string to the Writer.

      Parameters:
        `xmlString` - the String to serialize
        `allowDocTypeDeclaration` - whether to allow doctype processing
        `w` - the Writer to write to

    - #### public static String serialize(Element element, SerializeOptions options)

      Return a pretty String version of the Element using the specified options.

      Parameters:
        `element` - the Element to serialize
        `options` - the serialization options
      Returns:
        the pretty String representation of the Element
      Since:
        6.0.0

    - #### public static void serialize(Element element, OutputStream os, SerializeOptions options)

      Write a pretty version of the Element to the OutputStream using the specified options.

      Parameters:
        `element` - the Element to serialize
        `os` - the OutputStream to write to
        `options` - the serialization options
      Since:
        6.0.0

    - #### public static String serialize(Node node, SerializeOptions options)

      Return a pretty String version of the Node using the specified options.

      Parameters:
        `node` - the Node to serialize
        `options` - the serialization options
      Returns:
        the pretty String representation of the Node
      Since:
        6.0.0

    - #### public static void serialize(Node node, OutputStream os, SerializeOptions options)

      Write a pretty version of the Node to the OutputStream using the specified options.

      Parameters:
        `node` - the Node to serialize
        `os` - the OutputStream to write to
        `options` - the serialization options
      Since:
        6.0.0

    - #### public static String serialize(GPathResult node, SerializeOptions options)

      Return a pretty String version of the GPathResult using the specified options.

      Parameters:
        `node` - a GPathResult to serialize to a String
        `options` - the serialization options
      Returns:
        the pretty String representation of the GPathResult
      Since:
        6.0.0

    - #### public static void serialize(GPathResult node, OutputStream os, SerializeOptions options)

      Write a pretty version of the GPathResult to the OutputStream using the specified options.

      Parameters:
        `node` - a GPathResult to serialize
        `os` - the OutputStream to write to
        `options` - the serialization options
      Since:
        6.0.0

    - #### public static String serialize(Writable writable, SerializeOptions options)

      Return a pretty String version of the XML content produced by the Writable using the specified options.

      Parameters:
        `writable` - the Writable to serialize
        `options` - the serialization options
      Returns:
        the pretty String representation of the content from the Writable
      Since:
        6.0.0

    - #### public static void serialize(Writable writable, OutputStream os, SerializeOptions options)

      Write a pretty version of the XML content produced by the Writable to the OutputStream using the specified options.

      Parameters:
        `writable` - the Writable to serialize
        `os` - the OutputStream to write to
        `options` - the serialization options
      Since:
        6.0.0

    - #### public static String serialize(String xmlString, SerializeOptions options)

      Return a pretty version of the XML content contained in the given String using the specified options.

      Parameters:
        `xmlString` - the String to serialize
        `options` - the serialization options
      Returns:
        the pretty String representation of the original content
      Since:
        6.0.0

    - #### public static void serialize(String xmlString, OutputStream os, SerializeOptions options)

      Write a pretty version of the given XML string to the OutputStream using the specified options.

      Parameters:
        `xmlString` - the String to serialize
        `os` - the OutputStream to write to
        `options` - the serialization options
      Since:
        6.0.0

    - #### public static void setFeatureQuietly(TransformerFactory factory, String feature, boolean value)

      Attempts to set a feature on the transformer factory and ignores unsupported features.

      Parameters:
        `factory` - the transformer factory to configure
        `feature` - the fully qualified JAXP feature URI
        `value` - the value to apply

    - #### public static void setFeatureQuietly(DocumentBuilderFactory factory, String feature, boolean value)

      Attempts to set a feature on the document builder factory and ignores unsupported features.

      Parameters:
        `factory` - the document builder factory to configure
        `feature` - the fully qualified JAXP feature URI
        `value` - the value to apply

    - #### public static void setFeatureQuietly(SAXParserFactory factory, String feature, boolean value)

      Attempts to set a feature on the SAX parser factory and ignores unsupported features.

      Parameters:
        `factory` - the SAX parser factory to configure
        `feature` - the fully qualified JAXP feature URI
        `value` - the value to apply

    - #### public static Stream<Node> streamElements(Reader reader, String localName)

      Streams matching subtrees from a (potentially very large) XML document as DOM Nodes. Each emitted node is the root of one complete element matching `localName`; matching is performed on local name only (any namespace).

      Equivalent to streamElements(reader, null, localName, false).

      Closing the returned stream closes the underlying reader. For parallel per-subtree processing, sink the stream into a virtual-thread executor (JDK 21+).

      Parameters:
        `reader` - the XML source
        `localName` - the element local name to match
      Returns:
        a stream of DOM nodes, one per matching subtree
      Since:
        6.0.0

    - #### public static Stream<Node> streamElements(Reader reader, String namespaceURI, String localName)

      Streams matching subtrees from a (potentially very large) XML document as DOM Nodes. Matching is namespace-qualified.

      Parameters:
        `reader` - the XML source
        `namespaceURI` - the namespace URI to match (use `null` to match any)
        `localName` - the element local name to match
      Returns:
        a stream of DOM nodes, one per matching subtree
      Since:
        6.0.0

    - #### public static Stream<Node> streamElements(Reader reader, String namespaceURI, String localName, boolean allowDocTypeDeclaration)

      Streams matching subtrees from a (potentially very large) XML document as DOM Nodes. Matching is namespace-qualified.

      Parameters:
        `reader` - the XML source
        `namespaceURI` - the namespace URI to match (use `null` to match any)
        `localName` - the element local name to match
        `allowDocTypeDeclaration` - whether DOCTYPE declarations are permitted
      Returns:
        a stream of DOM nodes, one per matching subtree
      Since:
        6.0.0