開篇

?最近開始看Tomcat的源碼，在catalina. createStartDigester方法中，Tomcat開發(fā)人員采用了Digester來(lái)讀取conf/server.xml文件，以前讀取xml文件一般采用Dom4j和SAX，因此對(duì)Digester比較陌生，順便就抽時(shí)間研究了一下Digester是如何解析xml文件的。

?先簡(jiǎn)單闡述下Dom4j和SAX解析XML的區(qū)別：

• Dom4j是把一個(gè)xml文件全部讀取到內(nèi)存中，構(gòu)建成一個(gè)DOM樹來(lái)解析，所以Dom4j適合讀取比較小的xml文件。
• SAX是基于文件流來(lái)解析xml文件的，在讀取xml文件流時(shí)，SAX會(huì)通過(guò)節(jié)點(diǎn)來(lái)觸發(fā)相應(yīng)的操作，也可以說(shuō)SAX是基于文件流的事情觸發(fā)機(jī)制來(lái)解析xml文件的。
• Digeter是apache的common項(xiàng)目，作用是將XML轉(zhuǎn)化成對(duì)象，使用者直接從對(duì)象中獲取xml的節(jié)點(diǎn)信息。Digester是對(duì)SAX的包裝，它也是基于文件流來(lái)解析xml文件，只不過(guò)這些解析操作對(duì)用戶是透明的。
• Tomcat的配置文件conf/server.xml就是用Digester來(lái)讀取的。

?Digester的來(lái)源

• Digester本來(lái)僅僅是Jakarta Struts中的一個(gè)工具，用于處理struts-config.xml配置文件。顯然，將XML文件轉(zhuǎn)換成相應(yīng)的Java對(duì)象是一項(xiàng)很通用的功能，這個(gè)工具理應(yīng)具有更廣泛的用途，所以很快它就在Jakarta Commons項(xiàng)目(用于提供可重用的Java組件庫(kù))中有了一席之地。

• 如今Digester隨著Struts的發(fā)展以及其的公用性而被提到commons中獨(dú)自立項(xiàng)，是apache的一個(gè)組件 apache commons-digester.jar,通過(guò)它可以很方便的從xml文件生成java對(duì)象。

?Digester工作原理：

• Digester由"事件"驅(qū)動(dòng)，通過(guò)調(diào)用預(yù)定義的規(guī)則操作對(duì)象棧，將XML文件轉(zhuǎn)換為Java對(duì)象。

• Digester底層采用SAX解析XML文件，所以很自然的，對(duì)象轉(zhuǎn)換由"事件"驅(qū)動(dòng)，即在識(shí)別出特定XML元素時(shí)(實(shí)際被細(xì)分為begin、body、end、finish四個(gè)時(shí)點(diǎn))，將執(zhí)行特定的動(dòng)作，比如創(chuàng)建特定的Java對(duì)象，或調(diào)用特定對(duì)象的方法等。此處的XML元素根據(jù)匹配模式(matching pattern)識(shí)別，而相關(guān)操作由規(guī)則(rule)定義。

• 在轉(zhuǎn)換過(guò)程中，Digester維持了一個(gè)對(duì)象棧，可以看作對(duì)象轉(zhuǎn)換的工作臺(tái)，用來(lái)存放轉(zhuǎn)換中生成的、或是為轉(zhuǎn)換臨時(shí)創(chuàng)建的Java對(duì)象。對(duì)輸入XML文件作了一趟完整的掃描后，對(duì)象棧的棧頂元素即為目標(biāo)對(duì)象。由于Digester屏蔽了SAX解析的細(xì)節(jié)，使用者僅需關(guān)注轉(zhuǎn)換操作本身，大大簡(jiǎn)化了轉(zhuǎn)換操作。

?以下的內(nèi)容都是分享自文末參考文章的內(nèi)容，對(duì)于一些API的使用非常建議直接下載jar包看源碼注釋

        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-digester3</artifactId>
            <version>3.2</version>
        </dependency>

使用Digester的基本步驟

• 1、創(chuàng)建一個(gè) org.apache.commons.digester3.Digester 類的實(shí)例對(duì)象。這里補(bǔ)充說(shuō)明下，只要我們已經(jīng)完成XML解析操作，并且不在多個(gè)線程中使用同一個(gè)Digester對(duì)象，那么就可以安全的重復(fù)使用我們預(yù)先創(chuàng)建的這個(gè)Digester實(shí)例；不過(guò)重用Digester實(shí)例并不是非常推薦，最好每個(gè)XML解析對(duì)應(yīng)一個(gè)單獨(dú)的Digester實(shí)例；

