From 4bda86b9d56262db834dc6f65664a8a580fe26e7 Mon Sep 17 00:00:00 2001
From: Pascal Schumacher <pascalschumacher@gmx.net>
Date: Mon, 13 Apr 2015 10:28:17 +0200
Subject: [PATCH] Documentation: Add StaxBuilder documentation

---
 .../doc/core-domain-specific-languages.adoc   |  4 +-
 .../groovy-xml/src/spec/doc/stax-builder.adoc | 17 ++++++
 .../src/spec/test/StaxBuilderTest.groovy      | 56 +++++++++++++++++++
 3 files changed, 74 insertions(+), 3 deletions(-)
 create mode 100644 subprojects/groovy-xml/src/spec/doc/stax-builder.adoc
 create mode 100644 subprojects/groovy-xml/src/spec/test/StaxBuilderTest.groovy

diff --git a/src/spec/doc/core-domain-specific-languages.adoc b/src/spec/doc/core-domain-specific-languages.adoc
index b35ea2a4d5..69f89f45fa 100644
--- a/src/spec/doc/core-domain-specific-languages.adoc
+++ b/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
 
diff --git a/subprojects/groovy-xml/src/spec/doc/stax-builder.adoc b/subprojects/groovy-xml/src/spec/doc/stax-builder.adoc
new file mode 100644
index 0000000000..88ee63ee59
--- /dev/null
+++ b/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]
+----
\ No newline at end of file
diff --git a/subprojects/groovy-xml/src/spec/test/StaxBuilderTest.groovy b/subprojects/groovy-xml/src/spec/test/StaxBuilderTest.groovy
new file mode 100644
index 0000000000..707776a227
--- /dev/null
+++ b/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[]
+        '''
+    }
+}
\ No newline at end of file