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();
复制代码

这些规则将按顺序执行如下任务：

1. 遇到最外层的 <foo> 元素时，建立 mypackage.Foo 的新实例并将其推送到对象堆栈；在 <foo> 元素的末尾，此对象将从堆栈中弹出。
2. 基于此 XML 元素的属性值设置刚刚建立和推送到栈顶的对象，Foo 的属性。
3. 遇到嵌套的 <bar> 元素时，建立 mypackage.Bar 的新实例并将其推送到对象堆栈；在<bar>元素的末尾，该对象将从堆栈中弹出（即在处理匹配 foo/bar 的其他规则以后）。
4. 基于此 XML 元素的属性值设置刚刚建立和推送到栈顶的对象，Bar 的属性。注意 id，属性的 String -> int，要执行类型转换
5. 调用 next-to-top，即下一个栈顶元素上的 addBar 方法（这就是为何被称为 "set next" 规则），并将当前栈顶元素做为参数，从而创建父/子关系。

解析完成后，第一个被推入堆栈的对象（本例中为 Foo 对象）将返回，它的属性已被初始化，并包含建立的全部子 Bar 对象。

5. 小结

每一个框架都有本身解析 XML 的方法，Tomcat 也不例外，本文对 Digester 的基本原理进行了总结，使用仍是比较简单方便的。

此外，Digester 还有一些其余设置，好比指定建立对象使用的类加载器，是否以命名空间的方式解析，是否根据指定的 DTD 验证文档，还有 RuleSet 可重用规则集的使用等。

搜索微信公众号「顿悟源码」，获取更多源码分析和造的轮子。