XML-Dom4j
[TOC]
概述
Dom4j 是 Java 平台中广泛使用的开源 XML 解析框架,早期为支撑 JBoss、Hibernate 等主流中间件的配置文件解析而演进成熟。它底层融合了 DOM 内存树操作、SAX 事件流读取以及 Jaxen XPath 路径检索能力,并深度采用 Java 集合框架与面向接口的设计模式,使开发者既能以极低的代码量完成中小型 XML 文档的增删改查,也能在超大 XML 文件场景下按需切换为流式解析。
XML 解析方式对比
在 Java 生态中处理 XML 文档主要围绕三种解析模型展开,它们在内存占用、读写能力与编程复杂度上存在显著差异。
DOM
DOM(Document Object Model)是 W3C 制定的标准文档对象模型。解析器在读取 XML 时会将整个文档一次性加载到内存中,构建出一棵完整的节点树。
- 优势:节点树常驻内存,支持沿父子、兄弟方向任意双向遍历,并可直接对任意节点执行新增、修改或删除操作。
- 局限:内存消耗随 XML 文件体积线性增长,当解析数十兆甚至上百兆的 XML 文件时极易触发内存溢出(
OutOfMemoryError),且原生 W3C DOM 接口设计较为繁琐,存在大量强转操作。
SAX
SAX(Simple API for XML)是一种基于事件驱动的流式解析模型。解析器按从上到下的顺序逐行扫描 XML 文本,当遇到文档开头、元素起始标签、文本内容或元素结束标签时,实时触发对应的回调方法。
- 优势:无需在内存中保存整棵文档树,内存占用极低且恒定,适合处理超大体积的 XML 数据流。
- 局限:解析过程单向不可逆,无法随机回退访问已扫描过的节点,也不支持直接对原 XML 文档进行节点修改与写回,状态维护逻辑较为复杂。
Dom4j
Dom4j 在架构上对 DOM 与 SAX 进行了折中与整合,成为 Java 工程中处理 XML 的事实标准之一。
- 底层事件读取与内存树结合:默认通过
SAXReader调用底层 SAX 解析器读取 XML 流,并在回调过程中构建出轻量级的 Dom4j 内存对象树(Document),兼顾了读取效率与树形操作便利性。 - 面向接口与 Java 集合集成:所有节点均基于
Node、Branch、Element等接口定义,子节点与属性列表直接返回标准的java.util.List或Iterator,可直接配合增强for循环与集合流操作。 - 按需子树裁剪(
ElementHandler):针对超大 XML 文件,允许在SAXReader解析特定路径节点时注册回调并在处理完毕后立即调用detach()释放子树内存,避免全量建树导致的内存溢出。 - 原生集成 XPath 检索:内置对 XPath 表达式的支持,无需手写多层嵌套循环即可跨层级精准定位目标节点或属性。
核心工作流
Dom4j 处理 XML 数据的完整生命周期可分为三个核心阶段:
文档加载与构建阶段:通过
SAXReader从文件、字节流、字符流或 URL 中读取外部 XML 数据,或通过DocumentHelper在内存中直接创建空白文档,最终统一生成顶层Document实例。节点检索与树操作阶段:以
Document获取根元素Element为起点,通过层级遍历方法或XPath表达式检索目标Element、Attribute与Text节点,并在内存树上执行节点挂载、属性修改或子树剥离。格式化序列化阶段:配置
OutputFormat指定缩进字符、换行策略与字符编码,交由XMLWriter将内存中的Document树持久化写回磁盘文件或网络输出流。

Maven 依赖配置
在 Maven 项目中使用 Dom4j 时,除引入 dom4j 核心坐标外,若需要使用 XPath 语法检索节点,还需一并引入底层依赖的 jaxen 解析引擎,否则调用 XPath 相关方法时会抛出 NoClassDefFoundError 异常。
<!-- 1. 引入 Dom4j 核心解析库 -->
<dependency>
<groupId>org.dom4j</groupId>
<artifactId>dom4j</artifactId>
<version>2.1.4</version>
</dependency>
<!-- 2. 引入 Jaxen 引擎以支持 XPath 节点检索 -->
<dependency>
<groupId>jaxen</groupId>
<artifactId>jaxen</artifactId>
<version>1.2.0</version>
</dependency>示例: 解析 XML 文档
下面通过一个完整的学生信息读取示例,展示使用 SAXReader 加载 XML 文件并遍历提取节点属性与文本内容的标准流程。
首先准备待解析的 students.xml 配置文件:
<?xml version="1.0" encoding="UTF-8"?>
<!-- 1. 根节点 students 承载多个 student 子节点 -->
<students>
<!-- 2. student 节点通过 id 属性标识唯一编号,内嵌子标签存储学生信息 -->
<student id="101">
<name>张三</name>
<major>计算机科学与技术</major>
</student>
<student id="102">
<name>李四</name>
<major>软件工程</major>
</student>
</students>随后编写 StudentXmlDemo 类完成文档解析与节点遍历:
import org.dom4j.Document;
import org.dom4j.Element;
import org.dom4j.io.SAXReader;
import java.io.File;
import java.util.List;
// 1. 演示使用 Dom4j 读取并解析 XML 文档的基础流程
public class StudentXmlDemo {
public static void main(String[] args) throws Exception {
// 2. 创建 SAXReader 解析器并加载 XML 文件生成内存 Document 树
SAXReader reader = new SAXReader();
Document document = reader.read(new File("students.xml"));
// 3. 获取文档根元素并提取其下所有 student 子元素列表
Element rootElement = document.getRootElement();
List<Element> students = rootElement.elements("student");
// 4. 遍历每个 student 元素,读取节点属性与子元素文本
for (Element student : students) {
String id = student.attributeValue("id");
String name = student.elementText("name");
String major = student.elementText("major");
System.out.println(id + " - " + name + " - " + major);
}
}
}Node 节点继承体系
Dom4j 在 org.dom4j 包下采用面向接口的编程范式,将 XML 文档中的所有组成部分(文档根、元素标签、属性、文本、CDATA 块、注释、命名空间以及处理指令)全部抽象为统一的节点模型。通过严格区分“可包含子节点的分支容器”与“不可包含子节点的终端叶节点”,Dom4j 在编译期与运行期建立起清晰的节点树层次边界。
组合模式设计
Dom4j 的节点继承体系是经典组合设计模式(Composite Pattern)在 XML 树形结构上的工程实现。整棵 XML 文档树由以下三类抽象角色协同构成:
抽象构件(
Node):位于继承体系的最顶层,定义了所有 XML 节点共有的父子引用维护、节点类型标识、文本提取与 XPath 寻址契约。容器构件(
Branch):继承自Node,专门表示能够挂载子节点的分支节点。在 XML 规范中,只有整个文档(Document)与元素标签(Element)具备容纳子节点的能力。叶子构件(
Attribute、CharacterData等):直接或间接继承自Node但不实现Branch接口,表示处于文档树最末端的只读或值类型节点,内部不再维护子节点列表。

