0
# DOM4J Core API
1
2
The core DOM4J API defines the fundamental interfaces and classes for working with XML documents. This section covers the Node hierarchy, Document interface, Element interface, and Attribute interface that form the foundation of DOM4J's tree-based XML processing model.
3
4
## Node Interface
5
6
The Node interface is the root of the DOM4J node hierarchy and defines polymorphic behavior for all node types in the XML tree.
7
8
### Package and Import
9
```java { .api }
10
import org.dom4j.Node;
11
```
12
13
### Node Type Constants
14
```java { .api }
15
public interface Node {
16
short ANY_NODE = 0;
17
short ELEMENT_NODE = 1;
18
short ATTRIBUTE_NODE = 2;
19
short TEXT_NODE = 3;
20
short CDATA_SECTION_NODE = 4;
21
short ENTITY_REFERENCE_NODE = 5;
22
short PROCESSING_INSTRUCTION_NODE = 7;
23
short COMMENT_NODE = 8;
24
short DOCUMENT_NODE = 9;
25
short DOCUMENT_TYPE_NODE = 10;
26
short NAMESPACE_NODE = 13;
27
short UNKNOWN_NODE = 14;
28
short MAX_NODE_TYPE = 14;
29
}
30
```
31
32
### Core Node Methods
33
```java { .api }
34
public interface Node extends Cloneable {
35
// Parent and document relationships
36
boolean supportsParent();
37
Element getParent();
38
void setParent(Element parent);
39
Document getDocument();
40
void setDocument(Document document);
41
42
// Node properties
43
boolean isReadOnly();
44
boolean hasContent();
45
String getName();
46
void setName(String name);
47
String getText();
48
void setText(String text);
49
String getStringValue();
50
51
// Path and identification
52
String getPath();
53
String getPath(Element context);
54
String getUniquePath();
55
String getUniquePath(Element context);
56
57
// Serialization
58
String asXML();
59
void write(Writer writer) throws IOException;
60
61
// Type information
62
short getNodeType();
63
String getNodeTypeName();
64
65
// Tree manipulation
66
Node detach();
67
68
// XPath support
69
List<Node> selectNodes(String xpathExpression);
70
Object selectObject(String xpathExpression);
71
Node selectSingleNode(String xpathExpression);
72
String valueOf(String xpathExpression);
73
Number numberValueOf(String xpathExpression);
74
boolean matches(String xpathExpression);
75
XPath createXPath(String xpathExpression) throws InvalidXPathException;
76
Node asXPathResult(Element parent);
77
78
// Visitor pattern
79
void accept(Visitor visitor);
80
81
// Object support
82
Object clone();
83
}
84
```
85
86
### Using Node Interface
87
```java { .api }
88
// Check node type
89
Node node = element.selectSingleNode("child");
90
if (node.getNodeType() == Node.ELEMENT_NODE) {
91
Element childElement = (Element) node;
92
// Process as element
93
}
94
95
// Get node path for debugging
96
String path = node.getPath(); // Returns XPath-like path
97
String uniquePath = node.getUniquePath(); // Returns unique path with indices
98
99
// XPath operations on any node
100
List<Node> matches = node.selectNodes(".//text()");
101
String value = node.valueOf("@attribute");
102
boolean hasMatch = node.matches("self::element[@attr]");
103
104
// Visitor pattern for type-safe processing
105
node.accept(new VisitorSupport() {
106
public void visit(Element element) {
107
System.out.println("Found element: " + element.getName());
108
}
109
110
public void visit(Text text) {
111
System.out.println("Found text: " + text.getText());
112
}
113
});
114
```
115
116
## Branch Interface
117
118
Branch defines common behavior for nodes that can contain child nodes (Elements and Documents).
119
120
### Package and Import
121
```java { .api }
122
import org.dom4j.Branch;
123
```
124
125
### Branch Interface Methods
126
```java { .api }
127
public interface Branch extends Node {
128
// Node access
129
Node node(int index) throws IndexOutOfBoundsException;
130
int indexOf(Node node);
131
int nodeCount();
132
Element elementByID(String elementID);
133
134
// Content management
135
List<Node> content();
136
Iterator<Node> nodeIterator();
137
void setContent(List<Node> content);
138
void appendContent(Branch branch);
139
void clearContent();
140
141
// Processing instructions
142
List<ProcessingInstruction> processingInstructions();
143
List<ProcessingInstruction> processingInstructions(String target);
144
ProcessingInstruction processingInstruction(String target);
145
void setProcessingInstructions(List<ProcessingInstruction> listOfPIs);
146
boolean removeProcessingInstruction(String target);
147
148
// Element creation
149
Element addElement(String name);
150
Element addElement(QName qname);
151
Element addElement(String qualifiedName, String namespaceURI);
152
153
// Content addition
154
void add(Node node);
155
void add(Comment comment);
156
void add(Element element);
157
void add(ProcessingInstruction pi);
158
159
// Content removal
160
boolean remove(Node node);
161
boolean remove(Comment comment);
162
boolean remove(Element element);
163
boolean remove(ProcessingInstruction pi);
164
165
// Normalization
166
void normalize();
167
}
168
```
169
170
### Using Branch Interface
171
```java { .api }
172
// Work with any Branch (Document or Element)
173
Branch branch = document.getRootElement();
174
175
// Add various node types
176
branch.add(DocumentHelper.createComment("A comment"));
177
branch.add(DocumentHelper.createText("Some text"));
178
Element newChild = branch.addElement("child");
179
180
// Iterate through content
181
for (Iterator<Node> iter = branch.nodeIterator(); iter.hasNext();) {
182
Node node = iter.next();
183
processNode(node);
184
}
185
186
// Content management
187
List<Node> content = branch.content();
188
branch.clearContent();
189
branch.appendContent(otherBranch);
190
191
// Processing instructions
192
branch.add(DocumentHelper.createProcessingInstruction("xml-stylesheet",
193
"type=\"text/xsl\" href=\"style.xsl\""));
194
List<ProcessingInstruction> pis = branch.processingInstructions();
195
```
196
197
## Document Interface
198
199
The Document interface represents an XML document and extends Branch to include document-specific functionality.
200
201
### Package and Import
202
```java { .api }
203
import org.dom4j.Document;
204
```
205
206
### Document Interface Methods
207
```java { .api }
208
public interface Document extends Branch {
209
// Root element management
210
Element getRootElement();
211
void setRootElement(Element rootElement);
212
213
// Document-level content
214
Document addComment(String comment);
215
Document addProcessingInstruction(String target, String text);
216
Document addProcessingInstruction(String target, Map<String, String> data);
217
Document addDocType(String name, String publicId, String systemId);
218
219
// Document type
220
DocumentType getDocType();
221
void setDocType(DocumentType docType);
222
223
// Entity resolution
224
EntityResolver getEntityResolver();
225
void setEntityResolver(EntityResolver entityResolver);
226
227
// Encoding
228
String getXMLEncoding();
229
void setXMLEncoding(String encoding);
230
}
231
```
232
233
### Using Document Interface
234
```java { .api }
235
// Create and configure document
236
Document document = DocumentHelper.createDocument();
237
document.setXMLEncoding("UTF-8");
238
239
// Add document-level processing instruction
240
document.addProcessingInstruction("xml-stylesheet",
241
Map.of("type", "text/xsl", "href", "transform.xsl"));
242
243
// Add DOCTYPE declaration
244
document.addDocType("html", "-//W3C//DTD XHTML 1.0 Strict//EN",
245
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd");
246
247
// Set root element
248
Element root = DocumentHelper.createElement("root");
249
document.setRootElement(root);
250
251
// Document information
252
String encoding = document.getXMLEncoding();
253
DocumentType docType = document.getDocType();
254
Element rootElement = document.getRootElement();
255
256
// Document-wide XPath queries
257
List<Element> allElements = document.selectNodes("//element");
258
Element specificElement = (Element) document.selectSingleNode("//element[@id='123']");
259
```
260
261
## Element Interface
262
263
The Element interface defines XML element behavior, including namespace support, attributes, child nodes, and text content.
264
265
### Package and Import
266
```java { .api }
267
import org.dom4j.Element;
268
import org.dom4j.QName;
269
import org.dom4j.Namespace;
270
import org.dom4j.Attribute;
271
```
272
273
### Namespace Methods
274
```java { .api }
275
public interface Element extends Branch {
276
// QName and namespace access
277
QName getQName();
278
void setQName(QName qname);
279
Namespace getNamespace();
280
QName getQName(String qualifiedName);
281
282
// Namespace resolution
283
Namespace getNamespaceForPrefix(String prefix);
284
Namespace getNamespaceForURI(String uri);
285
List<Namespace> getNamespacesForURI(String uri);
286
String getNamespacePrefix();
287
String getNamespaceURI();
288
String getQualifiedName();
289
290
// Namespace declarations
291
List<Namespace> additionalNamespaces();
292
List<Namespace> declaredNamespaces();
293
}
294
```
295
296
### Builder Methods
297
```java { .api }
298
public interface Element extends Branch {
299
// Content builders (return this Element for chaining)
300
Element addAttribute(String name, String value);
301
Element addAttribute(QName qName, String value);
302
Element addComment(String comment);
303
Element addCDATA(String cdata);
304
Element addEntity(String name, String text);
305
Element addNamespace(String prefix, String uri);
306
Element addProcessingInstruction(String target, String text);
307
Element addProcessingInstruction(String target, Map<String, String> data);
308
Element addText(String text);
309
}
310
```
311
312
### Attribute Methods
313
```java { .api }
314
public interface Element extends Branch {
315
// Attribute collections
316
List<Attribute> attributes();
317
void setAttributes(List<Attribute> attributes);
318
int attributeCount();
319
Iterator<Attribute> attributeIterator();
320
321
// Attribute access
322
Attribute attribute(int index);
323
Attribute attribute(String name);
324
Attribute attribute(QName qName);
325
326
// Attribute values
327
String attributeValue(String name);
328
String attributeValue(String name, String defaultValue);
329
String attributeValue(QName qName);
330
String attributeValue(QName qName, String defaultValue);
331
}
332
```
333
334
### Element Content Methods
335
```java { .api }
336
public interface Element extends Branch {
337
// Child element access
338
Element element(String name);
339
Element element(QName qName);
340
List<Element> elements();
341
List<Element> elements(String name);
342
List<Element> elements(QName qName);
343
344
// Element iteration
345
Iterator<Element> elementIterator();
346
Iterator<Element> elementIterator(String name);
347
Iterator<Element> elementIterator(QName qName);
348
349
// Element properties
350
boolean isRootElement();
351
boolean hasMixedContent();
352
boolean isTextOnly();
353
354
// Element operations
355
void appendAttributes(Element element);
356
Element createCopy();
357
Element createCopy(String name);
358
Element createCopy(QName qName);
359
360
// Element text content
361
String elementText(String name);
362
String elementText(QName qname);
363
String elementTextTrim(String name);
364
String elementTextTrim(QName qname);
365
366
// XPath result access
367
Node getXPathResult(int index);
368
}
369
```
370
371
### Using Element Interface
372
```java { .api }
373
// Create element with namespace
374
Namespace ns = Namespace.get("prefix", "http://example.com/ns");
375
Element root = DocumentHelper.createElement(QName.get("root", ns));
376
377
// Builder pattern for content creation
378
Element person = root.addElement("person")
379
.addAttribute("id", "123")
380
.addAttribute("active", "true")
381
.addText("John Doe");
382
383
// Add namespaced child element
384
Element address = person.addElement(QName.get("address", ns))
385
.addText("123 Main St");
386
387
// Attribute access
388
String id = person.attributeValue("id");
389
String active = person.attributeValue("active", "false"); // with default
390
Attribute idAttr = person.attribute("id");
391
392
// Child element access
393
Element addressElement = person.element("address");
394
List<Element> children = person.elements();
395
List<Element> addressElements = person.elements("address");
396
397
// Element navigation
398
for (Iterator<Element> iter = root.elementIterator(); iter.hasNext();) {
399
Element child = iter.next();
400
System.out.println("Child: " + child.getName());
401
}
402
403
// Element text content
404
String personName = person.getText();
405
String addressText = person.elementText("address");
406
String trimmedAddress = person.elementTextTrim("address");
407
408
// Element properties
409
boolean isRoot = root.isRootElement(); // true
410
boolean hasText = person.isTextOnly(); // true if only text content
411
boolean hasMixed = person.hasMixedContent(); // true if text and elements
412
413
// Namespace operations
414
String namespaceURI = root.getNamespaceURI();
415
String prefix = root.getNamespacePrefix();
416
Namespace elementNS = root.getNamespace();
417
List<Namespace> declared = root.declaredNamespaces();
418
419
// Element copying
420
Element copy = person.createCopy();
421
Element namedCopy = person.createCopy("employee");
422
```
423
424
## Attribute Interface
425
426
The Attribute interface represents XML attributes with name, optional namespace, and value.
427
428
### Package and Import
429
```java { .api }
430
import org.dom4j.Attribute;
431
import org.dom4j.QName;
432
import org.dom4j.Namespace;
433
```
434
435
### Attribute Interface Methods
436
```java { .api }
437
public interface Attribute extends Node {
438
// Name and namespace
439
QName getQName();
440
Namespace getNamespace();
441
void setNamespace(Namespace namespace);
442
String getNamespacePrefix();
443
String getNamespaceURI();
444
String getQualifiedName();
445
446
// Value access
447
String getValue();
448
void setValue(String value);
449
450
// Data storage
451
Object getData();
452
void setData(Object data);
453
}
454
```
455
456
### Using Attribute Interface
457
```java { .api }
458
// Create element with attributes
459
Element element = DocumentHelper.createElement("product");
460
element.addAttribute("id", "P123");
461
element.addAttribute("price", "29.99");
462
463
// Access attributes
464
Attribute idAttr = element.attribute("id");
465
String id = idAttr.getValue();
466
String name = idAttr.getName();
467
QName qname = idAttr.getQName();
468
469
// Namespaced attributes
470
Namespace ns = Namespace.get("app", "http://myapp.com/");
471
element.addAttribute(QName.get("status", ns), "active");
472
473
Attribute statusAttr = element.attribute(QName.get("status", ns));
474
String namespaceURI = statusAttr.getNamespaceURI(); // "http://myapp.com/"
475
String prefix = statusAttr.getNamespacePrefix(); // "app"
476
String qualifiedName = statusAttr.getQualifiedName(); // "app:status"
477
478
// Attribute manipulation
479
statusAttr.setValue("inactive");
480
idAttr.setData(Integer.valueOf(123)); // Store typed data
481
482
// Iterate through all attributes
483
for (Iterator<Attribute> iter = element.attributeIterator(); iter.hasNext();) {
484
Attribute attr = iter.next();
485
System.out.println(attr.getName() + " = " + attr.getValue());
486
}
487
488
// Get attribute list
489
List<Attribute> attributes = element.attributes();
490
int attributeCount = element.attributeCount();
491
```
492
493
## QName Class
494
495
QName represents qualified names with local name and namespace. It's an immutable value object used throughout DOM4J for namespace-aware operations.
496
497
### Package and Import
498
```java { .api }
499
import org.dom4j.QName;
500
import org.dom4j.Namespace;
501
import org.dom4j.DocumentFactory;
502
```
503
504
### QName Static Factory Methods
505
```java { .api }
506
public class QName {
507
// Factory methods
508
public static QName get(String name);
509
public static QName get(String name, Namespace namespace);
510
public static QName get(String name, String prefix, String uri);
511
public static QName get(String qualifiedName, String uri);
512
}
513
```
514
515
### QName Instance Methods
516
```java { .api }
517
public class QName {
518
// Name access
519
public String getName();
520
public String getQualifiedName();
521
522
// Namespace access
523
public Namespace getNamespace();
524
public String getNamespacePrefix();
525
public String getNamespaceURI();
526
527
// Factory access
528
public DocumentFactory getDocumentFactory();
529
public void setDocumentFactory(DocumentFactory documentFactory);
530
}
531
```
532
533
### Using QName
534
```java { .api }
535
// Create QNames
536
QName simpleName = QName.get("element");
537
QName namespacedName = QName.get("element",
538
Namespace.get("ns", "http://example.com/"));
539
QName withPrefix = QName.get("element", "ns", "http://example.com/");
540
QName fromQualified = QName.get("ns:element", "http://example.com/");
541
542
// Access QName properties
543
String localName = namespacedName.getName(); // "element"
544
String qualified = namespacedName.getQualifiedName(); // "ns:element"
545
String uri = namespacedName.getNamespaceURI(); // "http://example.com/"
546
String prefix = namespacedName.getNamespacePrefix(); // "ns"
547
Namespace namespace = namespacedName.getNamespace();
548
549
// Use QNames with elements and attributes
550
Element element = DocumentHelper.createElement(namespacedName);
551
element.addAttribute(QName.get("id"), "123");
552
553
// QName equality and hashing
554
QName qname1 = QName.get("element", "ns", "http://example.com/");
555
QName qname2 = QName.get("element", "ns", "http://example.com/");
556
boolean equal = qname1.equals(qname2); // true - QNames are cached
557
```
558
559
## Namespace Class
560
561
Namespace is a flyweight class representing XML namespaces that can be shared among nodes.
562
563
### Package and Import
564
```java { .api }
565
import org.dom4j.Namespace;
566
```
567
568
### Namespace Constants and Factory Methods
569
```java { .api }
570
public class Namespace {
571
// Predefined namespaces
572
public static final Namespace XML_NAMESPACE; // XML namespace
573
public static final Namespace NO_NAMESPACE; // Empty namespace
574
575
// Factory methods
576
public static Namespace get(String prefix, String uri);
577
public static Namespace get(String uri); // Creates with empty prefix
578
}
579
```
580
581
### Namespace Instance Methods
582
```java { .api }
583
public class Namespace {
584
// Property access
585
public String getPrefix();
586
public String getURI();
587
}
588
```
589
590
### Using Namespace
591
```java { .api }
592
// Create namespaces
593
Namespace defaultNS = Namespace.get("http://example.com/default");
594
Namespace prefixedNS = Namespace.get("app", "http://example.com/app");
595
596
// Predefined namespaces
597
Namespace xmlNS = Namespace.XML_NAMESPACE; // xml prefix
598
Namespace noNS = Namespace.NO_NAMESPACE; // no namespace
599
600
// Namespace properties
601
String prefix = prefixedNS.getPrefix(); // "app"
602
String uri = prefixedNS.getURI(); // "http://example.com/app"
603
604
// Use with elements
605
Element root = DocumentHelper.createElement(QName.get("root", defaultNS));
606
root.addNamespace("app", "http://example.com/app");
607
Element child = root.addElement(QName.get("child", prefixedNS));
608
609
// Namespace equality
610
Namespace ns1 = Namespace.get("app", "http://example.com/app");
611
Namespace ns2 = Namespace.get("app", "http://example.com/app");
612
boolean equal = ns1.equals(ns2); // true - namespaces are cached
613
614
// Common namespace operations
615
Element element = root.element(QName.get("child", prefixedNS));
616
Namespace childNS = element.getNamespace();
617
List<Namespace> declared = root.declaredNamespaces();
618
```
619
620
## Character Data Node Types
621
622
DOM4J provides several interfaces for text-based content in XML documents.
623
624
### CharacterData Interface
625
```java { .api }
626
import org.dom4j.CharacterData;
627
628
public interface CharacterData extends Node {
629
void appendText(String text);
630
}
631
```
632
633
### Text Interface
634
```java { .api }
635
import org.dom4j.Text;
636
637
// Text nodes represent XML text content
638
Text textNode = DocumentHelper.createText("Hello World");
639
element.add(textNode);
640
641
String content = textNode.getText();
642
textNode.setText("Modified content");
643
```
644
645
### CDATA Interface
646
```java { .api }
647
import org.dom4j.CDATA;
648
649
// CDATA sections preserve whitespace and special characters
650
CDATA cdata = DocumentHelper.createCDATA("<script>alert('test');</script>");
651
element.add(cdata);
652
653
String content = cdata.getText(); // Original content preserved
654
```
655
656
### Comment Interface
657
```java { .api }
658
import org.dom4j.Comment;
659
660
// XML comments
661
Comment comment = DocumentHelper.createComment("This is a comment");
662
element.add(comment);
663
664
String commentText = comment.getText();
665
comment.setText("Updated comment");
666
```
667
668
## Processing Instructions and Entities
669
670
### ProcessingInstruction Interface
671
```java { .api }
672
import org.dom4j.ProcessingInstruction;
673
674
public interface ProcessingInstruction extends Node {
675
String getTarget();
676
void setTarget(String target);
677
String getText();
678
String getValue(String name);
679
Map<String, String> getValues();
680
void setValue(String name, String value);
681
void setValues(Map<String, String> data);
682
boolean removeValue(String name);
683
}
684
```
685
686
### Using Processing Instructions
687
```java { .api }
688
// Create processing instructions
689
ProcessingInstruction xmlStylesheet = DocumentHelper.createProcessingInstruction(
690
"xml-stylesheet", "type=\"text/xsl\" href=\"style.xsl\"");
691
692
ProcessingInstruction appSpecific = DocumentHelper.createProcessingInstruction(
693
"myapp", Map.of("version", "1.0", "mode", "debug"));
694
695
// Access PI properties
696
String target = xmlStylesheet.getTarget(); // "xml-stylesheet"
697
String text = xmlStylesheet.getText(); // "type=\"text/xsl\" href=\"style.xsl\""
698
699
// Work with PI values
700
appSpecific.setValue("mode", "production");
701
String mode = appSpecific.getValue("mode"); // "production"
702
Map<String, String> allValues = appSpecific.getValues();
703
```
704
705
### Entity Interface
706
```java { .api }
707
import org.dom4j.Entity;
708
709
// Entity references
710
Entity entity = DocumentHelper.createEntity("copyright", "© 2023");
711
element.add(entity);
712
713
String name = entity.getName(); // "copyright"
714
String text = entity.getText(); // "© 2023"
715
```
716
717
The core DOM4J API provides a comprehensive and flexible foundation for XML document manipulation. The interfaces are designed for extensibility while the default implementations provide efficient and robust behavior for most use cases. The namespace-aware design and XPath integration make DOM4J particularly suitable for complex XML processing tasks.