Digester 是一个依据 xml 配置文件动态构建 Java 对象树的工具,基于 SAX 解析器进行封装,它为 SAX 事件的处理提供了更高级和友好的接口,让开发更专注于要执行的处理,隐藏了 XML 元素详细的层次结构信息。
1. 对象堆栈
为了便于实现,内部使用堆栈存储创建的对象。当满足元素匹配模式时,按预设的处理规则操作栈中对象。
典型的创建对象处理逻辑是,触发创建新对象的规则,在遇到特定 XML 元素的开头时将其推送到栈顶;处理此元素的嵌套内容和属性时,该对象将保留在堆中;当遇到元素的末尾时,将它弹出。
Digester 提供的处理规则解决了这种设计的几个潜在问题:
- 如何将正在创建的对象相互关联?SetNextRule 规则将栈顶对象作为参数传递给堆栈下一个顶层对象的命名方法(反之亦然),此规则可以轻松地在这些对象之间建立父子关系,一对一和一对多的关系也很容易构建。
- 如何保留对第一个创建对象的引用?当遇到开始元素的结束标签时,所有对象从栈中弹出,但 parse() 方法会返回第一个创建的对象,也可以在解析前将某个应用程序对象的引用推送到堆栈,并手动设置和动态创建对象之间的父子关系。
2. 元素模式匹配
Digester 解析器的一个主要特性是自动确定正在解析的 XML 文档的元素层次结构,开发人员只需在解析过程中遇到某种嵌套元素排列时,决定要执行哪些函数。元素匹配模式,确认的就是执行函数也就是规则。
一个非常简单的元素匹配模式是一个简单的字符串,如\"a\"。只要在 XML文档中遇到顶级元素 <a>,无论它发生多少次,都会匹配此模式。请注意,嵌套的 <a> 元素将不匹配此模式。
比较复杂的是匹配嵌套元素,如 \"a/b\",当找到嵌套在顶级 <a> 元素内的 <b> 元素时,将匹配此模式。同样,这种匹配可以根据需要多次发生,具体取决于要解析的XML文档的内容。也可以使用多个斜杠来定义要匹配的任何所需深度的层次结构。
例如,假设已注册与 \"a\", \"a/b\", 和 \"a/b/c\" 模式匹配的处理规则。对于具有以下内容的输入XML文档,在解析相应元素时将匹配指示的模式:
<a> -- 匹配 \"a\"
<b> -- 匹配 \"a/b\"
<c/> -- 匹配 \"a/b/c\"
<c/> -- 匹配 \"a/b/c\"
</b>
<b> -- 匹配 \"a/b\"
<c/> -- 匹配 \"a/b/c\"
<c/> -- 匹配 \"a/b/c\"
<c/> -- 匹配 \"a/b/c\"
</b>
</a>
通过在匹配的模式字符串中使用 \"*\" 通配符,也可以匹配特定的XML元素,无论它是如何嵌套(或不嵌套)在XML文档中。例如,元素匹配模式 \"*/a\" 将匹配文档内任何嵌套位置的元素 <a>。
如果一个匹配模式对应多个处理规则,将按顺序触发。 begin(和body)方法按照最初向 Digester 注册的 Rules 的顺序执行,而 end 方法调用以相反的顺序执行。 换句话说 - 顺序是先进先出的。
3. 处理规则
处理规则定义的时模式匹配时应该发生的动作,它通常时 Rule 接口的子类,每个规则实现了以下一个或多个事件方法,这些方法会在解析的过程中执行:
- begin() - 遇到匹配的 XML 元素的开头时调用,并传递包含与该元素对应的所有属性的数据结构
- body() - 遇到匹配元素的嵌套内容(不是 XML 元素,文本内容)时调用,在解析过程中,任何开始或结束的空格都被删除
- end() - 遇到匹配的 XML 元素的结尾时调用,如果此元素包含嵌套的 XML 元素,则在调用此方法之前,已完成嵌套元素匹配的规则
- finish() - 在 XML 文档结束,完成解析时调用,为每个规则提供清理他们可能已创建和缓存的任何临时数据的机会
Digester 提供了一组处理规则实现类,用于处理许多常见的编程场景,这些类分别是:
- ObjectCreateRule - begin()方法被调用时,此规则将实例化指定 Java 类的新实例,并将其推送到堆栈。默认使用的类名是根据传递给构造函数的参数,但也可以通过正在处理的 XML 元素指定属性及类名被覆盖。当 end()方法被调用时,栈顶的对象将被弹出,并且 Digester 内它的任何引用将被丢弃。
- FactoryCreateRule - ObjectCreateRule 的一种变体,当要创建对象实例的 Java 类没有无参数构造函数,或者希望在将对象移交给 Digester 之前执行其他处理时,它很有用。
- SetPropertiesRule - begin()方法被调用时,Digester 使用 Java Reflection API 获取栈顶对象属性的 setter 方法名称,并与 XML 元素上指定的属性相匹配,然后执行设置相应的属性值。一个常见用法是:定义一个 ObjectCreateRule,然后是一个 SetPropertiesRule,它们具有相同的元素匹配模式。
- SetPropertyRule - begin()方法被调用时,Digester 调用栈顶对象指定属性的 setter 方法,属性的 key-value 由 XML 设置。当 XML 文件符合特定的 DTD,并且希望配置 DTD 中没有相应属性的特定属性时,这非常有用。
- SetNextRule - end()方法被调用时,Digester 分析栈中的下一个栈顶元素,查找指定属性的 setter 方法,然后它调用此方法,将栈顶对象作为参数传递。此规则通常用于在两个对象之间建立一对多关系,方法名称通常类似于 \"addChild\"。
- CallMethodRule - 在 end()方法被调用时执行,设置栈顶对象特定方法的调用,可指定方法名称和参数,实际的参数通常在触发此规则元素的 body 中。
- CallParamRule - 此规则标识我们嵌套的 CallMethodRule 参数的来源,可以指定参数值取自特定的命名属性,或者取自此元素嵌套的 body 内容。
4. 用法示例 - 创建简单的对象树
假设有两个简单的 JavaBeans,Foo 和 Bar,方法签名如下:
package mypackage;
public class Foo {
public void addBar(Bar bar);
public Bar findBar(int id);
public Iterator getBars();
public String getName();
public void setName(String name);
}
public mypackage;
public class Bar {
public int getId();
public void setId(int id);
public String getTitle();
public void setTitle(String title);
}
并且使用 Digester 来解析以下 XML 文档:
<foo name=\"The Parent\">
<bar id=\"123\" title=\"The First Child\"/>
<bar id=\"456\" title=\"The Second Child\"/>
</foo>
一个简单的方法是使用 Digester 设置如下方式的解析规则,然后处理包含此文档的输入文件:
Digester digester = new Digester();
digester.setValidating(false);
digester.addObjectCreate(\"foo\", \"mypackage.Foo\");
digester.addSetProperties(\"foo\");
digester.addObjectCreate(\"foo/bar\", \"mypackage.Bar\");
digester.addSetProperties(\"foo/bar\");
digester.addSetNext(\"foo/bar\", \"addBar\", \"mypackage.Bar\");
Foo foo = (Foo) digester.parse();
这些规则将按顺序执行以下任务:
- 遇到最外层的 <foo> 元素时,创建 mypackage.Foo 的新实例并将其推送到对象堆栈;在 <foo> 元素的末尾,此对象将从堆栈中弹出。
- 基于此 XML 元素的属性值设置刚刚创建和推送到栈顶的对象,Foo 的属性。
- 遇到嵌套的 <bar> 元素时,创建 mypackage.Bar 的新实例并将其推送到对象堆栈;在<bar>元素的末尾,该对象将从堆栈中弹出(即在处理匹配 foo/bar 的其余规则之后)。
- 基于此 XML 元素的属性值设置刚刚创建和推送到栈顶的对象,Bar 的属性。注意 id,属性的 String -> int,要执行类型转换
- 调用 next-to-top,即下一个栈顶元素上的 addBar 方法(这就是为什么被称为 \"set next\" 规则),并将当前栈顶元素作为参数,从而建立父/子关系。
解析完成后,第一个被推入堆栈的对象(本例中为 Foo 对象)将返回,它的属性已被初始化,并包含创建的所有子 Bar 对象。
5. 小结
每个框架都有自己解析 XML 的方法,Tomcat 也不例外,本文对 Digester 的基本原理进行了总结,使用还是比较简单方便的。
此外,Digester 还有一些其他设置,比如指定创建对象使用的类加载器,是否以命名空间的方式解析,是否根据指定的 DTD 验证文档,还有 RuleSet 可重用规则集的使用等。