为了避免在遍历多态节点集合时频繁执行 instanceof 类型判断,Node 接口内置了整型的节点类型常量(如 ELEMENT_NODE、ATTRIBUTE_NODE、TEXT_NODE、COMMENT_NODE 等)。每个具体节点实现类都会在底层返回固定的类型编码与对应的类型名称,从而支持基于常量的快速分支派发。
Node
org.dom4j.Node 是 Dom4j 所有节点的根接口,封装了任意 XML 节点在文档树中的生存状态与通用访问行为。
在树形结构维护方面,Node 提供了向上追溯父节点与所属文档对象的能力。任意子节点均可通过自身持有的父引用定位到外层 Element 或顶层 Document;当需要将某个节点及其子树从原文档树中移除,或将其迁移挂载到另一棵文档树时,调用节点的剥离方法即可断开其与原父节点的双向引用。
在文本内容读取方面,Node 区分了“当前节点直接文本”与“子树聚合文本”两种语义:读取直接文本时仅拼接当前节点直属的文本块,而读取字符串值(StringValue)时则会递归深入所有后代元素节点,将整棵子树下的全部文本内容合并返回。
Branch
org.dom4j.Branch 继承自 Node,为分支容器节点扩充了子节点集合的增删改查契约。Branch 内部维护了一个有序的子节点列表,允许按索引下标随机访问任意类型的 Node 子节点,或通过迭代器顺序扫描其直属的所有子节点(涵盖子元素、内嵌文本块与注释节点)。
Branch 接口下仅有两个核心子接口:Document 与 Element。
Document
org.dom4j.Document 表示内存中整篇 XML 文档的顶层容器。一个合法的 Document 实例内部最多只能挂载一个根元素(Root Element),但允许在根元素之外同时持有 XML 文档声明、文档类型定义(DocumentType)、顶层注释(Comment)以及处理指令(ProcessingInstruction)。此外,Document 还负责记录当前 XML 文档的字符编码格式,供后续序列化写出时读取。
Element
org.dom4j.Element 表示 XML 文档中的具体标签元素,是日常开发中交互最密集的核心接口。Element 在结构上同时扮演双重容器角色:
- 作为
Branch子节点容器:其内部的内容列表(Content List)按文档出现顺序混合存储子元素(Element)、文本节点(Text)、CDATA块与注释节点(Comment)。 - 作为属性与命名空间宿主:
Element独立维护了一组属性列表(Attribute List)与命名空间声明,使属性数据的检索与修改不会干扰子节点内容列表的遍历顺序。
叶节点接口
凡是不实现 Branch 接口的 Node 子接口均属于叶节点,它们挂载在 Element 或 Document 之下,用于承载具体的键值属性、字符文本或元数据。
Attribute
org.dom4j.Attribute 表示附加在 Element 起始标签上的键值对属性。虽然 Attribute 同样继承自 Node,且其父节点引用指向所属的 Element 实例,但在 Dom4j 的底层存储设计中,Attribute 并不存放在 Element 的 Branch 子节点内容列表中,而是存放在独立的属性集合内。因此,对 Element 执行标准的 Branch 子节点遍历时不会扫描到 Attribute 节点,必须通过专门的属性访问接口进行读取。
CharacterData
org.dom4j.CharacterData 继承自 Node,是所有字符数据类叶节点的公共父接口,提供了统一的字符追加与文本操作契约。根据 XML 语法语义的不同,该接口进一步派生出三个具体子接口:
Text:表示元素标签内部包含的普通字符文本,序列化写出时会自动对<、>、&等特殊字符执行 XML 实体转义。CDATA:表示由<![CDATA[...]]>包裹的原始字符块,用于存放包含大量特殊符号的脚本或代码片段,解析与写出时均跳过转义处理。Comment:表示由<!--...-->包裹的 XML 注释信息。
节点工厂体系
Dom4j 的核心 API 全部定义为接口,开发者在业务代码中通常不直接通过 new 关键字实例化具体的实现类,而是依托工厂模式在底层透明创建位于 org.dom4j.tree 包下的默认实现类(如 DefaultDocument、DefaultElement、DefaultAttribute、DefaultText 等)。
DocumentFactory
org.dom4j.DocumentFactory 是 Dom4j 底层负责实例化各类 Node 对象的核心工厂类,内部采用单例模式提供全局默认实例。无论是由 SAXReader 解析外部文件建树,还是在内存中手动拼装节点,底层最终都会委托给 DocumentFactory 完成具体节点实现类的创建。
DocumentHelper
org.dom4j.DocumentHelper 是对 DocumentFactory 单例的外观(Facade)工具类封装。它将常用的创建空白文档、创建元素、创建属性、构建 XPath 表达式以及将 XML 格式字符串直接解析为 Document 树等操作全部暴露为静态方法,省去了显式获取 DocumentFactory 实例的样板代码。
示例: 多态遍历节点树
以下代码通过 DocumentHelper 将一段包含注释、子元素、属性与文本的 XML 字符串解析为内存树,并利用 Branch 与 Node 接口的多态特性递归打印所有分支与叶节点的类型信息。
import org.dom4j.Branch;
import org.dom4j.Document;
import org.dom4j.DocumentHelper;
import org.dom4j.Element;
import org.dom4j.Node;
// 1. 演示基于 Node 与 Branch 接口多态遍历 XML 内存节点树
public class NodePolymorphismDemo {
public static void main(String[] args) throws Exception {
// 2. 使用 DocumentHelper 将 XML 字符串直接解析为 Document 实例
String xml = "<library><!-- 馆藏图书 --><book id=\"B01\"><title>Java 编程</title></book></library>";
Document document = DocumentHelper.parseText(xml);
// 3. 获取根元素并作为 Branch 容器入口启动递归遍历
Element root = document.getRootElement();
inspectBranch(root);
}
// 4. 接收 Branch 分支接口,统一遍历其挂载的所有 Node 子节点
public static void inspectBranch(Branch branch) {
for (int i = 0; i < branch.nodeCount(); i++) {
Node child = branch.node(i);
System.out.println("节点类型: " + child.getNodeTypeName() + " | 节点名称: " + child.getName() + " | 文本内容: " + child.getText());
// 5. 若当前子节点仍属于 Branch 分支容器,则递归向下遍历其内部子树
if (child instanceof Branch) {
inspectBranch((Branch) child);
}
}
}
}运行上述程序后,控制台将依次输出 Comment(注释节点)、Element(book 与 title 元素节点)以及 Text(Java 编程 文本节点),而 book 元素上的 id="B01" 属性由于存储在独立的属性列表中,不会出现在 Branch 子节点遍历结果内。
API: Node
节点类型标识
final shortNode.ELEMENT_NODE:元素节点常量。常量值为1,用于标识Element类型的 XML 标签元素节点。final shortNode.ATTRIBUTE_NODE:属性节点常量。常量值为2,用于标识挂载在元素标签上的Attribute键值对属性节点。final shortNode.TEXT_NODE:文本节点常量。常量值为3,用于标识元素内部的普通Text字符文本节点。final shortNode.CDATA_SECTION_NODE:原生字符块常量。常量值为4,用于标识由<![CDATA[...]]>包裹的CDATA节点。final shortNode.COMMENT_NODE:注释节点常量。常量值为8,用于标识由<!--...-->包裹的Comment注释节点。final shortNode.DOCUMENT_NODE:文档节点常量。常量值为9,用于标识顶层Document文档容器节点。shortgetNodeType():(),节点类型编码获取。返回当前节点对应的short类型常量编码,适合在多态节点遍历时配合switch语句快速分发处理,避免频繁执行instanceof判断。StringgetNodeTypeName():(),节点类型名称获取。返回当前节点类型的可读字符串名称(如"Element"、"Attribute"、"Text"、"Comment"),常用于日志输出与节点树调试。
import org.dom4j.Document;
import org.dom4j.DocumentHelper;
import org.dom4j.Element;
import org.dom4j.Node;
// 1. 演示使用 Node 节点类型常量与类型查询方法进行多态分支派发
public class NodeTypeDemo {
public static void main(String[] args) throws Exception {
// 2. 解析包含注释、子元素与文本的 XML 字符串
String xml = "<root><!-- 配置说明 --><item>数据</item></root>";
Document document = DocumentHelper.parseText(xml);
Element root = document.getRootElement();
// 3. 遍历子节点并依据 getNodeType() 返回的常量值区分节点类型
for (int i = 0; i < root.nodeCount(); i++) {
Node node = root.node(i);
switch (node.getNodeType()) {
case Node.COMMENT_NODE:
System.out.println("匹配注释 [" + node.getNodeTypeName() + "]: " + node.getText());
break;
case Node.ELEMENT_NODE:
System.out.println("匹配元素 [" + node.getNodeTypeName() + "]: " + node.getName());
break;
default:
System.out.println("其他节点: " + node.getNodeTypeName());
}
}
}
}树结构操作
ElementgetParent():(),父元素获取。返回直接包含当前节点的外层Element父元素;若当前节点为根元素、文档对象、处于游离状态或实现类不支持父引用,则返回null。voidsetParent():(Element parent),父元素设置。为当前节点设置所属的父元素引用;该方法仅供 Dom4j 内部维护树形关联使用,业务代码应通过父容器的添加方法完成挂载。DocumentgetDocument():(),所属文档获取。返回当前节点隶属的顶层Document实例;若当前节点尚未挂载到任何文档中,则返回null。voidsetDocument():(Document document),所属文档设置。显式绑定当前节点所属的Document实例,通常由内部建树或文档根元素替换逻辑调用。Nodedetach():(),节点剥离。将当前节点及其整棵子树从原父节点或所属文档中移除并清空父引用,返回被剥离的当前节点自身,用于节点删除、跨树迁移或流式解析时的内存释放。Objectclone():(),节点深拷贝。创建并返回当前节点及其整棵子树的深拷贝副本,新副本处于无父节点的游离状态,可直接挂载至其他父元素而不违反单亲节点约束。booleanhasContent():(),子节点存在判定。当且仅当当前节点属于Branch(Element或Document)且内部至少包含一个子节点(如子元素或文本节点)时返回true,叶节点恒返回false。booleanisReadOnly():(),只读状态判定。判断当前节点是否为不可修改的只读节点(如部分享元模式节点实现),只读节点在尝试变更内容时会抛出UnsupportedOperationException。
注意事项:
- Dom4j 严格遵循单亲节点约束,将已挂载在某棵文档树中的节点直接添加到另一个父元素会抛出
IllegalAddException,必须先调用detach()剥离原父节点,或通过clone()生成游离副本后再执行挂载。supportsParent()为false的轻量级只读节点实现不维护父指针,对其调用getParent()始终返回null。
import org.dom4j.Document;
import org.dom4j.DocumentHelper;
import org.dom4j.Element;
import org.dom4j.Node;
// 1. 演示节点的父子追溯、剥离迁移与深拷贝克隆操作
public class NodeTreeDemo {
public static void main(String[] args) throws Exception {
// 2. 构建源文档与目标文档
Document sourceDoc = DocumentHelper.parseText("<source><item>订单数据</item></source>");
Document targetDoc = DocumentHelper.createDocument();
Element targetRoot = targetDoc.addElement("archive");
// 3. 获取源节点并向上追溯父元素、所属文档及内容状态
Node itemNode = sourceDoc.getRootElement().element("item");
System.out.println("原父节点: " + itemNode.getParent().getName());
System.out.println("所属文档根节点: " + itemNode.getDocument().getRootElement().getName());
System.out.println("包含子节点: " + itemNode.hasContent() + " | 只读: " + itemNode.isReadOnly());
// 4. 克隆独立副本并挂载至目标文档,原文档节点不受影响
Node clonedNode = (Node) itemNode.clone();
targetRoot.add(clonedNode);
// 5. 调用 detach() 断开原父节点引用,将其安全迁移至目标文档
itemNode.detach();
System.out.println("剥离后原父节点: " + itemNode.getParent());
targetRoot.add(itemNode);
System.out.println("目标文档结果: " + targetDoc.asXML());
}
}节点内容读写
StringgetName():(),节点名称获取。返回当前节点的本地名称(如元素的标签名或属性名);对于无名称的Text、CDATA与Comment等节点返回null。voidsetName():(String name),节点名称设置。修改当前节点的本地名称(如重命名元素标签);对不支持命名的节点类型调用时可能抛出UnsupportedOperationException。StringgetText():(),直接文本获取。返回当前节点的直接文本内容;对于Element仅拼接其直属的Text、CDATA与实体节点文本而不递归深入子元素,对于Attribute返回属性值。voidsetText():(String text),文本内容设置。设置当前节点的文本内容;在Element上调用时会先清空原有的所有直属文本与CDATA节点再写入新文本,但保留已挂载的子元素。StringgetStringValue():(),聚合字符串值获取。遵循 XPath 规范递归收集当前节点及所有后代子元素下的全部文本并拼接返回,适合提取含内联子标签的完整纯文本内容。StringasXML():(),XML 文本序列化。将当前节点及其整棵子树转换为未格式化缩进的 XML 字符串,常用于快速日志打印、调试查看或生成局部 XML 片段。voidwrite():(Writer writer),字符流直接写出。将当前节点的 XML 文本直接写入传入的Writer字符输出流(抛出IOException),不附加自定义排版缩进。
注意事项:
asXML()与write(Writer)仅执行默认的无缩进序列化输出;若需要控制文件头编码、自定义缩进空格或展开空标签,应使用XMLWriter配合OutputFormat完成写出。- 对于混合包含文本与内嵌标签的元素(如
<p>Hello <b>World</b></p>),getText()仅返回"Hello ",而getStringValue()会返回完整的"Hello World"。
import org.dom4j.Document;
import org.dom4j.DocumentHelper;
import org.dom4j.Node;
import java.io.StringWriter;
// 1. 演示 Node 的名称修改、直接文本与聚合文本区别及片段写出
public class NodeContentDemo {
public static void main(String[] args) throws Exception {
// 2. 解析包含嵌套子标签的混合文本 XML
String xml = "<article>前言<em>核心</em>结语</article>";
Document document = DocumentHelper.parseText(xml);
Node root = document.getRootElement();
// 3. 对比 getText() 直接文本与 getStringValue() 递归聚合文本的差异
System.out.println("直接文本: " + root.getText());
System.out.println("聚合文本: " + root.getStringValue());
// 4. 修改节点名称与文本内容,并序列化为 XML 字符串
root.setName("post");
root.setText("更新后的正文");
System.out.println("XML 文本: " + root.asXML());
// 5. 使用 write() 将当前节点直接写出至指定字符流
StringWriter writer = new StringWriter();
root.write(writer);
System.out.println("流写出结果: " + writer.toString());
}
}XPath 路径检索
selectNodes():XPath 节点集合检索。以当前节点为上下文评估 XPath 表达式,返回所有匹配的节点集合,并支持按第二个排序表达式进行排序与去重。
List<Node>:(String xpathExpression),常规节点列表检索。执行指定 XPath 表达式并按文档出现顺序返回所有命中的Node列表,无匹配时返回空列表。List<Node>:(String xpathExpression, String comparisonXPathExpression),排序节点列表检索。检索节点后依据comparisonXPathExpression的计算结果对列表升序排列,保留重复项。List<Node>:(String xpathExpression, String comparisonXPathExpression, boolean removeDuplicates),排序去重节点列表检索。在按比较表达式排序的基础上,当removeDuplicates为true时移除排序键值相同的重复节点。
NodeselectSingleNode():(String xpathExpression),XPath 单节点检索。评估 XPath 表达式并返回首个匹配的Node实例;若命中多个节点仅取第一个,无匹配时返回null。StringvalueOf():(String xpathExpression),XPath 字符串求值。评估 XPath 表达式并将结果直接转化为 XPath 字符串值返回,常用于一步提取目标子元素文本或属性值,无匹配时返回空字符串""。NumbernumberValueOf():(String xpathExpression),XPath 数值求值。评估 XPath 表达式并将结果转化为Number数值对象,适用于执行count()、sum()或提取数值型字段。booleanmatches():(String xpathExpression),XPath 模式匹配校验。判断当前节点是否符合指定的 XPath 匹配模式表达式,常用于条件断言与节点过滤。XPathcreateXPath():(String xpathExpression),预编译 XPath 构建。基于当前节点所属的DocumentFactory创建并编译一个可复用的XPath实例,用于后续高频查询或绑定命名空间映射。getPath():通用 XPath 路径生成。反向生成可定位到当前节点集合的 XPath 表达式(不含同级位置下标,如
/store/book)。String:(),绝对通用路径生成。返回从文档根节点出发指向当前节点类型的绝对 XPath 路径。String:(Element context),相对通用路径生成。返回以指定祖先元素context为起点指向当前节点类型的相对 XPath 路径。
getUniquePath():唯一 XPath 路径生成。反向生成能够精确锁定当前单一节点的 XPath 表达式;若同级存在同名兄弟节点,会自动附加位置下标(如
/store/book[2])。String:(),绝对唯一路径生成。返回从文档根节点出发、唯一标识当前节点的绝对 XPath 路径。String:(Element context),相对唯一路径生成。返回以指定祖先元素context为起点、唯一标识当前节点的相对 XPath 路径。
注意事项:
- 调用
selectNodes()、selectSingleNode()、valueOf()等所有 XPath 检索方法均依赖运行期类路径中的jaxen库,缺失该依赖将抛出NoClassDefFoundError。- Dom4j 1.x 版本中
selectNodes()返回原始类型List,自 Dom4j 2.x 起已泛型化为List<Node>。- 当 XML 文档声明了默认命名空间(
xmlns="...")时,直接通过Node上的无前缀快捷检索方法无法命中节点,必须改用createXPath()构建XPath实例并注入命名空间 URI 映射后再检索。
import org.dom4j.Document;
import org.dom4j.DocumentHelper;
import org.dom4j.Node;
import java.util.List;
// 1. 演示 Node 内置的 XPath 节点检索、标量求值与唯一路径反向生成
public class NodeXPathDemo {
public static void main(String[] args) throws Exception {
// 2. 构建包含多本图书节点的测试文档
String xml = "<store><book id=\"B2\"><price>90</price></book><book id=\"B1\"><price>45</price></book></store>";
Document document = DocumentHelper.parseText(xml);
// 3. 检索全部 book 节点并按 @id 属性排序,同时输出其唯一路径
List<Node> sortedBooks = document.selectNodes("/store/book", "@id");
for (Node book : sortedBooks) {
System.out.println("通用路径: " + book.getPath() + " | 唯一路径: " + book.getUniquePath());
}
// 4. 定位单个目标节点并校验是否满足指定 XPath 条件
Node firstBook = document.selectSingleNode("//book[@id='B1']");
System.out.println("匹配低价条件: " + firstBook.matches("book[price<50]"));
// 5. 直接通过 XPath 提取字符串值与数值计算结果
String minPriceText = document.valueOf("//book[@id='B1']/price");
Number totalCount = document.numberValueOf("count(//book)");
System.out.println("B1 价格: " + minPriceText + " | 图书总数: " + totalCount);
}
}API: Branch【待补充】
API: Document【待补充】
API: Element【待补充】
API: Attribute【待补充】
API: DocumentHelper【待补充】
SAXReader 文档解析
org.dom4j.io.SAXReader 是 Dom4j 用于从外部数据源读取 XML 文本并构建内存 Document 树的核心入口。它本身并不直接实现底层词法分析,而是基于 JAXP(Java API for XML Processing)规范封装了标准的 SAX XMLReader 解析器,将流式的 SAX 事件回调实时转化为 Dom4j 的内存节点树。
SAXContentHandler
在 SAXReader 解析文档的过程中,真正承担“事件转节点树”职责的核心桥梁是 org.dom4j.io.SAXContentHandler。该类继承自 SAX 标准库的 DefaultHandler,同时实现了 LexicalHandler 与 DTDHandler 接口,在底层串联起事件监听、压栈追踪与工厂建树三个环节:
初始化文档与元素栈:当底层 SAX 解析器触发文档开始事件时,
SAXContentHandler调用DocumentFactory创建顶层空白Document实例,并初始化一个内部元素栈(ElementStack)用于追踪当前解析所处的标签层级。起始标签入栈与挂载:每当扫描到元素的起始标签时,
SAXContentHandler提取标签名、命名空间与属性集合,通过DocumentFactory实例化对应的Element与Attribute对象,将其挂载到当前栈顶父元素下(若栈为空则设为Document的根元素),随后将该新元素压入ElementStack栈顶。字符数据与注释追加:扫描到标签内部的字符数据、
CDATA块或注释时,SAXContentHandler直接创建对应的叶节点并挂载到当前栈顶Element的内容列表中。结束标签出栈闭合:当扫描到元素的结束标签时,意味着当前元素的子树已构建完毕,
SAXContentHandler将栈顶Element弹出ElementStack,使后续同级节点的挂载目标回退至外层父节点。

