0
# Groovy XML
1

2
Groovy XML provides comprehensive XML processing capabilities for Apache Groovy, including markup builders for creating XML documents using Groovy's builder pattern, SAX and DOM parsing utilities, streaming markup support for large XML documents, and enhanced XML processing methods that integrate seamlessly with Groovy's dynamic nature.
3

4
## Package Information
5

6
- **Package Name**: groovy-xml
7
- **Package Type**: maven
8
- **Group ID**: org.codehaus.groovy
9
- **Artifact ID**: groovy-xml
10
- **Language**: Java/Groovy
11
- **Installation**: 
12
  - Maven: `<dependency><groupId>org.codehaus.groovy</groupId><artifactId>groovy-xml</artifactId><version>2.5.23</version></dependency>`
13
  - Gradle: `implementation 'org.codehaus.groovy:groovy-xml:2.5.23'`
14
  - Note: Often included automatically with Groovy distribution
15

16
## Core Imports
17

18
```java
19
// Core builders and parsers
20
import groovy.xml.MarkupBuilder;
21
import groovy.xml.StreamingMarkupBuilder;
22
import groovy.xml.DOMBuilder;
23
import groovy.xml.SAXBuilder;
24
import groovy.xml.StaxBuilder;
25
import groovy.xml.XmlUtil;
26
import groovy.util.XmlParser;
27
import groovy.util.XmlSlurper;
28

29
// Navigation and results
30
import groovy.util.slurpersupport.GPathResult;
31
import groovy.util.Node;
32

33
// Namespace support
34
import groovy.xml.Namespace;
35
import groovy.xml.QName;
36

37
// Utilities and entities
38
import groovy.xml.XmlNodePrinter;
39
import groovy.xml.Entity;
40

41
// Extension methods
42
import org.codehaus.groovy.runtime.XmlGroovyMethods;
43
```
44

45
For Groovy scripts, core XML classes are often available by default through the Groovy runtime.
46

47
## Basic Usage
48

49
```groovy
50
// Building XML with MarkupBuilder
51
def writer = new StringWriter()
52
def xml = new MarkupBuilder(writer)
53
xml.root {
54
    person(id: '1') {
55
        name('John Doe')
56
        email('john@example.com')
57
    }
58
    person(id: '2') {
59
        name('Jane Smith')
60
        email('jane@example.com')
61
    }
62
}
63
println writer.toString()
64

65
// Parsing XML with XmlSlurper for navigation
66
def slurper = new XmlSlurper()
67
def root = slurper.parseText('''
68
    <root>
69
        <person id="1">
70
            <name>John Doe</name>
71
            <email>john@example.com</email>
72
        </person>
73
    </root>
74
''')
75
println root.person.name.text()  // "John Doe"
76
println root.person.'@id'        // "1"
77

78
// Parsing with XmlParser for manipulation
79
def parser = new XmlParser()
80
def doc = parser.parseText('<root><item>value</item></root>')
81
doc.item[0].value = 'new value'
82
```
83

84
## Architecture
85

86
Groovy XML is built around several key components:
87

88
- **Builders**: Various builder classes (MarkupBuilder, StreamingMarkupBuilder, DOMBuilder) that create XML using Groovy's builder pattern
89
- **Parsers**: XmlParser and XmlSlurper for parsing XML into navigable/manipulable structures
90
- **Navigation**: GPathResult hierarchy providing XPath-like navigation of parsed XML
91
- **Utilities**: XmlUtil for serialization, XmlNodePrinter for pretty printing, and various helper classes
92
- **Extensions**: XmlGroovyMethods that add XML functionality to existing Java classes
93
- **Streaming Support**: Classes for efficient processing of large XML documents
94

95
## Capabilities
96

97
### XML Building
98

99
Comprehensive XML document creation using Groovy's builder pattern. Supports formatted output, streaming generation, and DOM document creation.
100

101
```java { .api }
102
public class MarkupBuilder extends BuilderSupport {
103
    public MarkupBuilder();
104
    public MarkupBuilder(PrintWriter pw);
105
    public MarkupBuilder(Writer writer);
106
    public MarkupBuilder(IndentPrinter out);
107
    
108
    public boolean getDoubleQuotes();
109
    public void setDoubleQuotes(boolean useDoubleQuotes);
110
    public boolean isOmitNullAttributes();
111
    public void setOmitNullAttributes(boolean omitNullAttributes);
112
    public MarkupBuilderHelper getMkp();
113
}
114
```
115

116
[XML Builders](./builders.md)
117

118
### XML Parsing
119

120
Parse XML documents into navigable structures using either Node-based manipulation (XmlParser) or XPath-like navigation (XmlSlurper).
121

122
```java { .api }
123
public class XmlParser implements ContentHandler {
124
    public XmlParser();
125
    public XmlParser(boolean validating, boolean namespaceAware);
126
    
127
    public Node parse(File file) throws IOException, SAXException;
128
    public Node parse(InputStream input) throws IOException, SAXException;
129
    public Node parseText(String text) throws SAXException;
130
}
131

132
public class XmlSlurper extends DefaultHandler {
133
    public XmlSlurper();
134
    public XmlSlurper(boolean validating, boolean namespaceAware);
135
    
136
    public GPathResult parse(File file) throws IOException, SAXException;
137
    public GPathResult parse(InputStream input) throws IOException, SAXException;
138
    public GPathResult parseText(String text) throws SAXException;
139
}
140
```
141

142
[XML Parsing](./parsing.md)
143

144
### XML Navigation and Querying
145

146
XPath-like navigation through parsed XML using the GPathResult hierarchy, with support for filtering, traversal, and content extraction.
147

