Package: groovy.xml

## [Groovy] Class StaxBuilder

- groovy.xml.StaxBuilder

-     class StaxBuilder
      extends BuilderSupport

  A Groovy builder that emits XML using a StAX writer.

  Typical usage:

       import javax.xml.stream.XMLOutputFactory
       def factory = XMLOutputFactory.newInstance()
       def writer = new StringWriter()
       def builder = new groovy.xml.StaxBuilder(factory.createXMLStreamWriter(writer))
       builder.root1(a:5, b:7) {
           elem1('hello1')
           elem2('hello2')
           elem3(x:7)
       }
       def pretty = writer.toString()
           .replaceAll(/<\?xml[^>]*>/, '') // remove XML declaration
       assert pretty in ['hello1hello2',
                         'hello1hello2']

  StAX-compatible writers from external libraries, such as Jettison, may also be used.

- - ### Properties Summary

    Properties
    Type | Name and description
    --- | ---
    `Object` | `writer` Writer receiving the XML document generated by this builder.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `StaxBuilder(Object xmlStreamWriter)` Creates a builder that writes a new XML document to the supplied StAX writer.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `protected Object` | `createNode(Object name)` Creates an element with no attributes or body text.
    `` | `protected Object` | `createNode(Object name, Object value)` Creates an element containing simple text content.
    `` | `protected Object` | `createNode(Object name, Map attributes)` Creates an element with attributes and no body text.
    `` | `protected Object` | `createNode(Object name, Map attributes, Object value)` Creates an element and writes any supplied attributes and text content.
    `` | `protected void` | `nodeCompleted(Object parent, Object node)` Closes the current element and finalizes the document when the root node completes.
    `` | `protected void` | `setParent(Object parent, Object child)` No-op for StAX output because parent relationships are managed by the stream writer itself.

  - ### 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`

- - ### Property Detail

    - #### Object writer

      Writer receiving the XML document generated by this builder.

  - ### Constructor Detail

    - #### StaxBuilder(Object xmlStreamWriter)

      Creates a builder that writes a new XML document to the supplied StAX writer.

      Parameters:
        `xmlStreamWriter` - writer that receives generated XML events

  - ### Method Detail

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

      Creates an element with no attributes or body text.

      Parameters:
        `name` - element name
      Returns:
        the node token used by BuilderSupport

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

      Creates an element containing simple text content.

      Parameters:
        `name` - element name
        `value` - text value to write inside the element
      Returns:
        the node token used by BuilderSupport

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

      Creates an element with attributes and no body text.

      Parameters:
        `name` - element name
        `attributes` - attribute values to write on the element
      Returns:
        the node token used by BuilderSupport

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

      Creates an element and writes any supplied attributes and text content.

      Parameters:
        `name` - element name
        `attributes` - attribute values to write on the element
        `value` - text value to write inside the element
      Returns:
        the node token used by BuilderSupport

    - #### @SuppressWarnings(value="UnusedMethodParameter")
      protected void nodeCompleted(Object parent, Object node)

      Closes the current element and finalizes the document when the root node completes.

      Parameters:
        `parent` - parent node token, or `null` for the document root
        `node` - completed node token

    - #### @SuppressWarnings(value=["UnusedMethodParameter", "EmptyMethod"])
      protected void setParent(Object parent, Object child)

      No-op for StAX output because parent relationships are managed by the stream writer itself.

      Parameters:
        `parent` - parent node token
        `child` - child node token