输入源与编码识别
SAXReader 提供了多组重载的读取入口,支持从本地文件(File)、字节输入流(InputStream)、字符输入流(Reader)、网络资源定位符(URL)以及 SAX 原生 InputSource 中加载 XML 数据。
在选择输入源类型时,字符编码的识别优先级直接影响中文等多字节字符的解析准确性:
- 字节流与文件输入(推荐):传入
File或InputStream时,SAXReader会先读取 XML 文件头部的字节序标记(BOM)及<?xml version="1.0" encoding="..."?>声明,自动选用声明中指定的字符集解码字节流;若外部流未携带声明,也可预先在SAXReader上显式指定默认编码。 - 字符流输入(需谨慎):传入
FileReader或InputStreamReader时,字节到字符的解码过程已在外部Reader中提前发生,SAXReader无法再根据 XML 头部的encoding属性重新纠正字符集。若操作系统默认编码与 XML 文件实际编码不一致,极易产生乱码。
解析行为控制
XML 文档为了便于人工阅读,通常包含大量用于排版缩进的换行符、制表符与空格,同时底层 SAX 解析器在遇到字符缓冲区边界或实体引用时还可能将同一段连续文本拆分为多次回调。SAXReader 提供了多项开关用于在建树阶段优化节点结构。
空白文本剥离
在未开启优化的默认状态下,两个相邻元素标签之间的换行符与缩进空格会被 SAXContentHandler 视为有效字符数据,进而在父元素的 Branch 内容列表中生成大量仅包含空白字符的 Text 节点。开启空白文本剥离后,解析器会自动丢弃纯空白字符块,既降低了内存节点数量,也避免了按索引遍历子节点时误读到排版空白。
相邻文本合并
底层 SAX XMLReader 读取长文本块或处理夹杂在文本中的转义实体(如 &)时,会分多次触发字符回调事件,默认情况下每一次回调都会在父元素下生成一个独立的 Text 子节点。开启相邻文本合并后,SAXContentHandler 会在元素闭合前将连续相邻的多个 Text 节点合并为单个 Text 实例,保证文本节点的完整性。
注释忽略
在仅关注业务配置数据的场景中,XML 文档内的 <!-- ... --> 注释无需加载到内存树。开启注释忽略开关后,SAXContentHandler 会在词法回调阶段直接跳过所有注释事件,不再实例化 Comment 节点。
ElementHandler
当待解析的 XML 数据文件达到数百兆甚至数吉字节(GB)规模时,若任由 SAXReader 将全部节点保留在 Document 树中,必然导致 JVM 堆内存耗尽并抛出 OutOfMemoryError。为此,Dom4j 引入了 org.dom4j.ElementHandler 接口,允许按路径对特定子树实施“边解析、边消费、边卸载”的流式裁剪策略。
ElementHandler 围绕 ElementStack 的入栈与出栈生命周期定义了两个核心触发时机:
子树起始回调:当解析器刚扫描到目标路径(如
/orders/order)的起始标签并将其压入ElementStack时触发。此时当前Element仅包含标签自身的属性,其内部子元素尚未被解析。子树闭合回调:当解析器扫描到目标路径的结束标签、即将将其弹出
ElementStack时触发。此时该目标Element及其内部所有后代子节点均已完整构建,业务代码可通过传入的ElementPath上下文提取当前Element完成数据入库或业务计算,随后立即调用该元素的剥离方法将其从父节点中移除。
由于每个处理完毕的业务子树都在闭合瞬间断开了与外层父节点的引用,能够立即被垃圾回收器(GC)回收,内存中始终只驻留当前正在解析的单个子元素块,从而以恒定的极低内存开销完成超大 XML 文档的解析。
外部实体解析防护
默认创建的 SAXReader 在解析包含 DOCTYPE 声明的不可信 XML 输入时,存在 XML 外部实体注入(XXE)安全隐患,同时也可能因尝试联网下载远程 DTD 校验文件而导致离线服务器发生网络阻塞。
在生产环境中实例化 SAXReader 后,通常需要向底层封装的 SAX XMLReader 注入安全特征配置(Feature):通过禁用 DOCTYPE 声明,或关闭外部通用实体与外部参数实体的解析开关,并在无需校验的场景下关闭外部 DTD 加载,从而彻底阻断恶意读取服务器本地文件与远程请求挂起风险。
示例: 超大文档子树裁剪
以下代码展示了配置 SAXReader 的安全防护特征、开启空白剥离与文本合并,并针对 /orders/order 路径注册 ElementHandler 实现流式消费与内存即时卸载的完整过程。
import org.dom4j.Element;
import org.dom4j.ElementHandler;
import org.dom4j.ElementPath;
import org.dom4j.io.SAXReader;
import java.io.StringReader;
// 1. 演示配置 SAXReader 安全特征并结合 ElementHandler 按需裁剪子树
public class SaxStreamParseDemo {
public static void main(String[] args) throws Exception {
// 2. 创建 SAXReader 实例并开启空白剥离与相邻文本合并
SAXReader reader = new SAXReader();
reader.setStripWhitespaceText(true);
reader.setMergeAdjacentText(true);
// 3. 禁用外部实体与 DOCTYPE 声明,阻断外部实体注入风险
reader.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
reader.setFeature("http://xml.org/sax/features/external-general-entities", false);
// 4. 针对 /orders/order 路径注册处理器,在子树闭合时提取数据并立即剥离内存
reader.addHandler("/orders/order", new ElementHandler() {
@Override
public void onStart(ElementPath elementPath) {
}
@Override
public void onEnd(ElementPath elementPath) {
Element order = elementPath.getCurrent();
System.out.println("已处理订单编号: " + order.attributeValue("id"));
order.detach();
}
});
// 5. 执行流式读取,解析完成后根元素下不再残留已处理的 order 子节点
String xml = "<orders><order id=\"A1\"><item>键盘</item></order><order id=\"A2\"><item>鼠标</item></order></orders>";
reader.read(new StringReader(xml));
}
}API: SAXReader【待补充】
API: ElementHandler【待补充】
Element 节点树操作
在通过 SAXReader 或 DocumentHelper 获得内存 Document 实例后,对 XML 数据的读取、构建、插入、修改与删除均围绕 org.dom4j.Element 接口展开。理解 Element 底层的双列表存储模型、实时视图映射以及单亲节点约束,是安全高效地操作内存文档树的基础。
节点存储结构
Dom4j 默认的元素实现类(DefaultElement)在内部采用分离式的双列表结构来管理其挂载的数据:
- 子节点内容列表(Content List):继承自
Branch容器语义,按文档中的出现顺序混合存放直属的Element、Text、CDATA、Comment等子节点。 - 属性列表(Attribute List):独立存储当前标签上的所有
Attribute节点,与子节点内容列表物理隔离。
当开发者调用 Element 的子元素检索方法获取 List<Element> 集合时,Dom4j 并不会返回与原文档脱节的静态集合副本,而是返回一个名为 BackedList 的双向实时视图(Live View)。

