Package: groovy.xml

## [Java] Class DOMBuilder

- groovy.xml.DOMBuilder

-     public class DOMBuilder
      extends BuilderSupport

  A helper class for creating a W3C DOM tree

- - ### Constructor Summary

    Constructors
    Constructor and description
    `DOMBuilder(Document document)` Creates a builder that appends newly created elements to the supplied document.
    `DOMBuilder(DocumentBuilder documentBuilder)` Creates a builder that lazily creates a backing document from the supplied document builder.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `protected void` | `appendNamespaceAttributes(Element element, Map<Object, Object> attributes)` Applies namespace declaration attributes from an `xmlns` map to the supplied element.
    `` | `protected Document` | `createDocument()` Creates the backing document used by subsequent builder callbacks.
    `` | `protected Object` | `createNode(Object name)` Builder lifecycle callback that creates an element for the supplied node name.
    `` | `protected Object` | `createNode(Object name, Object value)` Builder lifecycle callback that creates an element and adds text content to it.
    `` | `protected Object` | `createNode(Object name, Map attributes, Object value)` Builder lifecycle callback that creates an element, applies attributes and adds text content.
    `` | `protected Object` | `createNode(Object name, Map attributes)` Builder lifecycle callback that creates an element and applies the supplied attributes.
    `` | `public static DOMBuilder` | `newInstance()` Creates a non-validating, namespace-aware DOM builder.
    `` | `public static DOMBuilder` | `newInstance(boolean validating, boolean namespaceAware)` Creates a DOM builder using the requested parser settings.
    `` | `public static DOMBuilder` | `newInstance(boolean validating, boolean namespaceAware, boolean allowDocTypeDeclaration)` Creates a DOM builder using the requested parser settings, including whether DOCTYPE declarations are permitted in parsed documents.
    `` | `public static Document` | `parse(Reader reader)` Creates a DocumentBuilder and uses it to parse the XML text read from the given reader.
    `` | `public static Document` | `parse(Reader reader, boolean validating, boolean namespaceAware)` Creates a DocumentBuilder and uses it to parse the XML text read from the given reader, allowing parser validation and namespace awareness to be controlled.
    `` | `public static Document` | `parse(Reader reader, boolean validating, boolean namespaceAware, boolean allowDocTypeDeclaration)` Creates a DocumentBuilder and uses it to parse the XML text read from the given reader, allowing parser validation, namespace awareness and permission of DOCTYPE declarations to be controlled.
    `` | `public Document` | `parseText(String text)` A helper method to parse the given text as XML.
    `` | `protected void` | `setParent(Object parent, Object child)` Builder lifecycle callback that attaches a completed child node to its parent node.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class BuilderSupport` | `createNode, createNode, createNode, createNode, doInvokeMethod, getCurrent, getName, invokeMethod, invokeMethod, nodeCompleted, postNodeCompletion, setClosureDelegate, setCurrent, setParent`
    `class GroovyObjectSupport` | `getMetaClass, setMetaClass`

- - ### Constructor Detail

    - #### public DOMBuilder(Document document)

      Creates a builder that appends newly created elements to the supplied document.

      Parameters:
        `document` - the target document to populate

    - #### public DOMBuilder(DocumentBuilder documentBuilder)

      Creates a builder that lazily creates a backing document from the supplied document builder.

      Parameters:
        `documentBuilder` - the document builder used when a new document is required

  - ### Method Detail

    - #### protected void appendNamespaceAttributes(Element element, Map<Object, Object> attributes)

      Applies namespace declaration attributes from an `xmlns` map to the supplied element.

      throws:
        IllegalArgumentException if an entry has a `null` value or an unsupported key type
      Parameters:
        `element` - the element receiving namespace attributes
        `attributes` - the namespace attributes keyed by prefix or QName

    - #### protected Document createDocument()

      Creates the backing document used by subsequent builder callbacks. Subclasses may override to supply a custom document implementation.

      throws:
        IllegalArgumentException if no DocumentBuilder is available
      Returns:
        a new document ready to receive builder output

    - #### protected Object createNode(Object name)

      Builder lifecycle callback that creates an element for the supplied node name.

      Parameters:
        `name` - the node name, either a QName or plain element name
      Returns:
        the created Element

    - #### protected Object createNode(Object name, Object value)

      Builder lifecycle callback that creates an element and adds text content to it.

      Parameters:
        `name` - the node name, either a QName or plain element name
        `value` - the text value to append
      Returns:
        the created Element

    - #### protected Object createNode(Object name, Map attributes, Object value)

      Builder lifecycle callback that creates an element, applies attributes and adds text content.

      Parameters:
        `name` - the node name, either a QName or plain element name
        `attributes` - the attributes to apply to the created element
        `value` - the text value to append
      Returns:
        the created Element

    - #### protected Object createNode(Object name, Map attributes)

      Builder lifecycle callback that creates an element and applies the supplied attributes.

      Parameters:
        `name` - the node name, either a QName or plain element name
        `attributes` - the attributes to apply, including namespace declarations
      Returns:
        the created Element

    - #### public static DOMBuilder newInstance()

      Creates a non-validating, namespace-aware DOM builder.

      throws:
        ParserConfigurationException if the parser cannot be configured
      Returns:
        a new DOM builder backed by a freshly created DocumentBuilder

    - #### public static DOMBuilder newInstance(boolean validating, boolean namespaceAware)

      Creates a DOM builder using the requested parser settings. The underlying parser does not allow DOCTYPE declarations.

      throws:
        ParserConfigurationException if the parser cannot be configured
      Parameters:
        `validating` - whether the parser should validate source documents
        `namespaceAware` - whether the parser should be namespace aware
      Returns:
        a new DOM builder backed by a freshly created DocumentBuilder
      See Also:
        newInstance(boolean, boolean, boolean)

    - #### public static DOMBuilder newInstance(boolean validating, boolean namespaceAware, boolean allowDocTypeDeclaration)

      Creates a DOM builder using the requested parser settings, including whether DOCTYPE declarations are permitted in parsed documents.

      throws:
        ParserConfigurationException if the parser cannot be configured
      Parameters:
        `validating` - whether the parser should validate source documents
        `namespaceAware` - whether the parser should be namespace aware
        `allowDocTypeDeclaration` - whether the parser should allow DOCTYPE declarations
      Returns:
        a new DOM builder backed by a freshly created DocumentBuilder
      Since:
        6.0.0

    - #### public static Document parse(Reader reader)

      Creates a DocumentBuilder and uses it to parse the XML text read from the given reader. A non-validating, namespace aware parser which does not allow DOCTYPE declarations is used.

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      throws:
        ParserConfigurationException if a DocumentBuilder cannot be created which satisfies the configuration requested.
      Parameters:
        `reader` - the reader to read the XML text from
      Returns:
        the root node of the parsed tree of Nodes
      See Also:
        parse(Reader, boolean, boolean)

    - #### public static Document parse(Reader reader, boolean validating, boolean namespaceAware)

      Creates a DocumentBuilder and uses it to parse the XML text read from the given reader, allowing parser validation and namespace awareness to be controlled. Documents are not allowed to contain DOCYTYPE declarations.

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      throws:
        ParserConfigurationException if a DocumentBuilder cannot be created which satisfies the configuration requested.
      Parameters:
        `reader` - the reader to read the XML text from
        `validating` - whether to validate the XML
        `namespaceAware` - whether the parser should be namespace aware
      Returns:
        the root node of the parsed tree of Nodes

    - #### public static Document parse(Reader reader, boolean validating, boolean namespaceAware, boolean allowDocTypeDeclaration)

      Creates a DocumentBuilder and uses it to parse the XML text read from the given reader, allowing parser validation, namespace awareness and permission of DOCTYPE declarations to be controlled.

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      throws:
        ParserConfigurationException if a DocumentBuilder cannot be created which satisfies the configuration requested.
      Parameters:
        `reader` - the reader to read the XML text from
        `validating` - whether to validate the XML
        `namespaceAware` - whether the parser should be namespace aware
        `allowDocTypeDeclaration` - whether the parser should allow DOCTYPE declarations
      Returns:
        the root node of the parsed tree of Nodes

    - #### public Document parseText(String text)

      A helper method to parse the given text as XML.

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      throws:
        ParserConfigurationException if a DocumentBuilder cannot be created which satisfies the configuration requested.
      Parameters:
        `text` - the XML text to parse
      Returns:
        the root node of the parsed tree of Nodes
      See Also:
        parse(Reader)

    - #### protected void setParent(Object parent, Object child)

      Builder lifecycle callback that attaches a completed child node to its parent node.

      Parameters:
        `parent` - the parent Node
        `child` - the child Node to append