148
```java { .api }
149
public abstract class GPathResult implements Writable, Buildable, Iterable<GPathResult> {
150
    public GPathResult parent();
151
    public GPathResult children();
152
    public String name();
153
    public abstract String text();
154
    public abstract int size();
155
    
156
    public Object getAt(int index);
157
    public Iterator<GPathResult> iterator();
158
    public Iterator<GPathResult> depthFirst();
159
    public abstract GPathResult find(Closure closure);
160
    public abstract GPathResult findAll(Closure closure);
161
}
162
```
163

164
[XML Navigation](./navigation.md)
165

166
### XML Utilities and Serialization
167

168
Utility functions for XML serialization, escaping, parser creation, and pretty printing of XML structures.
169

170
```java { .api }
171
public class XmlUtil {
172
    public static String serialize(Element element);
173
    public static String serialize(Node node);
174
    public static String serialize(GPathResult node);
175
    public static String serialize(Writable writable);
176
    
177
    public static SAXParser newSAXParser(String schemaLanguage, Source... schemas)
178
        throws ParserConfigurationException, SAXException;
179
    public static String escapeXml(String orig);
180
}
181
```
182

183
[XML Utilities](./utilities.md)
184

185
### Streaming XML Processing
186

187
Efficient streaming XML generation and processing for large documents, using StreamingMarkupBuilder and associated support classes.
188

189
```groovy { .api }
190
class StreamingMarkupBuilder extends AbstractStreamingBuilder {
191
    boolean useDoubleQuotes
192
    boolean expandEmptyElements
193
    String encoding
194
    
195
    Writable bind(Closure closure)
196
    Writable bindNode(Object node)
197
}
198
```
199

200
[Streaming XML](./streaming.md)
201

202
### Namespace Support
203

204
Comprehensive namespace support including namespace-aware parsing, building, and navigation with proper prefix handling.
205

206
```java { .api }
207
public class Namespace {
208
    public Namespace();
209
    public Namespace(String uri);
210
    public Namespace(String uri, String prefix);
211
    
212
    public QName get(String localName);
213
    public String getPrefix();
214
    public String getUri();
215
}
216
```
217

218
[Namespace Support](./namespaces.md)
219

220
### JAXB Integration
221

222
JAXB (Java Architecture for XML Binding) support for marshalling and unmarshalling Java objects to/from XML.
223

224
```groovy { .api }
225
@Deprecated
226
class JaxbGroovyMethods {
227
    static <T> String marshal(Marshaller self, T jaxbElement)
228
    static <T> T unmarshal(Unmarshaller self, String xml)
229
    static Marshaller createMarshaller(JAXBContext self)
230
    static Unmarshaller createUnmarshaller(JAXBContext self)
231
}
232
```
233

234
[JAXB Integration](./jaxb.md)
235

236
### XML Entities
237

238
Predefined XML and HTML entity constants for special characters and symbols.
239

240
```groovy { .api }
241
class Entity implements Buildable {
242
    Entity(String name)
243
    Entity(int name)
244
    void build(GroovyObject builder)
245
    
246
    // Predefined entities
247
    static final Entity lt, gt, amp, quot, apos  // Core XML entities
248
    static final Entity nbsp, copy, reg, deg     // Common symbols
249
    static final Entity eacute, ntilde, uuml    // Accented characters
250
    // ... many more predefined entities
251
}
252
```
253

254
[XML Entities](./entities.md)
255

256
## Types
257

258
```java { .api }
259
// Core Node type for XmlParser results
260
public class Node {
261
    public String name();
262
    public String text();
263
    public List<Node> children();
264
    public Map<String, String> attributes();
265
    public Object get(String key);
266
    public void setValue(String value);
267
}
268

269
// QName for namespace-aware operations
270
public class QName {
271
    public QName(String localName);
272
    public QName(String namespaceURI, String localName);
273
    public QName(String namespaceURI, String localName, String prefix);
274
    
275
    public String getLocalName();
276
    public String getNamespaceURI();
277
    public String getPrefix();
278
}
279

280
// Markup builder helper for special operations
281
public class MarkupBuilderHelper {
282
    public void yield(Object value);
283
    public void yieldUnescaped(Object value);
284
    public void comment(String value);
285
    public void xmlDeclaration(Map<String, Object> args);
286
}
287

288
// Extension methods support
289
public class XmlGroovyMethods {
290
    public static Iterator<Node> iterator(NodeList nodeList);
291
    public static String serialize(Element element);
292
}
293

294
// DOMBuilder for W3C DOM document creation
295
public class DOMBuilder extends BuilderSupport {
296
    public static DOMBuilder newInstance() throws ParserConfigurationException;
297
    public static DOMBuilder newInstance(boolean validating, boolean namespaceAware) 
298
        throws ParserConfigurationException;
299
    public static Document parse(Reader reader) 
300
        throws IOException, SAXException, ParserConfigurationException;
301
    public static Document parse(Reader reader, boolean validating, boolean namespaceAware)
302
        throws IOException, SAXException, ParserConfigurationException;
303
    public Document parseText(String text) throws SAXException, IOException;
304
}
305

306
// StaxBuilder for StAX-based XML processing
307
public class StaxBuilder extends BuilderSupport {
308
    public StaxBuilder(XMLStreamWriter xmlStreamWriter);
309
}
310

311
// SAXBuilder for SAX-based XML generation  
312
public class SAXBuilder extends BuilderSupport {
313
    public SAXBuilder(SAXResult saxResult);
314
}
315

316
// Utility for converting XML to Groovy code
317
public class DomToGroovy {
318
    public static void print(PrintWriter out, Element element);
319
    public static void print(PrintWriter out, Document document);
320
}
321
```