BackedList 内部持有所属父元素 DefaultElement 的引用。当业务代码仅按名称筛选某一类子元素(例如从混杂了空白 Text、注释与多类标签的父节点中提取所有 book 子元素)时,BackedList 会从底层的混合内容列表中过滤出匹配的 Element 子集;一旦业务代码对该 BackedList 执行新增、按索引插入或删除操作,BackedList 会自动计算目标节点在底层混合内容列表中的真实偏移量,并将变更实时同步回父元素的 DOM 树中。
子节点与属性遍历
在导航访问 Element 内部数据时,Dom4j 区分了按元素筛选、按属性读取与文本提取三类路径:
子元素导航:可直接获取当前元素下的全部子元素列表,或按指定标签名过滤出同名子元素集合;若确定目标子元素在当前层级唯一,也可直接获取首个匹配标签名的单实例。
属性读取:支持直接传入属性名读取对应的字符串值(属性不存在时返回
null或预设默认值),也可获取Attribute对象列表以同时访问属性的命名空间与限定名。文本提取与空白裁剪:元素的文本内容存储在底层的
Text或CDATA叶节点中。读取当前元素的文本时,既可原样保留前后的换行与缩进空白,也可调用裁剪方法自动剔除首尾空白字符;在工程实践中,通常优先使用封装在父元素上的便捷方法直接按子标签名提取子元素文本,从而省去先获取子元素再判空的样板代码。
链式构建与单亲约束
在内存中构建新的 XML 节点树时,Dom4j 提供了流式链式调用与分步挂载两种方式。
链式构建
通过父元素直接调用添加子元素方法时,方法内部会自动委托 DocumentFactory 创建新的子 Element 实例、将其追加到父元素的内容列表末尾,并立即返回该新建的子 Element 引用。而在该子元素上继续调用添加属性、添加文本或添加 CDATA 方法时,则会返回该子元素自身(this),从而支持在单条语句内连贯完成元素创建、属性赋值与文本填充。
分步挂载与单亲约束
除链式创建外,开发者也可先通过 DocumentHelper 静态工厂创建处于游离状态的独立 Element 或 Attribute 实例,组装完毕后再挂载到目标父节点下。
在执行节点挂载时,Dom4j 强制实施单亲节点约束(Single-Parent Constraint):任意一个 Node 实例在同一时刻最多只能隶属于一个父节点。如果尝试将一个已经挂载在某棵文档树(或某个父元素)下的节点直接添加到另一个父元素中,Dom4j 会在运行期抛出 IllegalAddException 异常。若确需将现有节点迁移至新位置,必须先将其从原父节点中剥离(调用 detach() 使其父引用归零),或者先克隆出深拷贝副本,随后再挂载到新的父容器下。
定点插入与节点移除
对内存 Document 树执行结构变更时,需根据目标位置与遍历状态选择对应的修改策略。
指定索引位置插入
直接在父元素上调用添加子元素方法总是将新节点追加到末尾。若需要将新节点插入到首部或两个既有元素之间,可通过父元素获取 BackedList 实时集合视图,再调用标准 java.util.List 的按索引插入方法。此时需要注意:传入视图集合的新元素必须是通过 DocumentHelper 创建的无父节点游离实例,严禁先在父元素上调用添加方法后再重复塞入列表中,否则同样会触发违反单亲约束的 IllegalAddException。
属性与文本覆写
修改既有元素的属性时,直接向该元素重复添加同名属性即可原位覆写旧属性值,无需先删除旧属性再新建;修改元素文本时,调用设置文本方法会自动清空该元素下原有的全部 Text、CDATA 与 Entity 子节点,并替换为新的文本节点(但不会误删该元素下挂载的其他子 Element)。
节点移除与剥离
从文档树中删除节点有两种等价途径:一种是由外层父元素调用移除方法并传入待删子节点引用;另一种是直接在目标子节点(包括 Element、Attribute 或 Comment)自身上调用剥离方法,使其主动断开与父容器的关联。若在遍历节点集合的过程中需要按条件动态删除元素,应使用迭代器的移除方法,或基于快照索引倒序操作,避免直接修改底层列表引发并发修改异常(ConcurrentModificationException)。
示例: 节点树增删改查
以下代码完整演示了使用 DocumentHelper 创建空白文档、链式构建初始节点树、利用 BackedList 实时视图在指定索引位置插入新节点、修改属性与文本,以及剥离移除节点的全过程。
import org.dom4j.Document;
import org.dom4j.DocumentHelper;
import org.dom4j.Element;
import java.util.List;
// 1. 演示在内存中创建、定点插入、修改与删除 Element 节点树
public class ElementCrudDemo {
public static void main(String[] args) {
// 2. 创建空白 Document 并通过链式调用构建根元素与初始子元素
Document document = DocumentHelper.createDocument();
Element root = document.addElement("books");
root.addElement("book")
.addAttribute("id", "B02")
.addElement("title")
.addText("数据结构");
// 3. 创建独立节点并通过 BackedList 实时视图插入到列表首部
Element firstBook = DocumentHelper.createElement("book");
firstBook.addAttribute("id", "B01");
firstBook.addElement("title").setText("Java 核心技术");
List<Element> bookList = root.elements("book");
bookList.add(0, firstBook);
// 4. 修改指定元素的属性值与子元素文本内容
Element secondBook = bookList.get(1);
secondBook.addAttribute("category", "计算机");
secondBook.element("title").setText("算法导论");
// 5. 将首个 book 节点从父容器中剥离并输出最终 XML 字符串
firstBook.detach();
System.out.println(document.asXML());
}
}API: Branch【待补充】
API: Document【待补充】
API: Element【待补充】
API: Attribute【待补充】
API: DocumentHelper【待补充】
XPath 节点检索
当 XML 文档层级较深或需要根据属性、文本条件跨层级筛选节点时,依靠 Element 的子元素遍历方法会产生大量嵌套循环与空指针校验代码。Dom4j 将 XPath(XML Path Language)能力直接下沉至顶层 Node 接口,并通过 org.dom4j.XPath 接口提供预编译表达式、结果排序与命名空间映射支持,使任意节点都能作为上下文起点执行声明式路径检索。
Jaxen 评估流程
Dom4j 自身仅定义了 XPath 的调用契约,底层的路径词法解析、抽象语法树(AST)构建与节点匹配计算全部委托给第三方开源引擎 Jaxen(org.jaxen.dom4j.Dom4jXPath)完成。一次完整的 XPath 检索在底层经历以下四个阶段:
表达式编译:Dom4j 接收用户传入的 XPath 路径字符串,创建
DefaultXPath实例,并在内部初始化Dom4jXPath对象,将路径字符串解析为可重复执行的语法树结构。导航器适配:Jaxen 引擎通过 Dom4j 实现的
DocumentNavigator单例适配器接入内存文档树,使引擎能够理解Document、Element、Attribute、Text等 Dom4j 专属节点的父子与平级导航关系。上下文寻址与过滤:以调用方指定的
Node(如整个Document或某个局部Element子树)作为起始上下文,沿语法树定义的轴向(Axis)逐级扫描候选节点,并逐一验证谓语条件表达式。结果集封装返回:将所有命中条件的节点封装为
List<Node>集合、单个Node实例,或进一步计算转化为字符串、布尔值与数值类型返回给业务层。

