0
# XML Utilities
1

2
Utility functions for XML serialization, pretty printing, escaping, and advanced parser configuration with schema validation support. Essential tools for XML processing workflows.
3

4
## Capabilities
5

6
### XmlUtil
7

8
Comprehensive utility class providing serialization, pretty printing, and XML processing utilities for various XML object types.
9

10
#### Serialization Methods for DOM Elements
11

12
```groovy { .api }
13
/**
14
 * Serialize DOM Element to formatted XML string
15
 * @param element - DOM Element to serialize
16
 * @return Pretty-printed XML string
17
 */
18
static String serialize(Element element)
19

20
/**
21
 * Serialize DOM Element with DOCTYPE control
22
 * @param element - DOM Element to serialize
23
 * @param allowDocTypeDeclaration - Whether to allow DOCTYPE declarations
24
 * @return Pretty-printed XML string
25
 */
26
static String serialize(Element element, boolean allowDocTypeDeclaration)
27

28
/**
29
 * Serialize DOM Element to OutputStream
30
 * @param element - DOM Element to serialize
31
 * @param os - OutputStream for output
32
 */
33
static void serialize(Element element, OutputStream os)
34

35
/**
36
 * Serialize DOM Element to OutputStream with DOCTYPE control
37
 * @param element - DOM Element to serialize
38
 * @param os - OutputStream for output
39
 * @param allowDocTypeDeclaration - Whether to allow DOCTYPE declarations
40
 */
41
static void serialize(Element element, OutputStream os, boolean allowDocTypeDeclaration)
42

43
/**
44
 * Serialize DOM Element to Writer
45
 * @param element - DOM Element to serialize
46
 * @param writer - Writer for output
47
 */
48
static void serialize(Element element, Writer writer)
49

50
/**
51
 * Serialize DOM Element to Writer with DOCTYPE control
52
 * @param element - DOM Element to serialize
53
 * @param writer - Writer for output
54
 * @param allowDocTypeDeclaration - Whether to allow DOCTYPE declarations
55
 */
56
static void serialize(Element element, Writer writer, boolean allowDocTypeDeclaration)
57
```
58

59
#### Serialization Methods for Groovy Nodes
60

61
```groovy { .api }
62
/**
63
 * Serialize groovy.util.Node to formatted XML string
64
 * @param node - Node to serialize
65
 * @return Pretty-printed XML string
66
 */
67
static String serialize(Node node)
68

69
/**
70
 * Serialize groovy.util.Node to OutputStream
71
 * @param node - Node to serialize
72
 * @param os - OutputStream for output
73
 */
74
static void serialize(Node node, OutputStream os)
75

76
/**
77
 * Serialize groovy.util.Node to Writer
78
 * @param node - Node to serialize
79
 * @param writer - Writer for output
80
 */
81
static void serialize(Node node, Writer writer)
82
```
83

84
#### Serialization Methods for GPathResult
85

86
```groovy { .api }
87
/**
88
 * Serialize GPathResult to formatted XML string
89
 * @param gPathResult - GPathResult to serialize
90
 * @return Pretty-printed XML string
91
 */
92
static String serialize(GPathResult gPathResult)
93

94
/**
95
 * Serialize GPathResult to OutputStream
96
 * @param gPathResult - GPathResult to serialize
97
 * @param os - OutputStream for output
98
 */
99
static void serialize(GPathResult gPathResult, OutputStream os)
100

101
/**
102
 * Serialize GPathResult to Writer
103
 * @param gPathResult - GPathResult to serialize
104
 * @param writer - Writer for output
105
 */
106
static void serialize(GPathResult gPathResult, Writer writer)
107
```
108

109
#### Serialization Methods for Writable Objects
110

