Package groovy.xml

# Class DOMBuilder

java.lang.Object
groovy.lang.GroovyObjectSupport
groovy.util.BuilderSupport
groovy.xml.DOMBuilder

All Implemented Interfaces:
  `GroovyObject`

public class DOMBuilder extends BuilderSupport
A helper class for creating a W3C DOM tree

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  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)`
  Builder lifecycle callback that creates an element and applies the supplied attributes.
  `protected Object`
  `createNode(Object name, Map attributes, Object value)`
  Builder lifecycle callback that creates an element, applies attributes and adds text content.
  `static DOMBuilder`
  `newInstance()`
  Creates a non-validating, namespace-aware DOM builder.
  `static DOMBuilder`
  `newInstance(boolean validating, boolean namespaceAware)`
  Creates a DOM builder using the requested parser settings.
  `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.
  `static Document`
  `parse(Reader reader)`
  Creates a DocumentBuilder and uses it to parse the XML text read from the given reader.
  `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.
  `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.
  `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.

  ### Methods inherited from class groovy.util.BuilderSupport

  `doInvokeMethod, getCurrent, getName, invokeMethod, invokeMethod, nodeCompleted, postNodeCompletion, setClosureDelegate, setCurrent`

  ### Methods inherited from class groovy.lang.GroovyObjectSupport

  `getMetaClass, setMetaClass`

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

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

  ### Methods inherited from interface groovy.lang.GroovyObject

  `getProperty, setProperty`

- ## Constructor Details

  - ### DOMBuilder

    public DOMBuilder(Document document)
    Creates a builder that appends newly created elements to the supplied document.
    Parameters:
      `document` - the target document to populate

  - ### DOMBuilder

    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 Details

  - ### newInstance

    public static DOMBuilder newInstance() throws ParserConfigurationException
    Creates a non-validating, namespace-aware DOM builder.
    Returns:
      a new DOM builder backed by a freshly created `DocumentBuilder`
    Throws:
      `ParserConfigurationException` - if the parser cannot be configured

  - ### newInstance

    public static DOMBuilder newInstance(boolean validating, boolean namespaceAware) throws ParserConfigurationException
    Creates a DOM builder using the requested parser settings. The underlying parser does not allow DOCTYPE declarations.
    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`
    Throws:
      `ParserConfigurationException` - if the parser cannot be configured
    See Also:
      - `newInstance(boolean, boolean, boolean)`

  - ### newInstance

    public static DOMBuilder newInstance(boolean validating, boolean namespaceAware, boolean allowDocTypeDeclaration) throws ParserConfigurationException
    Creates a DOM builder using the requested parser settings, including whether DOCTYPE declarations are permitted in parsed documents.
    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`
    Throws:
      `ParserConfigurationException` - if the parser cannot be configured
    Since:
      6.0.0

  - ### parse

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

  - ### parse

    public static Document parse(Reader reader, boolean validating, boolean namespaceAware) throws SAXException, IOException, ParserConfigurationException
    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.
    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
    Throws:
      `SAXException` - Any SAX exception, possibly wrapping another exception.
      `IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      `ParserConfigurationException` - if a DocumentBuilder cannot be created which satisfies the configuration requested.

  - ### parse

    public static Document parse(Reader reader, boolean validating, boolean namespaceAware, boolean allowDocTypeDeclaration) throws SAXException, IOException, ParserConfigurationException
    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.
    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
    Throws:
      `SAXException` - Any SAX exception, possibly wrapping another exception.
      `IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      `ParserConfigurationException` - if a DocumentBuilder cannot be created which satisfies the configuration requested.

  - ### parseText

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

  - ### setParent

    protected void setParent(Object parent, Object child)
    Builder lifecycle callback that attaches a completed child node to its parent node.
    Specified by:
      `setParent` in class `BuilderSupport`
    Parameters:
      `parent` - the parent `Node`
      `child` - the child `Node` to append

  - ### createNode

    protected Object createNode(Object name)
    Builder lifecycle callback that creates an element for the supplied node name.
    Specified by:
      `createNode` in class `BuilderSupport`
    Parameters:
      `name` - the node name, either a `QName` or plain element name
    Returns:
      the created `Element`

  - ### createDocument

    protected Document createDocument()
    Creates the backing document used by subsequent builder callbacks. Subclasses may override to supply a custom document implementation.
    Returns:
      a new document ready to receive builder output
    Throws:
      `IllegalArgumentException` - if no `DocumentBuilder` is available

  - ### createNode

    protected Object createNode(Object name, Object value)
    Builder lifecycle callback that creates an element and adds text content to it.
    Specified by:
      `createNode` in class `BuilderSupport`
    Parameters:
      `name` - the node name, either a `QName` or plain element name
      `value` - the text value to append
    Returns:
      the created `Element`

  - ### createNode

    protected Object createNode(Object name, Map attributes, Object value)
    Builder lifecycle callback that creates an element, applies attributes and adds text content.
    Specified by:
      `createNode` in class `BuilderSupport`
    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`

  - ### createNode

    protected Object createNode(Object name, Map attributes)
    Builder lifecycle callback that creates an element and applies the supplied attributes.
    Specified by:
      `createNode` in class `BuilderSupport`
    Parameters:
      `name` - the node name, either a `QName` or plain element name
      `attributes` - the attributes to apply, including namespace declarations
    Returns:
      the created `Element`

  - ### appendNamespaceAttributes

    protected void appendNamespaceAttributes(Element element, Map<Object,Object> attributes)
    Applies namespace declaration attributes from an `xmlns` map to the supplied element.
    Parameters:
      `element` - the element receiving namespace attributes
      `attributes` - the namespace attributes keyed by prefix or `QName`
    Throws:
      `IllegalArgumentException` - if an entry has a `null` value or an unsupported key type