• 2、為Digester實(shí)例配置屬性值，通過(guò)配置屬性值，我們可以改變Digester 的解析行為，具體有哪些屬性值可以配置，待會(huì)會(huì)介紹；

• 3、可選的, 可以將我們的一些初始對(duì)象push到Digester棧里；

• 4、在輸入的XML文檔中，給所有需要觸發(fā)規(guī)則（rule）處理的元素匹配模式（pattern）注冊(cè)規(guī)則;針對(duì)任何一個(gè)模式，你可以注冊(cè)任意數(shù)量的規(guī)則；補(bǔ)充說(shuō)明下，如果一個(gè)模式對(duì)應(yīng)多個(gè)規(guī)則，則begin和body事件方法會(huì)按照它們注冊(cè)的順序依次執(zhí)行，而end事件方法是倒序執(zhí)行的；

• 5、最后，調(diào)用digester.parse()方法，該方法需要傳入XML文件的引用作為參數(shù)，該參數(shù)支持多種格式的文件流；另外需要注意的是，該方法會(huì)拋出IOException or SAXException異常，以及各種可能的在規(guī)則解析處理時(shí)遇到的異常，如NoSuchMethodException、IllegalAccessException…

?了解基本步驟后，來(lái)看一個(gè)簡(jiǎn)單的示例，如下所示，是我們即將要解析的xml文件：

<foo name="The Parent">
    <bar id="123" title="The First Child" />
    <bar id="456" title="The Second Child" />
    <bar id="789" title="The Second Child" />
</foo>

?首先，創(chuàng)建兩個(gè)java bean對(duì)應(yīng)xml中的元素信息：

?Foo類

package apache.commons.digester3.example.pojo;

import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;

/**
 * @author http://www.cnblogs.com/chenpi/
 * @version 2017年6月3日
 */
public class Foo
{
    private String name;
    private List<Bar> barList = new ArrayList<Bar>();

    public void addBar(Bar bar)
    {
        barList.add(bar);
    }

    public Bar findBar(int id)
    {
        for (Bar bar : barList)
        {
            if (bar.getId() == id)
            {
                return bar;
            }
        }
        return null;
    }

    public Iterator<Bar> getBars()
    {
        return barList.iterator();
    }

    /**
     * @return the name
     */
    public String getName()
    {
        return name;
    }

    /**
     * @param name the name to set
     */
    public void setName(String name)
    {
        this.name = name;
    }

    /**
     * @return the barList
     */
    public List<Bar> getBarList()
    {
        return barList;
    }

    /**
     * @param barList the barList to set
     */
    public void setBarList(List<Bar> barList)
    {
        this.barList = barList;
    }
}

?Bar類

package apache.commons.digester3.example.pojo;

/**
 * @author    http://www.cnblogs.com/chenpi/
 * @version   2017年6月3日
 */
public class Bar
{

    private int id;
    private String title;

    /**
     * @return the id
     */
    public int getId()
    {
        return id;
    }

    /**
     * @param id the id to set
     */
    public void setId(int id)
    {
        this.id = id;
    }

    /**
     * @return the title
     */
    public String getTitle()
    {
        return title;
    }

    /**
     * @param title the title to set
     */
    public void setTitle(String title)
    {
        this.title = title;
    }

}

?使用Digester解析xml：

package apache.commons.digester3.example.simpletest;

import java.io.IOException;

import org.apache.commons.digester3.Digester;
import org.xml.sax.SAXException;

import apache.commons.digester3.example.pojo.Bar;
import apache.commons.digester3.example.pojo.Foo;

/**
 * 
 * @author http://www.cnblogs.com/chenpi/
 * @version 2017年6月3日
 */

public class Main
{