111
```groovy { .api }
112
/**
113
 * Serialize Writable object to formatted XML string
114
 * @param writable - Writable object to serialize
115
 * @return Pretty-printed XML string
116
 */
117
static String serialize(Writable writable)
118

119
/**
120
 * Serialize Writable object to OutputStream
121
 * @param writable - Writable object to serialize
122
 * @param os - OutputStream for output
123
 */
124
static void serialize(Writable writable, OutputStream os)
125

126
/**
127
 * Serialize Writable object to Writer
128
 * @param writable - Writable object to serialize
129
 * @param writer - Writer for output
130
 */
131
static void serialize(Writable writable, Writer writer)
132
```
133

134
#### Serialization Methods for XML Strings
135

136
```groovy { .api }
137
/**
138
 * Pretty-print XML string
139
 * @param xmlString - XML string to format
140
 * @return Pretty-printed XML string
141
 */
142
static String serialize(String xmlString)
143

144
/**
145
 * Pretty-print XML string with DOCTYPE control
146
 * @param xmlString - XML string to format
147
 * @param allowDocTypeDeclaration - Whether to allow DOCTYPE declarations
148
 * @return Pretty-printed XML string
149
 */
150
static String serialize(String xmlString, boolean allowDocTypeDeclaration)
151

152
/**
153
 * Pretty-print XML string to OutputStream
154
 * @param xmlString - XML string to format
155
 * @param os - OutputStream for output
156
 */
157
static void serialize(String xmlString, OutputStream os)
158

159
/**
160
 * Pretty-print XML string to OutputStream with DOCTYPE control
161
 * @param xmlString - XML string to format
162
 * @param os - OutputStream for output
163
 * @param allowDocTypeDeclaration - Whether to allow DOCTYPE declarations
164
 */
165
static void serialize(String xmlString, OutputStream os, boolean allowDocTypeDeclaration)
166

167
/**
168
 * Pretty-print XML string to Writer
169
 * @param xmlString - XML string to format
170
 * @param writer - Writer for output
171
 */
172
static void serialize(String xmlString, Writer writer)
173

174
/**
175
 * Pretty-print XML string to Writer with DOCTYPE control
176
 * @param xmlString - XML string to format
177
 * @param writer - Writer for output
178
 * @param allowDocTypeDeclaration - Whether to allow DOCTYPE declarations
179
 */
180
static void serialize(String xmlString, Writer writer, boolean allowDocTypeDeclaration)
181
```
182

183
#### SAXParser Factory Methods
184

185
```groovy { .api }
186
/**
187
 * Create SAXParser with schema validation
188
 * @param schemaLanguage - Schema language (e.g., XMLConstants.W3C_XML_SCHEMA_NS_URI)
189
 * @param schemas - Schema sources for validation
190
 * @return Configured SAXParser
191
 */
192
static SAXParser newSAXParser(String schemaLanguage, Source... schemas)
193

194
/**
195
 * Create SAXParser with full configuration control
196
 * @param schemaLanguage - Schema language
197
 * @param namespaceAware - Enable namespace processing
198
 * @param validating - Enable DTD validation
199
 * @param schemas - Schema sources for validation
200
 * @return Configured SAXParser
201
 */
202
static SAXParser newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, Source... schemas)
203

204
/**
205
 * Create SAXParser with complete configuration
206
 * @param schemaLanguage - Schema language
207
 * @param namespaceAware - Enable namespace processing
208
 * @param validating - Enable DTD validation
209
 * @param allowDoctypeDecl - Allow DOCTYPE declarations
210
 * @param schemas - Schema sources for validation
211
 * @return Configured SAXParser
212
 */
213
static SAXParser newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, boolean allowDoctypeDecl, Source... schemas)
214

215
/**
216
 * Create SAXParser with File-based schema
217
 * @param schemaLanguage - Schema language
218
 * @param schema - Schema file
219
 * @return Configured SAXParser
220
 */
221
static SAXParser newSAXParser(String schemaLanguage, File schema)
222

223
/**
224
 * Create SAXParser with File-based schema and configuration
225
 * @param schemaLanguage - Schema language
226
 * @param namespaceAware - Enable namespace processing
227
 * @param validating - Enable DTD validation
228
 * @param schema - Schema file
229
 * @return Configured SAXParser
230
 */
231
static SAXParser newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, File schema)
232

233
/**
234
 * Create SAXParser with URL-based schema
235
 * @param schemaLanguage - Schema language
236
 * @param schema - Schema URL
237
 * @return Configured SAXParser
238
 */
239
static SAXParser newSAXParser(String schemaLanguage, URL schema)
240

241
/**
242
 * Create SAXParser with URL-based schema and configuration
243
 * @param schemaLanguage - Schema language
244
 * @param namespaceAware - Enable namespace processing
245
 * @param validating - Enable DTD validation
246
 * @param schema - Schema URL
247
 * @return Configured SAXParser
248
 */
249
static SAXParser newSAXParser(String schemaLanguage, boolean namespaceAware, boolean validating, URL schema)
250
```
251

