Documentation: Add StaxBuilder documentation

src/spec/doc/core-domain-specific-languages.adoc

@@ -1033,9 +1033,7 @@ See <<_streamingmarkupbuilder,Creating Xml - StreamingMarkupBuilder>>.
 
 (TBD)
 
-==== StaxBuilder
-
-(TBD)
+include::{projectdir}/subprojects/groovy-xml/{specfolder}/stax-builder.adoc[leveloffset=+3]
 
 ==== DomBuilder
 

subprojects/groovy-xml/src/spec/doc/stax-builder.adoc

@@ -0,0 +1,17 @@
+= StaxBuilder
+
+A Groovy builder that works with http://en.wikipedia.org/wiki/StAX[Streaming API for XML (StAX)] processors.
+
+Here is a simple example using the StAX implementation of Java to generate XML:
+
+[source,groovy]
+----
+include::{rootProjectDir}/subprojects/groovy-xml/src/spec/test/StaxBuilderTest.groovy[tags=stax_builder,indent=0]
+----
+
+An external library such as http://jettison.codehaus.org/[Jettison] can be used as follows:
+
+[source,groovy]
+----
+include::{rootProjectDir}/subprojects/groovy-xml/src/spec/test/StaxBuilderTest.groovy[tags=stax_builder_external_library,indent=0]
+----

subprojects/groovy-xml/src/spec/test/StaxBuilderTest.groovy

@@ -0,0 +1,56 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+
+class StaxBuilderTest extends GroovyTestCase {
+
+    void testStaxBuilder() {
+        // tag::stax_builder[]
+        def factory = javax.xml.stream.XMLOutputFactory.newInstance()
+        def writer = new StringWriter()
+        def builder = new groovy.xml.StaxBuilder(factory.createXMLStreamWriter(writer))
+
+        builder.root(attribute:1) {
+            elem1('hello')
+            elem2('world')
+        }
+
+        assert writer.toString() == '<?xml version="1.0" ?><root attribute="1"><elem1>hello</elem1><elem2>world</elem2></root>'
+        // end::stax_builder[]
+    }
+
+    void testStaxBuilderExternalLibrary() {
+        assertScript '''
+            // tag::stax_builder_external_library[]
+            @Grab('org.codehaus.jettison:jettison:1.3.3')
+            import org.codehaus.jettison.mapped.*
+
+            def writer = new StringWriter()
+            def mappedWriter = new MappedXMLStreamWriter(new MappedNamespaceConvention(), writer)
+            def builder = new groovy.xml.StaxBuilder(mappedWriter)
+            
+            builder.root(attribute:1) {
+                 elem1('hello')
+                 elem2('world')
+            }
+            
+            assert writer.toString() == '{"root":{"@attribute":"1","elem1":"hello","elem2":"world"}}'
+            // end::stax_builder_external_library[]
+        '''
+    }
+}