Tomcat 配置文件解析工具 Digester

752 阅读8分钟

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

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