252
#### XML Escaping and Character Handling
253

254
```groovy { .api }
255
/**
256
 * Escape special XML characters in string
257
 * @param text - Text to escape
258
 * @return XML-escaped string
259
 */
260
static String escapeXml(String text)
261

262
/**
263
 * Escape control characters in string
264
 * @param text - Text to escape
265
 * @return String with control characters escaped
266
 */
267
static String escapeControlCharacters(String text)
268
```
269

270
#### Feature Configuration Utilities
271

272
```groovy { .api }
273
/**
274
 * Safely set feature on TransformerFactory (ignores exceptions)
275
 * @param factory - TransformerFactory to configure
276
 * @param feature - Feature name
277
 * @param value - Feature value
278
 */
279
static void setFeatureQuietly(TransformerFactory factory, String feature, boolean value)
280

281
/**
282
 * Safely set feature on DocumentBuilderFactory (ignores exceptions)
283
 * @param factory - DocumentBuilderFactory to configure
284
 * @param feature - Feature name
285
 * @param value - Feature value
286
 */
287
static void setFeatureQuietly(DocumentBuilderFactory factory, String feature, boolean value)
288

289
/**
290
 * Safely set feature on SAXParserFactory (ignores exceptions)
291
 * @param factory - SAXParserFactory to configure
292
 * @param feature - Feature name
293
 * @param value - Feature value
294
 */
295
static void setFeatureQuietly(SAXParserFactory factory, String feature, boolean value)
296
```
297

298
**Usage Examples:**
299