    public static void main(String[] args)
    {

        try
        {
            //1、創(chuàng)建Digester對(duì)象實(shí)例
            Digester digester = new Digester();

            //2、配置屬性值
            digester.setValidating(false);

            //3、push對(duì)象到對(duì)象棧
            //digester.push(new Foo());
            
            //4、設(shè)置匹配模式、規(guī)則
            digester.addObjectCreate("foo", "apache.commons.digester3.example.pojo.Foo");
            digester.addSetProperties("foo");
            digester.addObjectCreate("foo/bar", "apache.commons.digester3.example.pojo.Bar");
            digester.addSetProperties("foo/bar");
            digester.addSetNext("foo/bar", "addBar", "apache.commons.digester3.example.pojo.Bar");

            //5、開始解析
            Foo foo = digester.parse(Main.class.getClassLoader().getResourceAsStream("example.xml"));

            //6、打印解析結(jié)果
            System.out.println(foo.getName());
            for (Bar bar : foo.getBarList())
            {
                System.out.println(bar.getId() + "," + bar.getTitle());
            }

        }
        catch (IOException e)
        {

            e.printStackTrace();
        }
        catch (SAXException e)
        {

            e.printStackTrace();
        }
    }
}

?結(jié)果打印：

The Parent
123,The First Child
456,The Second Child
789,The Second Child

?注意以上代碼涉及類型的自動(dòng)轉(zhuǎn)換，如id屬性，由字符串類型轉(zhuǎn)為整型，這里所有的類型轉(zhuǎn)換都是由commons-beanutils包的ConvertUtils來(lái)完成的。

Digester屬性配置

?org.apache.commons.digester3.Digester實(shí)例對(duì)象包含若干成員屬性，這些屬性值是可以設(shè)置的，以便我們自定義解析操作；

?為了讓這些配置在XML解析前生效，這些屬性值的更改一定要在parse方法調(diào)用之前設(shè)置；下面是一些可以配置的屬性：

?另外，我們可以通過(guò)Digester的register方法，讓Digester在遇到DOCTYPE聲明時(shí)，使用本地dtd，而不是從網(wǎng)上獲取，如下所示：

URL url = new URL("/org/apache/struts/resources/struts-config_1_0.dtd");
digester.register("-//Apache Software Foundation//DTD Struts Configuration 1.0//EN", url.toString());

Digester對(duì)象棧

?Digester使用的一個(gè)核心技術(shù)就是動(dòng)態(tài)構(gòu)建一顆java對(duì)象樹，在構(gòu)建的過(guò)程中，一個(gè)重要的輔助數(shù)據(jù)結(jié)構(gòu)即對(duì)象棧；

?以如下xml為例：

<foo name="The Parent">
    <bar id="123" title="The First Child" />
    <bar id="456" title="The Second Child" />
    <bar id="789" title="The Second Child" />
</foo>

?在解析的時(shí)候，首先會(huì)創(chuàng)建一個(gè)foo對(duì)象，并壓入對(duì)象棧，然后設(shè)置foo屬性值name，緊接著，創(chuàng)建bar對(duì)象并壓入棧，然后設(shè)置bar的屬性值，然后將該bar對(duì)象添加的到foo對(duì)象的barlist屬性集合中，然后bar對(duì)象彈出對(duì)象棧；

?以此類推，遇到起始標(biāo)記的元素創(chuàng)建對(duì)象入棧，遇到結(jié)尾標(biāo)記的元素做出棧操作，出棧前，需要將出棧對(duì)象并關(guān)聯(lián)到上一個(gè)棧頂對(duì)象；

?最終，解析完xml后，留在棧頂?shù)木完P(guān)聯(lián)了所有在xml解析中創(chuàng)建的動(dòng)態(tài)對(duì)象了；

?Digester暴露出的與對(duì)象棧操作API如下所示：

• clear() - 清除對(duì)象棧.
• peek() - 返回棧頂對(duì)象引用，但是不彈出.
• pop() - 返回棧頂對(duì)象，并彈出.
• push() - 入棧操作.

Digester元素匹配模式

?Digester的一個(gè)關(guān)鍵特性是可以自動(dòng)識(shí)別xml的層次結(jié)構(gòu)，程序員只需要關(guān)心遇到匹配到某個(gè)元素后需要做哪些操作即可；

?如下是一個(gè)示例，其中a, a/b, a/b/c為匹配模式，對(duì)應(yīng)xml中特定位置的元素：

<a>         -- Matches pattern "a"
    <b>       -- Matches pattern "a/b"
      <c/>    -- Matches pattern "a/b/c"
      <c/>    -- Matches pattern "a/b/c"
    </b>
    <b>       -- Matches pattern "a/b"
      <c/>    -- Matches pattern "a/b/c"
      <c/>    -- Matches pattern "a/b/c"
      <c/>    -- Matches pattern "a/b/c"
    </b>
  </a>

Digester規(guī)則處理

