Tomcat 配置文件解析工具 Digester

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 可重用规则集的使用等。