300
```groovy
301
import groovy.xml.*
302
import javax.xml.XMLConstants
303
import javax.xml.transform.stream.StreamSource
304
import org.w3c.dom.Element
305

306
// Serialization examples
307
def parser = new XmlParser()
308
def node = parser.parseText('''
309
    <library>
310
        <book id="1">
311
            <title>Groovy Guide</title>
312
            <author>Expert</author>
313
        </book>
314
    </library>
315
''')
316

317
// Serialize Node to pretty-printed string
318
String prettyXml = XmlUtil.serialize(node)
319
println prettyXml
320

321
// Serialize to file
322
new File("output.xml").withWriter { writer ->
323
    XmlUtil.serialize(node, writer)
324
}
325

326
// Serialize to OutputStream with encoding
327
new FileOutputStream("output.xml").withStream { stream ->
328
    XmlUtil.serialize(node, stream)
329
}
330

331
// Serialize GPathResult
332
def slurper = new XmlSlurper()
333
def gpath = slurper.parseText('<data><item>test</item></data>')
334
String gPathXml = XmlUtil.serialize(gpath)
335
println gPathXml
336

337
// Pretty-print existing XML string
338
String uglyXml = '<root><child>text</child></root>'
339
String formatted = XmlUtil.serialize(uglyXml)
340
println formatted
341

342
// DOM serialization
343
def builder = DOMBuilder.newInstance()
344
def doc = builder.catalog { item("Sample") }
345
Element rootElement = doc.documentElement
346
String domXml = XmlUtil.serialize(rootElement)
347
println domXml
348

349
// Schema validation with SAXParser
350
def schemaFile = new File("schema.xsd")
351
def parser = XmlUtil.newSAXParser(
352
    XMLConstants.W3C_XML_SCHEMA_NS_URI,
353
    true,    // namespace aware
354
    true,    // validating
355
    schemaFile
356
)
357

358
// Multiple schema sources
359
def schema1 = new StreamSource(new File("schema1.xsd"))
360
def schema2 = new StreamSource(new File("schema2.xsd"))
361
def validatingParser = XmlUtil.newSAXParser(
362
    XMLConstants.W3C_XML_SCHEMA_NS_URI,
363
    schema1, schema2
364
)
365

366
// XML escaping
367
String unsafe = '<script>alert("hack")</script> & "quotes"'
368
String safe = XmlUtil.escapeXml(unsafe)
369
println safe  // &lt;script&gt;alert(&quot;hack&quot;)&lt;/script&gt; &amp; &quot;quotes&quot;
370

371
// Control character escaping
372
String withControlChars = "Text\u0001with\u0002control\u0003chars"
373
String escaped = XmlUtil.escapeControlCharacters(withControlChars)
374
println escaped
375

376
// Feature configuration (safe)
377
import javax.xml.parsers.DocumentBuilderFactory
378
import javax.xml.transform.TransformerFactory
379

380
def docFactory = DocumentBuilderFactory.newInstance()
381
XmlUtil.setFeatureQuietly(docFactory, XMLConstants.FEATURE_SECURE_PROCESSING, true)
382
XmlUtil.setFeatureQuietly(docFactory, "http://apache.org/xml/features/disallow-doctype-decl", true)
383

384
def transformerFactory = TransformerFactory.newInstance()
385
XmlUtil.setFeatureQuietly(transformerFactory, XMLConstants.FEATURE_SECURE_PROCESSING, true)
386

387
// Serialize with DOCTYPE control
388
String xmlWithDoctype = '''<?xml version="1.0"?>
389
<!DOCTYPE root SYSTEM "test.dtd">
390
<root><item>data</item></root>'''
391

392
// Serialize without allowing DOCTYPE
393
String safeXml = XmlUtil.serialize(xmlWithDoctype, false)  // DOCTYPE removed
394
String unsafeXml = XmlUtil.serialize(xmlWithDoctype, true) // DOCTYPE preserved
395

396
// Working with Writable objects
397
def markupBuilder = new StreamingMarkupBuilder()
398
def writable = markupBuilder.bind {
399
    catalog {
400
        book(id: "1", "Sample Book")
401
    }
402
}
403

404
String writableXml = XmlUtil.serialize(writable)
405
println writableXml
406

407
// Batch processing with utilities
408
def xmlFiles = new File("xml-data").listFiles { it.name.endsWith(".xml") }
409
xmlFiles.each { file ->
410
    def content = file.text
411
    def formatted = XmlUtil.serialize(content)
412
    
413
    def outputFile = new File("formatted/${file.name}")
414
    outputFile.text = formatted
415
    
416
    println "Formatted: ${file.name}"
417
}
418
```
419

420
---
421

422
### XmlNodePrinter
423

424
Specialized printer for `groovy.util.Node` objects with extensive formatting control.
425

426
```groovy { .api }
427
/**
428
 * Default constructor writing to System.out
429
 */
430
XmlNodePrinter()
431

432
/**
433
 * Constructor with PrintWriter output
434
 * @param out - PrintWriter for output
435
 */
436
XmlNodePrinter(PrintWriter out)
437

438
/**
439
 * Constructor with custom indentation
440
 * @param out - PrintWriter for output
441
 * @param indent - Indentation string
442
 */
443
XmlNodePrinter(PrintWriter out, String indent)
444

445
/**
446
 * Constructor with indentation and quote style
447
 * @param out - PrintWriter for output
448
 * @param indent - Indentation string
449
 * @param quote - Quote character for attributes
450
 */
451
XmlNodePrinter(PrintWriter out, String indent, String quote)
452

453
/**
454
 * Constructor with IndentPrinter
455
 * @param out - IndentPrinter for formatted output
456
 */
457
XmlNodePrinter(IndentPrinter out)
458

459
/**
460
 * Constructor with IndentPrinter and quote style
461
 * @param out - IndentPrinter for formatted output
462
 * @param quote - Quote character for attributes
463
 */
464
XmlNodePrinter(IndentPrinter out, String quote)
465

466
/**
467
 * Print Node to configured output
468
 * @param node - Node to print
469
 */
470
void print(Node node)
471
```
472

