0
# XML Parser and Document Processing
1

2
Advanced XML parsing capabilities with validation, entity resolution, and DOM-like tree processing. The XmlParser class wraps standard JAXP parsers with convenient error handling and provides a mini DOM-like document tree for configuration processing.
3

4
## Capabilities
5

6
### XmlParser Class
7

8
XML parser wrapper that provides validation, entity resolution, and document tree processing.
9

10
```java { .api }
11
/**
12
 * XML Parser wrapper with convenient error and entity handlers
13
 */
14
class XmlParser {
15
    /**
16
     * Construct XmlParser with default validation settings
17
     */
18
    XmlParser();
19
    
20
    /**
21
     * Construct XmlParser with specified validation setting
22
     * @param validating true to enable validation, false to disable
23
     */
24
    XmlParser(boolean validating);
25
}
26
```
27

28
### Parser Configuration
29

30
Configure parser behavior and validation settings.
31

32
```java { .api }
33
/**
34
 * Set validation mode
35
 * @param validating true to enable validation
36
 */
37
void setValidating(boolean validating);
38

39
/**
40
 * Get current validation mode
41
 * @return true if validation is enabled
42
 */
43
boolean isValidating();
44

45
/**
46
 * Get underlying SAX parser
47
 * @return SAX parser instance
48
 */
49
SAXParser getSAXParser();
50
```
51

52
### XML Catalog Support
53

54
Add XML catalogs for entity resolution.
55

56
```java { .api }
57
/**
58
 * Add XML catalog for entity resolution
59
 * @param catalogXml URI to catalog XML file
60
 */
61
void addCatalog(URI catalogXml);
62

63
/**
64
 * Add catalog with base class location
65
 * @param catalogXml URI to catalog XML file
66
 * @param baseClassLocation base class for relative resolution
67
 */
68
void addCatalog(URI catalogXml, Class<?> baseClassLocation);
69
```
70

71
### XPath Support
72

73
Set simple XPath expressions for selective parsing.
74

75
```java { .api }
76
/**
77
 * Set simple XPath for partial tree selection
78
 * @param xpath XPath expression
79
 */
80
void setXpath(String xpath);
81

82
/**
83
 * Get current XPath expression
84
 * @return XPath string or null
85
 */
86
String getXpath();
87
```
88

89
### Content Handling
90

91
Add custom content handlers for specific XML elements.
92

93
```java { .api }
94
/**
95
 * Add content handler for specific tag
96
 * @param trigger tag name to trigger handler
97
 * @param observer content handler to invoke
98
 */
99
void addContentHandler(String trigger, ContentHandler observer);
100
```
101

102
### Document Parsing
103

104
Parse XML documents from various sources.
105

106
```java { .api }
107
/**
108
 * Parse XML from input source
109
 * @param source SAX input source
110
 * @return root node of parsed document
111
 * @throws IOException if I/O error occurs
112
 * @throws SAXException if XML parsing error occurs
113
 */
114
Node parse(InputSource source) throws IOException, SAXException;
115

116
/**
117
 * Parse XML from URL string
118
 * @param url URL string to XML document
119
 * @return root node of parsed document
120
 * @throws IOException if I/O error occurs
121
 * @throws SAXException if XML parsing error occurs
122
 */
123
Node parse(String url) throws IOException, SAXException;
124

125
/**
126
 * Parse XML from file
127
 * @param file file containing XML document
128
 * @return root node of parsed document
129
 * @throws IOException if I/O error occurs
130
 * @throws SAXException if XML parsing error occurs
131
 */
132
Node parse(File file) throws IOException, SAXException;
133

134
/**
135
 * Parse XML from input stream
136
 * @param in input stream containing XML document
137
 * @return root node of parsed document
138
 * @throws IOException if I/O error occurs
139
 * @throws SAXException if XML parsing error occurs
140
 */
141
Node parse(InputStream in) throws IOException, SAXException;
142
```
143

144
### Document Metadata
145

146
Get metadata about parsed documents.
147

148
```java { .api }
149
/**
150
 * Get DTD identifier from parsed document
151
 * @return DTD identifier string or null
152
 */
153
String getDTD();
154
```
155

156
## Document Tree API
157

158
### XmlParser.Node
159

160
Represents XML elements with attributes and content, providing DOM-like access to the document tree.
161

162
```java { .api }
163
/**
164
 * XML element node with attributes and content
165
 */
166
static class Node {
167
    /**
168
     * Get parent node
169
     * @return parent node or null for root
170
     */
171
    Node getParent();
172
    
173
    /**
174
     * Get element tag name
175
     * @return tag name
176
     */
177
    String getTag();
178
    
179
    /**
180
     * Get XPath-like path to this node
181
     * @return path string
182
     */
183
    String getPath();
184
}
185
```
186

187
### Attribute Access
188

189
Access and query element attributes.
190

191
```java { .api }
192
/**
193
 * Get all attributes
194
 * @return array of attributes
195
 */
196
Attribute[] getAttributes();
197

198
/**
199
 * Get attribute value by name
200
 * @param name attribute name
201
 * @return attribute value or null if not found
202
 */
203
String getAttribute(String name);
204

205
/**
206
 * Get attribute value with default
207
 * @param name attribute name
208
 * @param dft default value if attribute not found
209
 * @return attribute value or default
210
 */
211
String getAttribute(String name, String dft);
212
```
213

214
### Child Node Access
215

