Package groovy.xml

# Class XmlUtil

java.lang.Object
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.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `XmlUtil()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `escapeControlCharacters(String orig)`
  Escape control characters (below 0x20) with their XML entities, e.g.
  `static String`
  `escapeXml(String orig)`
  Escape the following characters `" ' & < >` with their XML entities, e.g.
  `static Stream<XMLEvent>`
  `events(Reader reader)`
  Streams XML events from the supplied `Reader` using a hardened StAX `XMLInputFactory`.
  `static Stream<XMLEvent>`
  `events(Reader reader, boolean allowDocTypeDeclaration)`
  Streams XML events from the supplied `Reader` using a hardened StAX `XMLInputFactory`.
  `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.
  `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.
  `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.
  `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.
  `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.
  `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.
  `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.
  `static String`
  `serialize(Writable writable)`
  Return a pretty String version of the XML content produced by the Writable.
  `static String`
  `serialize(Writable writable, SerializeOptions options)`
  Return a pretty String version of the XML content produced by the Writable using the specified options.
  `static void`
  `serialize(Writable writable, OutputStream os)`
  Write a pretty version of the XML content produced by the Writable to the OutputStream.
  `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.
  `static void`
  `serialize(Writable writable, Writer w)`
  Write a pretty version of the XML content produced by the Writable to the Writer.
  `static String`
  `serialize(Node node)`
  Return a pretty String version of the Node.
  `static String`
  `serialize(Node node, SerializeOptions options)`
  Return a pretty String version of the Node using the specified options.
  `static void`
  `serialize(Node node, OutputStream os)`
  Write a pretty version of the Node to the OutputStream.
  `static void`
  `serialize(Node node, OutputStream os, SerializeOptions options)`
  Write a pretty version of the Node to the OutputStream using the specified options.
  `static void`
  `serialize(Node node, Writer w)`
  Write a pretty version of the Node to the Writer.
  `static String`
  `serialize(GPathResult node)`
  Return a pretty version of the GPathResult.
  `static String`
  `serialize(GPathResult node, SerializeOptions options)`
  Return a pretty String version of the GPathResult using the specified options.
  `static void`
  `serialize(GPathResult node, OutputStream os)`
  Write a pretty version of the GPathResult to the OutputStream.
  `static void`
  `serialize(GPathResult node, OutputStream os, SerializeOptions options)`
  Write a pretty version of the GPathResult to the OutputStream using the specified options.
  `static void`
  `serialize(GPathResult node, Writer w)`
  Write a pretty version of the GPathResult to the Writer.
  `static String`
  `serialize(String xmlString)`
  Return a pretty version of the XML content contained in the given String.
  `static String`
  `serialize(String xmlString, boolean allowDocTypeDeclaration)`
  Return a pretty version of the XML content contained in the given String.
  `static String`
  `serialize(String xmlString, SerializeOptions options)`
  Return a pretty version of the XML content contained in the given String using the specified options.
  `static void`
  `serialize(String xmlString, OutputStream os)`
  Write a pretty version of the given XML string to the OutputStream.
  `static void`
  `serialize(String xmlString, OutputStream os, boolean allowDocTypeDeclaration)`
  Write a pretty version of the given XML string to the OutputStream.
  `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.
  `static void`
  `serialize(String xmlString, Writer w)`
  Write a pretty version of the given XML string to the Writer.
  `static void`
  `serialize(String xmlString, Writer w, boolean allowDocTypeDeclaration)`
  Write a pretty version of the given XML string to the Writer.
  `static String`
  `serialize(Element element)`
  Return a pretty String version of the Element.
  `static String`
  `serialize(Element element, boolean allowDocTypeDeclaration)`
  Return a pretty String version of the Element.
  `static String`
  `serialize(Element element, SerializeOptions options)`
  Return a pretty String version of the Element using the specified options.
  `static void`
  `serialize(Element element, OutputStream os)`
  Write a pretty version of the Element to the OutputStream.
  `static void`
  `serialize(Element element, OutputStream os, boolean allowDocTypeDeclaration)`
  Write a pretty version of the Element to the OutputStream.
  `static void`
  `serialize(Element element, OutputStream os, SerializeOptions options)`
  Write a pretty version of the Element to the OutputStream using the specified options.
  `static void`
  `serialize(Element element, Writer w)`
  Write a pretty version of the Element to the Writer.
  `static void`
  `serialize(Element element, Writer w, boolean allowDocTypeDeclaration)`
  Write a pretty version of the Element to the Writer.
  `static void`
  `setFeatureQuietly(DocumentBuilderFactory factory, String feature, boolean value)`
  Attempts to set a feature on the document builder factory and ignores unsupported features.
  `static void`
  `setFeatureQuietly(SAXParserFactory factory, String feature, boolean value)`
  Attempts to set a feature on the SAX parser factory and ignores unsupported features.
  `static void`
  `setFeatureQuietly(TransformerFactory factory, String feature, boolean value)`
  Attempts to set a feature on the transformer factory and ignores unsupported features.
  `static Stream<Node>`
  `streamElements(Reader reader, String localName)`
  Streams matching subtrees from a (potentially very large) XML document as DOM `Node`s.
  `static Stream<Node>`
  `streamElements(Reader reader, String namespaceURI, String localName)`
  Streams matching subtrees from a (potentially very large) XML document as DOM `Node`s.
  `static Stream<Node>`
  `streamElements(Reader reader, String namespaceURI, String localName, boolean allowDocTypeDeclaration)`
  Streams matching subtrees from a (potentially very large) XML document as DOM `Node`s.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### XmlUtil

    public XmlUtil()

- ## Method Details

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### serialize

    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

  - ### newSAXParser

    public static SAXParser newSAXParser(String schemaLanguage, Source... schemas) throws SAXException, ParserConfigurationException
    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.
    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
    Throws:
      `SAXException`
      `ParserConfigurationException`
    Since:
      1.8.7
    See Also:
      - `newSAXParser(String, boolean, boolean, Source...)`

  - ### newSAXParser

    public static SAXParser newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, Source... schemas) throws SAXException, ParserConfigurationException
    Factory method to create a SAXParser configured to validate according to a particular schema language and optionally providing the schema sources to validate with.
    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
    Throws:
      `SAXException`
      `ParserConfigurationException`
    Since:
      1.8.7

  - ### newSAXParser

    public static SAXParser newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, boolean allowDoctypeDecl, Source... schemas) throws SAXException, ParserConfigurationException
    Factory method to create a SAXParser configured to validate according to a particular schema language and optionally providing the schema sources to validate with.
    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
    Throws:
      `SAXException`
      `ParserConfigurationException`
    Since:
      3.0.11

  - ### newSAXParser

    public static SAXParser newSAXParser(String schemaLanguage, File schema) throws SAXException, ParserConfigurationException
    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.
    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
    Throws:
      `SAXException`
      `ParserConfigurationException`
    Since:
      1.8.7
    See Also:
      - `newSAXParser(String, boolean, boolean, File)`

  - ### newSAXParser

    public static SAXParser newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, File schema) throws SAXException, ParserConfigurationException
    Factory method to create a SAXParser configured to validate according to a particular schema language and a File containing the schema to validate against.
    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
    Throws:
      `SAXException`
      `ParserConfigurationException`
    Since:
      1.8.7

  - ### newSAXParser

    public static SAXParser newSAXParser(String schemaLanguage, URL schema) throws SAXException, ParserConfigurationException
    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.
    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
    Throws:
      `SAXException`
      `ParserConfigurationException`
    Since:
      1.8.7
    See Also:
      - `newSAXParser(String, boolean, boolean, URL)`

  - ### newSAXParser

    public static SAXParser newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, URL schema) throws SAXException, ParserConfigurationException
    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.
    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
    Throws:
      `SAXException`
      `ParserConfigurationException`
    Since:
      1.8.7

  - ### escapeXml

    public static String escapeXml(String orig)
    Escape the following characters `" ' & < >` with their XML entities, e.g. `"bread" & "butter"` becomes `&quot;bread&quot; &amp; &quot;butter&quot`. 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)`

  - ### escapeControlCharacters

    public static String escapeControlCharacters(String orig)
    Escape control characters (below 0x20) with their XML entities, e.g. carriage return (`Ctrl-M or \r`) becomes `&#13;` 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)`

  - ### setFeatureQuietly

    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

  - ### setFeatureQuietly

    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

  - ### setFeatureQuietly

    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

  - ### events

    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, false)`.

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

  - ### events

    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 `XMLEvent`s
    Since:
      6.0.0

  - ### streamElements

    public static Stream<Node> streamElements(Reader reader, String localName)
    Streams matching subtrees from a (potentially very large) XML document as DOM `Node`s. 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

  - ### streamElements

    public static Stream<Node> streamElements(Reader reader, String namespaceURI, String localName)
    Streams matching subtrees from a (potentially very large) XML document as DOM `Node`s. 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

  - ### streamElements

    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 `Node`s. 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