?當(dāng)匹配到模式時(shí)，會(huì)觸發(fā)規(guī)則處理，具體的規(guī)則處理機(jī)制是由這個(gè)org.apache.commons.digester3.Rule接口封裝的，該接口定義了以下幾個(gè)方法：

• begin() - 匹配到xml元素開始標(biāo)記時(shí)，調(diào)用該方法；
• body() - 匹配到xml元素body時(shí)，調(diào)用該方法；
• end() - 匹配到xml元素結(jié)束標(biāo)記時(shí)，調(diào)用該方法；
• finish() - 當(dāng)所有解析方法解析完畢后，調(diào)用該方法，用于清楚臨時(shí)數(shù)據(jù)等；

?默認(rèn)情況下，Digester提供了以下Rule接口的實(shí)現(xiàn)類，我們?cè)诰幋a的時(shí)候可以直接使用，詳見API文檔：

• ObjectCreateRule
• FactoryCreateRule
• SetPropertiesRule
• SetPropertyRule
• SetNextRule
• SetTopRule
• CallMethodRule
• CallParamRule
• NodeCreateRule

?如下是一個(gè)SetNextRule規(guī)則實(shí)現(xiàn)類的示例（兩種寫法）：

Rule rule = new SetNextRule("addBar",Bar.class);
digester.addRule("foo/bar", rule );

//digester.addSetNext("foo/bar", "addBar", Bar.class.getName());

Digester日志

?日志是調(diào)試、排查錯(cuò)誤非常關(guān)鍵的一個(gè)環(huán)節(jié)，Digester記錄了非常詳細(xì)的日志，我們可以按如下方式來(lái)開啟日志打印功能，這里的日志實(shí)現(xiàn)選擇log4j。

• 1、首先，在pom.xml加上如下依賴：

        <!-- https://mvnrepository.com/artifact/log4j/log4j -->
        <dependency>
            <groupId>log4j</groupId>
            <artifactId>log4j</artifactId>
            <version>1.2.17</version>
        </dependency>

• 2、然后，編寫一個(gè)配置文件log4j.properties放到resources路徑下：

### set log levels ###
log4j.rootLogger = debug, stdout

### \u8F93\u51FA\u5230\u63A7\u5236\u53F0 ###
log4j.appender.stdout = org.apache.log4j.ConsoleAppender
log4j.appender.stdout.Target = System.out
log4j.appender.stdout.layout = org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern = %-d{yyyy-MM-dd HH:mm:ss}  [ %t:%r ] - [ %p ]  %m%n

• 3、運(yùn)行程序，發(fā)現(xiàn)已經(jīng)可以看到DEBUG調(diào)試日志了日志：

2017-06-04 18:26:33  [ main:51 ] - [ DEBUG ]    Fire body() for SetPropertiesRule[aliases={}, ignoreMissingProperty=true]
2017-06-04 18:26:33  [ main:51 ] - [ DEBUG ]    Popping body text ''
2017-06-04 18:26:33  [ main:51 ] - [ DEBUG ]    Fire end() for SetPropertiesRule[aliases={}, ignoreMissingProperty=true]
2017-06-04 18:26:33  [ main:52 ] - [ DEBUG ]    Fire end() for ObjectCreateRule[className=apache.commons.digester3.example.pojo.Foo, attributeName=null]
2017-06-04 18:26:33  [ main:52 ] - [ DEBUG ]  [ObjectCreateRule]{foo} Pop 'apache.commons.digester3.example.pojo.Foo'
2017-06-04 18:26:33  [ main:52 ] - [ DEBUG ]  endDocument()
The Parent
123,The First Child
456,The Second Child
789,The Second Child

Digester例子

?前面我們已經(jīng)舉了一個(gè)Digester的簡(jiǎn)單使用例子，這里將繼續(xù)展示幾個(gè)示例,解析xml元素body值。
?如下XML文檔就是我們要解析內(nèi)容：

<web-app>
    <servlet>
        <servlet-name>action</servlet-name>
        <servlet-class>org.apache.struts.action.ActionServlet</servlet-class>
            <init-param>
                <param-name>application</param-name>
                <param-value>org.apache.struts.example.ApplicationResources</param-value>
            </init-param>
            <init-param>
                <param-name>config</param-name>
                <param-value>/WEB-INF/struts-config.xml</param-value>
            </init-param>
    </servlet>
</web-app>

• 1、首先，定義一個(gè)ServletBean，存儲(chǔ)以上xml信息，如下所示：