216
Navigate and access child nodes.
217

218
```java { .api }
219
/**
220
 * Get first child node with specified tag
221
 * @param tag tag name to find
222
 * @return first matching child node or null
223
 */
224
Node get(String tag);
225

226
/**
227
 * Get child node as string content
228
 * @param tag child tag name
229
 * @param tags include tag names in output
230
 * @param trim trim whitespace
231
 * @return string content
232
 */
233
String getString(String tag, boolean tags, boolean trim);
234

235
/**
236
 * Iterate over child nodes with specified tag
237
 * @param tag tag name to iterate
238
 * @return iterator over matching child nodes
239
 */
240
Iterator<Node> iterator(String tag);
241
```
242

243
### List Operations
244

245
Node implements List interface for child access.
246

247
```java { .api }
248
/**
249
 * Get number of child nodes
250
 * @return child count
251
 */
252
int size();
253

254
/**
255
 * Get child by index
256
 * @param i child index
257
 * @return child object (Node or String)
258
 */
259
Object get(int i);
260

261
/**
262
 * Add child at index
263
 * @param i index position
264
 * @param obj child object to add
265
 */
266
void add(int i, Object obj);
267

268
/**
269
 * Remove all children
270
 */
271
void clear();
272
```
273

274
### String Conversion
275

276
Convert nodes to string representation.
277

278
```java { .api }
279
/**
280
 * Convert to string representation
281
 * @param tag include tag names in output
282
 * @return string representation
283
 */
284
String toString(boolean tag);
285
```
286

287
### XmlParser.Attribute
288

289
Represents XML attributes with name and value.
290

291
```java { .api }
292
/**
293
 * XML attribute with name and value
294
 */
295
static class Attribute {
296
    /**
297
     * Get attribute name
298
     * @return attribute name
299
     */
300
    String getName();
301
    
302
    /**
303
     * Get attribute value
304
     * @return attribute value
305
     */
306
    String getValue();
307
}
308
```
309

310
## Usage Examples
311

312
### Basic Parsing
313

314
```java
315
import org.eclipse.jetty.xml.XmlParser;
316
import java.io.File;
317

318
// Create parser with validation
319
XmlParser parser = new XmlParser(true);
320

321
// Parse XML file
322
XmlParser.Node root = parser.parse(new File("config.xml"));
323

324
// Access root element
325
String rootTag = root.getTag();
326
String classAttr = root.getAttribute("class");
327
```
328

329
### Navigating Document Tree
330

331
```java
332
// Get child nodes
333
XmlParser.Node childNode = root.get("Set");
334
String nameAttr = childNode.getAttribute("name");
335

336
// Iterate over all children with specific tag
337
Iterator<XmlParser.Node> setNodes = root.iterator("Set");
338
while (setNodes.hasNext()) {
339
    XmlParser.Node setNode = setNodes.next();
340
    String name = setNode.getAttribute("name");
341
    // Process set node...
342
}
343
```
344

345
### Using XML Catalogs
346

347
```java
348
import java.net.URI;
349

350
// Add catalog for entity resolution
351
XmlParser parser = new XmlParser();
352
parser.addCatalog(URI.create("file:///path/to/catalog.xml"));
353

354
// Parse with entity resolution
355
XmlParser.Node root = parser.parse("config-with-entities.xml");
356
```
357

358
### Validation and Error Handling
359

360
```java
361
try {
362
    XmlParser parser = new XmlParser(true); // Enable validation
363
    XmlParser.Node root = parser.parse("config.xml");
364
    
365
    // Get DTD information
366
    String dtd = parser.getDTD();
367
    
368
} catch (SAXException e) {
369
    // Handle XML parsing errors
370
    System.err.println("XML parsing error: " + e.getMessage());
371
} catch (IOException e) {
372
    // Handle I/O errors
373
    System.err.println("I/O error: " + e.getMessage());
374
}
375
```
376

377
### XPath Filtering
378

379
```java
380
// Parse only specific parts of document
381
XmlParser parser = new XmlParser();
382
parser.setXpath("/Configure/Set[@name='port']");
383

384
XmlParser.Node root = parser.parse("large-config.xml");
385
// Only port setting nodes will be in the tree
386
```
387

388
### Custom Content Handlers
389

390
```java
391
import org.xml.sax.ContentHandler;
392
import org.xml.sax.helpers.DefaultHandler;
393

394
// Add custom handler for specific elements
395
ContentHandler customHandler = new DefaultHandler() {
396
    @Override
397
    public void startElement(String uri, String localName, 
398
                           String qName, Attributes attributes) {
399
        System.out.println("Processing custom element: " + qName);
400
    }
401
};
402

403
XmlParser parser = new XmlParser();
404
parser.addContentHandler("CustomElement", customHandler);
405

406
XmlParser.Node root = parser.parse("config-with-custom.xml");
407
```
408

409
### Accessing Attributes and Content
410

411
```java
412
XmlParser.Node configNode = root;
413

414
// Get all attributes
415
XmlParser.Attribute[] attributes = configNode.getAttributes();
416
for (XmlParser.Attribute attr : attributes) {
417
    String name = attr.getName();
418
    String value = attr.getValue();
419
    System.out.println(name + "=" + value);
420
}
421

422
// Get text content
423
String content = configNode.getString("Property", false, true);
424

425
// Convert to string with tags
426
String xmlString = configNode.toString(true);
427
```