473
#### Configuration Methods
474

475
```groovy { .api }
476
/**
477
 * Control namespace awareness in output
478
 * @param namespaceAware - true for namespace-aware printing
479
 */
480
void setNamespaceAware(boolean namespaceAware)
481
boolean isNamespaceAware()
482

483
/**
484
 * Control whitespace preservation
485
 * @param preserveWhitespace - true to preserve whitespace
486
 */
487
void setPreserveWhitespace(boolean preserveWhitespace)
488
boolean isPreserveWhitespace()
489

490
/**
491
 * Set quote character for attributes
492
 * @param quote - Quote character (" or ')
493
 */
494
void setQuote(String quote)
495
String getQuote()
496

497
/**
498
 * Control empty element formatting
499
 * @param expandEmptyElements - true to expand empty elements
500
 */
501
void setExpandEmptyElements(boolean expandEmptyElements)
502
boolean isExpandEmptyElements()
503
```
504

505
**Usage Examples:**
506

507
```groovy
508
import groovy.xml.*
509
import groovy.util.IndentPrinter
510

511
// Create Node to print
512
def parser = new XmlParser()
513
def node = parser.parseText('''
514
    <library>
515
        <book id="1" title="Groovy Programming"/>
516
        <book id="2" title="XML Processing">
517
            <author>Jane Doe</author>
518
            <categories>
519
                <category>XML</category>
520
                <category>Programming</category>
521
            </categories>
522
        </book>
523
    </library>
524
''')
525

526
// Basic printing to System.out
527
def printer = new XmlNodePrinter()
528
printer.print(node)
529

530
// Print to StringWriter with custom formatting
531
def writer = new StringWriter()
532
def customPrinter = new XmlNodePrinter(new PrintWriter(writer), "    ", '"')
533
customPrinter.setNamespaceAware(true)
534
customPrinter.setExpandEmptyElements(true)
535
customPrinter.setPreserveWhitespace(false)
536
customPrinter.print(node)
537

538
println writer.toString()
539

540
// Print to file with IndentPrinter
541
new File("formatted-output.xml").withWriter { fileWriter ->
542
    def indentPrinter = new IndentPrinter(fileWriter, "  ")
543
    def filePrinter = new XmlNodePrinter(indentPrinter, "'")
544
    filePrinter.print(node)
545
}
546

547
// Configuration examples
548
printer.setQuote("'")           // Use single quotes
549
printer.setExpandEmptyElements(true)  // <empty></empty> instead of <empty/>
550
printer.setNamespaceAware(true) // Handle namespaces properly
551
printer.setPreserveWhitespace(true)   // Keep original whitespace
552
```
553

554
---
555

556
### FactorySupport
557

558
Utility methods for creating properly configured XML factory instances with security settings.
559

560
```groovy { .api }
561
/**
562
 * Create secure DocumentBuilderFactory
563
 * @return Configured DocumentBuilderFactory
564
 */
565
static DocumentBuilderFactory createDocumentBuilderFactory()
566

567
/**
568
 * Create secure SAXParserFactory
569
 * @return Configured SAXParserFactory
570
 */
571
static SAXParserFactory createSaxParserFactory()
572
```
573

574
**Usage Examples:**
575

576
```groovy
577
import groovy.xml.FactorySupport
578

579
// Create secure factories
580
def docBuilderFactory = FactorySupport.createDocumentBuilderFactory()
581
def saxParserFactory = FactorySupport.createSaxParserFactory()
582

583
// Use factories for secure parsing
584
def docBuilder = docBuilderFactory.newDocumentBuilder()
585
def saxParser = saxParserFactory.newSAXParser()
586

587
// These factories are preconfigured with security features
588
def doc = docBuilder.parse(new File("input.xml"))
589
```