定製自己的xDoclet標籤

出處：http://www.javaresearch.org/article/showarticle.jsp?column=2&thread=15082

xDoclet是一種通過讀取JAVA源文件中的特定標籤，然後生成指定文件的工具。xDoclet標籤本身已經提供了一些常用的標籤，例如@ejb，@hibernate，@web等等，但是仍然不能滿足我們的需求。
例如我們最新的項目中引用了一個Javascript驗證框架，通過配置特定的xml配置文件，即可完成客戶端表單驗證，但是不想開發人員再去學習一套框架，於是想讓開發人員在源代碼中寫@javascript這樣的標籤，然後生成其配置文件。
Javascript客戶端驗證一直是web開發中一個比較頭疼的問題，經常是每一個頁面中充斥着許多類似甚至相同的驗證代碼，如何統一有效的管理這些代碼，以及如何做到代碼頁面的分離一直沒有太好的解決方法。

運用這個驗證框架那麼客戶端開發就變成了配置validation-config.xml這個文件如此輕鬆了，本文並不打算詳細講述如何使用JSValidation框架，有興趣的朋友可以去http://www.cosoft.org.cn/projects/jsvalidation JSValidation的官方網站自己去學習。

雖然運用這框架已經可以很好的完成客戶端驗證代碼的編寫，並且提供了dtd文件進行xml文件的，但是手動編寫xml文件還是很容易出錯，效率比較低，而且新的開發人員還要掌握一個全新的框架，不宜於開發人員入門。
像Struts或JSF這樣的框架大都需要爲表單寫一個類似FormBean的東西，以JSF爲例，假如表單內有一文本框<input type=”text” name=”txtUsername” />，那麼對應的Page類或叫FormBean類就應有如下代碼：
private HtmlInputText txtUsername = new HtmlInputText();
/**
* @return 用戶名
*/
public HtmlInputText getTxtUsername ()
{
    return txtUsername;
}
/**
 * @param text
 */
public void setTxtTeaName(HtmlInputText text)
{
    txtTeaName = text;
}
如果可以利用xDoclet，那麼，就可以自動生成JSValidation的配置文件了，而且還利於培訓新的開發人員，再加入ant task還可以形成每日構建。想象的代碼應該是下面這個樣子：
/**
 * @javascript.field
 * name="frmZBAddGlobalPage:txtTeaName"
 * display-name="用戶名"
 * 
 * @javascript.depend
 * name="required"
 *
 * @return用戶名
 */
 public HtmlInputText getTxtUsername()
 {
     return txtUsername;
 }
通過分析xDoclet自帶的一些標籤包，發現只需要提供三個文件即可實現自定義xDoclet標籤：一個繼承於XmlSubTask的類，一個繼承於DocletTask的類（用於ant），一個xdt的模板語言文件即可。

在XmlSubTask類中，首先，定義模板文件名：
private static String DEFAULT_TEMPLATE_FILE =
        "resources/validation-config.xdt";
定義dtd文件名：
private final static String DTD_FILE_NAME_20 =
        "resources/validation-config.dtd";
定義要生成的配置文件名：
private static String GENERATED_FILE_NAME = "validation-config.xml";

然後只需將三個文件組合起來既可，詳細代碼如下：
public JavascriptSubTask()
    {
        setTemplateURL(getClass().getResource(DEFAULT_TEMPLATE_FILE));
        setDestinationFile(GENERATED_FILE_NAME);
    }

    public void execute() throws XDocletException
    {
        setDtdURL(getClass().getResource(DTD_FILE_NAME_20));
        startProcess();
    }

    protected void engineStarted() throws XDocletException
    {
        System.out.println(
            Translator.getString(
                XDocletMessages.class,
                XDocletMessages.GENERATING_SOMETHING,
                new String[] { getDestinationFile()}));
    }
要想ant可以使用，只需要以下簡單的代碼：
/*
 * 創建日期 2004-4-26
 */
package paradise.xdoclet.modules.javascript;

import xdoclet.DocletTask;

/**
 * @author 清風
 */
public class JavascriptDocletTask extends DocletTask
{
    public JavascriptDocletTask()
    {
        addSubTask(new JavascriptSubTask());
    }
}
在ant中按如下方式定義：
<target name="javascript" depends="jxdoc_init" description="Generate javascript validation-config">
        <javascriptdoclet destdir="${jsp}/javascript">
            <fileset dir="${src}">
                <include name="**/zaibian/*.java"/>
            </fileset>
        </javascriptdoclet>
</target>

接下來，也是最核心的部分，就是有關xdt模板語言，xdt文件可以說是自定義xDoclet標籤的最重要的文件之一，以JavaScriptxDoclet爲例，簡單介紹一下xdt模板語言：
<XDtClass:forAllClasses>    遍歷所有含有標籤的類（在ant中指定）
<XDtMethod:forAllMethods>    遍歷當前類的所有方法
<XDtMethod:ifHasMethodTag tagName="javascript.form">    如果遍歷到的方法中含有指定的標籤
<XDtMethod:forAllMethodTags tagName="javascript.depend">    遍歷當前方法的所有標籤
更多的模板語言，參考xDoclet的.XDT文檔，都是很好理解的模板語言。

接下來，開始自定義自己的標籤，新建一個xtags.xml文件，加上開頭
<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE xdoclet PUBLIC "-//XDoclet Team//DTD XDoclet Tags 1.1//EN" "http://xdoclet.sourceforge.net/dtds/xtags_1_1.dtd">
然後寫下所有自定義的標籤，例如：
<xdoclet>
    <namespace>
        <name>javascript</name>
        <tags>
            <tag>
                <level>method</level>
                <name>javascript.form</name>
                <usage-description>Form</usage-description>
                <condition type="method"/>
                <parameter type="text">
                    <name>id</name>
                    <usage-description>Form id</usage-description>
                    <mandatory>true</mandatory>
                </parameter>
                <parameter type="text">
                    <name>show-error</name>
                    <usage-description>Form Error Display</usage-description>
                    <mandatory>true</mandatory>
                </parameter>
                <parameter type="text">
                    <name>onfail</name>
                    <usage-description>Form Error Run Custom Javascript Function</usage-description>
                    <mandatory>false</mandatory>
                </parameter>
            </tag>
        </tags>
    </namespace>
</xdoclet>
注意幾個地方：
“<level> method </level>”代表該標籤出現在方法上而不是類之上。例如
/**
*@javascript.form
*name=”test”
*/
public String getXXX()
{
}


最後就是將這些文件打成jar，其放置目錄分別是：
根目錄
|
|--META-INF/xtags.xml
|
|--源代碼
|----|
|----|--resources/*.xdt,*.dtd