/*
 * File Name: ServletBean.java
 * Description: 
 * Author: http://www.cnblogs.com/chenpi/
 * Create Date: 2017年6月4日
 */
package apache.commons.digester3.example.pojo;

import java.util.HashMap;
import java.util.Map;

/**
 * 
 * @author    http://www.cnblogs.com/chenpi/
 * @version   2017年6月4日
 */

public class ServletBean
{

    private String servletName;
    private String servletClass;
    private Map<String, String> initParams = new HashMap<String, String>();
    
    
    public void addInitParam(String paramName, String paramValue){
        initParams.put(paramName, paramValue);
    }
    /**
     * @return the servletName
     */
    public String getServletName()
    {
        return servletName;
    }
    /**
     * @param servletName the servletName to set
     */
    public void setServletName(String servletName)
    {
        this.servletName = servletName;
    }
    /**
     * @return the servletClass
     */
    public String getServletClass()
    {
        return servletClass;
    }
    /**
     * @param servletClass the servletClass to set
     */
    public void setServletClass(String servletClass)
    {
        this.servletClass = servletClass;
    }
    /**
     * @return the initParams
     */
    public Map<String, String> getInitParams()
    {
        return initParams;
    }
    /**
     * @param initParams the initParams to set
     */
    public void setInitParams(Map<String, String> initParams)
    {
        this.initParams = initParams;
    }
}

• 2、編寫規(guī)則解析xml，如下所示：

/*
 * File Name: Main2.java
 * Description: 
 * Author: http://www.cnblogs.com/chenpi/
 * Create Date: 2017年6月4日
 */
package apache.commons.digester3.example.simpletest;

import java.io.IOException;

import org.apache.commons.digester3.Digester;
import org.apache.commons.digester3.Rule;
import org.apache.commons.digester3.SetNextRule;
import org.xml.sax.SAXException;

import apache.commons.digester3.example.pojo.Bar;
import apache.commons.digester3.example.pojo.Foo;
import apache.commons.digester3.example.pojo.ServletBean;

/**
 * 
 * @author http://www.cnblogs.com/chenpi/
 * @version 2017年6月4日
 */

public class WebMain
{

    public static void main(String[] args)
    {
        try
        {
            // 1、創(chuàng)建Digester對(duì)象實(shí)例
            Digester digester = new Digester();

            // 2、配置屬性值
            digester.setValidating(false);

            // 3、push對(duì)象到對(duì)象棧

            // 4、設(shè)置匹配模式、規(guī)則
            digester.addObjectCreate("web-app/servlet", "apache.commons.digester3.example.pojo.ServletBean");
            digester.addCallMethod("web-app/servlet/servlet-name", "setServletName", 0);
            digester.addCallMethod("web-app/servlet/servlet-class", "setServletClass", 0);
            digester.addCallMethod("web-app/servlet/init-param", "addInitParam", 2);
            digester.addCallParam("web-app/servlet/init-param/param-name", 0);
            digester.addCallParam("web-app/servlet/init-param/param-value", 1);

            // 5、開始解析
            ServletBean servletBean = digester
                .parse(ExampleMain.class.getClassLoader().getResourceAsStream("web.xml"));

            // 6、打印解析結(jié)果
            System.out.println(servletBean.getServletName());
            System.out.println(servletBean.getServletClass());
            for(String key : servletBean.getInitParams().keySet()){
                System.out.println(key + ": " + servletBean.getInitParams().get(key));
            }

        }
        catch (IOException e)
        {

            e.printStackTrace();
        }
        catch (SAXException e)
        {

            e.printStackTrace();
        }

    }
}

• 3、結(jié)果打印：

action
org.apache.struts.action.ActionServlet
application: org.apache.struts.example.ApplicationResources
config: /WEB-INF/struts-config.xml

參考資料

http://commons.apache.org/proper/commons-digester/guide/core.html

示例代碼

https://github.com/peterchenhdu/apache-commons-digester-example

參考文章

Apache Commons Digester 一 （基礎(chǔ)內(nèi)容、核心API）
Apache Commons Digester 二（規(guī)則模塊綁定-RulesModule、異步解析-asyncParse、xml變量Substitutor、帶參構(gòu)造方法）
Apache Commons Digester 三（規(guī)則注解）
tomcat源碼解析（三）——Digester類源碼解析及Rule分析
tomcat源碼解讀一 Digester的解析方式