若运行期未在项目的构建依赖中引入 jaxen 组件,即使代码编译通过,一旦触发 XPath 相关调用,JVM 就会在实例化 DefaultXPath 时抛出 NoClassDefFoundError: org/jaxen/JaxenException 异常。
路径表达式语法
XPath 使用类似文件系统路径的表达式语法在 XML 树中寻址。根据检索范围与过滤维度的不同,常用语法可分为以下五类。
绝对路径与相对路径
路径表达式的起始符号决定了检索的基准起点:
- 绝对路径(
/开头):以/起始(如/store/book/title)表示无论当前是在哪个子节点上发起调用,检索始终从整棵Document的根部开始逐级向下匹配。 - 相对路径(无前导
/或以./、../开头):直接书写的标签路径(如book/title或./book)表示以当前调用方节点为基准向下寻找直属子元素;使用../则表示回退至当前节点的父元素后再继续寻址。
跨层级全文检索
当目标元素在文档树中的嵌套深度不固定,或需要跳过中间多层容器直接提取后代节点时,可使用双斜杠 // 语法:
- 全局后代匹配:
//book表示从整篇文档的任意层级检索所有名为book的元素节点。 - 子树后代匹配:在相对路径中使用
.//title或/store//title,则限定仅在指定父节点子树范围内跨层级搜索所有title后代节点。
属性匹配与提取
在 XPath 中使用 @ 前缀标识属性节点(Attribute),既可用于判断元素是否携带某个属性,也可直接将属性节点本身提取出来:
- 提取属性节点集合:使用
//book/@id会直接返回所有book元素上的Attribute节点列表,而非外层的Element元素列表。 - 筛选包含特定属性的元素:在谓语中书写
//book[@category]可筛选出所有声明了category属性的book元素。
谓语条件过滤
紧跟在节点名称之后的方括号 [...] 称为谓语(Predicate),用于对当前层级匹配到的候选节点集施加精确过滤:
- 按位置索引过滤:
//book[1]表示匹配同级下的第一个book元素(注意 XPath 的位置索引从1开始计数,而非 Java 数组的0);//book[last()]与//book[last()-1]则分别定位倒数第一个与倒数第二个元素。 - 按属性值等值过滤:
//book[@id='B01']表示筛选出id属性值等于"B01"的book元素。 - 按子元素数值比较过滤:
//book[price>50]表示筛选出内部包含price子元素且其数值大于50的book元素。
逻辑与文本函数
在复杂条件检索场景下,谓语内部支持组合布尔逻辑运算符与 XPath 内置字符串函数:
- 多条件逻辑组合:使用
and与or连接多个条件,例如//book[@category='tech' and price<=100]。 - 文本模糊匹配:结合
contains()、starts-with()与text()函数检索文本内容,例如//book[contains(title, 'Java')]可筛选出标题中包含"Java"子串的所有图书元素。
XPath
在 Dom4j 中执行 XPath 检索共有两种编程入口:一种是直接调用 Node 接口提供的快捷检索方法,另一种是通过 DocumentHelper 显式构建 org.dom4j.XPath 接口实例。
直接在 Document 或 Element 上调用快捷检索方法时,Dom4j 会在每次调用内部临时创建一个新的 XPath 实例并解析路径字符串,适合执行一次性的简单查询(如获取节点列表、获取首个匹配节点或提取目标路径的字符串值)。
而在高频循环检索、结果集排序或包含 XML 命名空间的复杂文档中,直接显式操作 XPath 接口实例更具优势:
表达式预编译复用:通过
DocumentHelper将路径字符串编译为XPath对象后,可在多个不同的Document或Element上下文上反复调用评估方法,省去了重复解析 XPath 语法树的性能开销。检索结果自动排序:
XPath接口支持传入第二个用于指定排序依据的子 XPath 表达式(如按@id或price排序),在返回匹配节点列表的同时自动完成升序、降序或去重排列。命名空间上下文注入:仅显式
XPath实例提供绑定命名空间前缀与 URI 映射字典的入口,这是解析带默认命名空间 XML 文档的唯一标准途径。
默认命名空间陷阱
在解析 Maven 的 pom.xml、Spring 配置文件或 Java Web 的 web.xml 等标准工程配置时,根标签上通常带有无前缀的默认命名空间声明(例如 <project xmlns="[http://maven.apache.org/POM/4.0.0](http://maven.apache.org/POM/4.0.0)">)。此时若直接使用常规无前缀路径(如 /project/dependencies/dependency)执行检索,返回结果必然为空列表。
这一现象源于 XPath 1.0 规范的严格约定:路径表达式中凡是不带命名空间前缀的节点名称,一律只匹配“无命名空间(Null Namespace)”的节点,绝不会自动匹配文档声明的默认命名空间。而根标签一旦声明了 xmlns="...",其自身及下属所有未显式切换命名空间的子元素在内存中均绑定了该 URI,导致无前缀表达式完全失配。
解决该问题的标准步骤如下:
调用
DocumentHelper显式创建XPath实例,并在路径表达式中为每个隶属默认命名空间的标签人工加上自定义前缀(如/pom:project/pom:modelVersion,前缀名可任意指定,无需与原 XML 文档一致)。构建一个
Map<String, String>映射表,将自定义前缀("pom")与 XML 文档中真实的xmlns命名空间 URI("[http://maven.apache.org/POM/4.0.0](http://maven.apache.org/POM/4.0.0)")关联起来。将该映射表注入
XPath实例后,再传入Document执行节点检索。
示例: XPath 多维检索与命名空间绑定
以下代码演示了基于谓语条件筛选节点列表、跨层级定位单个节点,以及通过显式 XPath 实例配置命名空间映射以解决默认 xmlns 检索失效问题的完整实现。
import org.dom4j.Document;
import org.dom4j.DocumentHelper;
import org.dom4j.Element;
import org.dom4j.Node;
import org.dom4j.XPath;
import java.util.Collections;
import java.util.List;
// 1. 演示使用 XPath 表达式检索节点及处理默认命名空间
public class XPathQueryDemo {
public static void main(String[] args) throws Exception {
// 2. 解析带有属性与层级的 XML 字符串生成 Document 树
String xml = "<store><book id=\"B01\" category=\"tech\"><title>Java 编程</title><price>89</price></book>"
+ "<book id=\"B02\" category=\"tech\"><title>网络协议</title><price>45</price></book></store>";
Document document = DocumentHelper.parseText(xml);
// 3. 通过谓语条件检索价格大于 50 的图书节点列表
List<Node> expensiveBooks = document.selectNodes("/store/book[price>50]");
for (Node book : expensiveBooks) {
System.out.println("高价图书: " + book.valueOf("title"));
}
// 4. 跨层级精准定位单个目标节点并读取其文本
Node targetTitle = document.selectSingleNode("//book[@id='B02']/title");
System.out.println("指定图书: " + targetTitle.getText());
// 5. 针对声明了默认 xmlns 命名空间的 XML 绑定前缀映射后执行检索
String nsXml = "<project xmlns=\"http://maven.apache.org/POM\"><modelVersion>4.0.0</modelVersion></project>";
Document nsDoc = DocumentHelper.parseText(nsXml);
XPath xpath = DocumentHelper.createXPath("/pom:project/pom:modelVersion");
xpath.setNamespaceURIs(Collections.singletonMap("pom", "http://maven.apache.org/POM"));
Element versionNode = (Element) xpath.selectSingleNode(nsDoc);
System.out.println("模型版本: " + versionNode.getText());
}
}API: Node【待补充】
API: DocumentHelper【待补充】
API: XPath【待补充】
XMLWriter 格式化输出
在内存中完成对 Document 节点树的构建或修改后,变更仅停留在 JVM 堆内存内,不会自动同步回原 XML 文件。虽然 Node 接口提供了将节点直接转为字符串的快捷能力,但该方式默认输出无缩进的紧凑文本,且无法控制底层字符集编码与空白排版。在工程实践中,将内存文档树持久化到磁盘文件、网络输出流或格式化字符串,统一由 org.dom4j.io.XMLWriter 配合 org.dom4j.io.OutputFormat 完成。
XMLWriter
org.dom4j.io.XMLWriter 是 Dom4j 的核心序列化输出组件。从继承结构上看,它继承自 SAX 标准库的 XMLFilterImpl 并实现了 LexicalHandler 接口,既可直接接收内存中的 Dom4j 节点对象,也可作为 SAX 事件过滤器直接将流式事件写出为 XML 文本。
执行序列化输出时,XMLWriter 会按照深度优先顺序递归遍历目标节点树,依次完成以下输出步骤:
写出文档声明:若序列化目标为顶层
Document且未禁用声明输出,首先依据OutputFormat配置的字符编码写出<?xml version="1.0" encoding="..."?>头部声明,并按需写出文档类型定义(DocumentType)与顶层注释。展开元素与属性:遇到
Element节点时,先输出起始标签名、命名空间声明及全部Attribute键值对;若当前元素无子节点,则根据格式配置决定输出自闭合标签(<tag/>)或成对展开标签(<tag></tag>)。转义字符数据与缩进排版:遍历子内容列表,对普通
Text节点执行 XML 保留字符转义,对CDATA块按原样包裹输出,并在相邻元素节点之间依据层级深度插入对应的缩进与换行符。刷出底层输出流:将组装好的字符序列写入内部封装的带缓冲字符输出流,等待显式刷新或关闭后落盘。
除整篇 Document 外,XMLWriter 也支持直接传入单个 Element、Attribute、Comment 或 CDATA 节点执行局部片段序列化。

OutputFormat
org.dom4j.io.OutputFormat 负责封装 XML 序列化过程中的全部排版规则与编码元数据,并将其注入 XMLWriter 实例。Dom4j 预先提供了两种开箱即用的工厂预设,同时也允许按需微调各项输出细节。
紧凑格式
紧凑格式会移除元素标签之间的全部多余缩进、换行与文本首尾空白,将整篇 XML 文档压缩为连续的紧凑文本流。该格式能最大限度减小输出体积,适合接口报文传输、消息队列投递或日志存储等无需人工阅读的场景。
美化格式
美化格式默认开启自动换行与缩进排版(默认每层缩进 2 个空格),并会自动裁剪文本节点前后由原始文档残留的冗余空白字符。该格式生成的 XML 层级清晰、结构规整,适合配置文件回写与人工审阅场景。
自定义排版属性
在预设格式的基础上,还可通过 OutputFormat 灵活定制输出样式:
- 编码与声明控制:显式指定输出字符集(默认
UTF-8);在仅输出 XML 片段或嵌入已有文档时,可开启抑制声明开关以省略顶部的<?xml ...?>头。 - 缩进与换行定制:可将默认缩进替换为 4 个空格或制表符(
\t),并可显式指定跨平台一致的行分隔符(如统一使用\n而非随操作系统变化的换行符)。 - 空标签展开策略:默认情况下,不含任何子节点与文本的空元素会被简写为自闭合形式(如
<script/>);在生成兼容 HTML 规范的文档时,可开启空标签展开开关,强制输出成对的起止标签(如<script></script>)。
输出流编码策略
在将包含中文或其他非 ASCII 字符的 Document 树写回磁盘时,向 XMLWriter 传入的输出流类型直接决定了最终文件是否会出现乱码。
OutputStream
传入字节输出流(如 FileOutputStream 或 ByteArrayOutputStream)是工程中最稳妥的推荐方式。当 XMLWriter 接收到 OutputStream 时,会在内部读取 OutputFormat 中设定的编码名称,自动为其包装一层匹配该字符集的 OutputStreamWriter 与缓冲流。这样能严格保证文件头部 encoding="..." 声明与磁盘实际落盘的字节编码完全一致,不受操作系统默认字符集影响。
Writer
若直接向 XMLWriter 传入字符输出流(如 FileWriter),字符集编码已在外部构造 FileWriter 时被提前锁定为 JVM 启动时的平台默认编码(例如部分 Windows 环境下的 GBK)。此时即便在 OutputFormat 中配置了 UTF-8,XMLWriter 也只能更改 XML 头部声明中的文字,却无法改变底层 FileWriter 的实际写入编码,最终导致“声明编码与文件实际字节编码冲突”的乱码问题。因此,仅在输出到内存 StringWriter 或已显式指定相同编码的 OutputStreamWriter 时,才建议直接传入 Writer。
实体字符转义
为保证输出的文本严格符合 XML 语法规范,XMLWriter 默认开启文本转义策略:在写出 Text 节点和 Attribute 属性值时,会自动将 <、>、& 等保留符号转换为 <、>、& 实体引用,防止特殊符号破坏标签边界。
若业务文本中本身包含已预先转义好的实体片段,或期望按原样输出内嵌标签文本,可通过 XMLWriter 关闭文本转义开关。需要注意的是,关闭全局转义后若文本中混入未闭合的尖括号或孤立的 & 符号,将导致生成的 XML 文档无法被重新解析;针对包含大量特殊符号的原文内容,优先将其封装为 CDATA 节点是更安全的做法。
缓冲资源释放
XMLWriter 在向 OutputStream 写出数据时,底层会通过缓冲写入器(BufferedWriter)缓存字符以提升磁盘 I/O 吞吐效率。若调用写出方法后未及时刷新或关闭 XMLWriter,缓存中的数据将滞留在内存中无法落盘,最终导致生成的 XML 文件为空或末尾标签被截断。
此外,XMLWriter 并未实现 Java 标准的 AutoCloseable 接口,因此无法直接声明在 try-with-resources 语句头部自动关闭。在生产代码中,必须在 finally 代码块内显式执行刷新与关闭操作,确保在发生异常时缓冲内容能够安全释放且底层文件句柄不会泄漏。
示例: 格式化输出 XML 文档
以下代码演示了如何分别使用美化格式与紧凑格式配置 OutputFormat,通过字节输出流将内存 Document 树安全写回本地文件,以及借助 StringWriter 将其序列化为紧凑字符串。
import org.dom4j.Document;
import org.dom4j.DocumentHelper;
import org.dom4j.Element;
import org.dom4j.io.OutputFormat;
import org.dom4j.io.XMLWriter;
import java.io.FileOutputStream;
import java.io.OutputStream;
import java.io.StringWriter;
// 1. 演示使用 OutputFormat 与 XMLWriter 将 Document 树格式化写出到文件及字符串
public class XmlWriteDemo {
public static void main(String[] args) throws Exception {
// 2. 在内存中构建包含中文与特殊字符的测试文档树
Document document = DocumentHelper.createDocument();
Element root = document.addElement("config");
root.addElement("appName").setText("订单中心 & 结算服务");
root.addElement("description").addCDATA("支持 x < 100 条件过滤");
// 3. 配置美化输出格式,指定 UTF-8 编码与四空格缩进
OutputFormat prettyFormat = OutputFormat.createPrettyPrint();
prettyFormat.setEncoding("UTF-8");
prettyFormat.setIndent(" ");
// 4. 通过字节输出流配合 XMLWriter 写回磁盘,确保缓冲刷新与资源释放
try (OutputStream out = new FileOutputStream("config.xml")) {
XMLWriter xmlWriter = new XMLWriter(out, prettyFormat);
try {
xmlWriter.write(document);
xmlWriter.flush();
} finally {
xmlWriter.close();
}
}
// 5. 配置紧凑格式并结合 StringWriter 将文档树序列化为单行 XML 字符串
OutputFormat compactFormat = OutputFormat.createCompactFormat();
compactFormat.setEncoding("UTF-8");
StringWriter stringWriter = new StringWriter();
XMLWriter textWriter = new XMLWriter(stringWriter, compactFormat);
textWriter.write(document);
textWriter.close();
System.out.println(stringWriter.toString());
}
}