一、什么是XDoclet

XDoclet從Rickard Oberg創(chuàng)建的EJBDoclet工具發(fā)展而來，它的設想很簡單：避免為每個EJB提供多個文件，而是從單一Bean類文件中提供組件需要的所有信息,。那么,，這是如何實現(xiàn)的呢？Java沒有.NET吹噓的“屬性”，但Java有Javadoc標記。我們可以把一個特殊的@標記放入Javadoc注釋，然后讓一個Doclet工具處理這些標記,。由工具為指定的Bean生成合適的XML描述器文件和接口文件。XDoclet建立在EJBDoclet思想的基礎上,，但適用范圍不再局限于EJB?，F(xiàn)在，我們已經(jīng)可以用XDoclet生成Web服務,、Web應用描述器,，甚至還可以對它進行擴展，滿足自己的特殊需要,。

@標記有一個標準的格式,，包含一個“名稱空間”以及一個屬于該名稱空間的“標記名稱”。標記的屬性以“名字=值”的形式在標記中指定,。下面是一個例子：

/**

* @namespace:tag name="value" name2="value2" ...

*/

當前可用的名稱空間包括：

ejb

標準的EJB信息（非廠商私有的信息）

jboss

面向JBoss應用服務器的信息,。

weblogic

面向BEA Weblogic應用服務器的信息。

webSphere

面向IBM WebSphere應用服務器的信息,。

orion

面向Orion應用服務器（Oracle）的信息,。

castor

為Castor框架生成映射信息。

mvcsoft

為MVCSoft EJB 2.0持久化管理器生成文件,。

soap

生成SOAP描述器,。

struts

生成struts-config.xml。

web

為Web應用生成web.xml配置文件,。

jsp

生成標記庫擴展描述器信息,。

從上面的清單可以看出，除了EJB之外,，XDoclet還提供了許多其它方面的支持（因此它的名字也從EJBDoclet變成了XDcolet）。

二、用Javadoc標記標注會話Bean

前面我們討論了XDoclet工具的基本情況,，下面來看一個實例,。我們從一個會話EJB開始。這個EJB是XBeans框架的一部分,，但對于本文來說,，Bean有什么樣的功能其實無關緊要。我們關心的是如何在Bean類的基礎上,，用Javadoc標記進行適當?shù)臉俗?，然后用XDoclet生成我們需要的各種文件。

ReceiverBean.java文件包含了一個documentReady(Document doc)方法,，這個方法接收一個DOM文檔并把它傳遞給鏈上面的下一個XBean,。

2.1 在類這一級上的定義

在類這一層次上，我們必須定義：

聲明Bean的類型,，本例是無狀態(tài)會話Bean,。

JNDI名稱。

環(huán)境變量,。

面向廠商的信息（例如WebLogic 緩沖池信息）,。

2.1.1 @ejb:bean標記

該標記唯一必需的屬性是把Bean的名字告訴XDoclet。此外,，我們還將定義Bean的類型,、JNDI名稱和顯示的名稱（display-name）：

/**

* This is the EJB Receiver Xbean

*

* @ejb:bean type="Stateless"

* name="ejbReceiver"

* jndi-name="org.xbeans.ejb.receiver.Receiver"

* display-name="EJB Receiver Xbean"

*

* ... 其他javadoc標記 ...

*/

public class ReceiverBean implements SessionBean, DOMSource {

ejb:Bean標記最常用的屬性是：

name

EJB的名字（用于描述器）。

type

定義Bean的類型,。對于會話Bean,，Bean的類型是Stateful或者Stateless；對于實體Bean,，它是CMP或BMP,。

jndi-name

提供Bean的JNDI名字，它將被用于廠商私有的部署描述器（用于遠程接口）,。

local-jndi-name

與jndi-name相同,，但用于本地接口。

view-type

表示應當支持哪一種Bean的“視圖”,?？梢允莚emote或local，或者both,。

要查看所有標記的完整說明,，請訪問XDoclet的文檔。

2.1.2 @ejb:env-entry標記

這個標記定義了將在JNDI中通過java:comp/env上下文配置的環(huán)境變量,。下面我們將定義一個環(huán)境變量,，Bean用它來查找鏈上面的下一個XBean：

/**

* This is the EJB Receiver Xbean

*

* ... 其他javadoc標記 ...

*

* @ejb:env-entry name="channelBean" type="java.lang.String"

* value="com.your.ChannelBean"

*

* ... 其他javadoc標記 ...

*/

public class ReceiverBean implements SessionBean, DOMSource {

2.1.3 @weblogic:pool標記

下面我們將配置面向特定廠商的緩沖池特征,，為便于討論，我們將使用WebLogic,。為表示聲明僅對特定廠商有效,，我們先聲明weblogic名稱空間：

/**

* This is the EJB Receiver Xbean

*

* ... 其他javadoc標記 ...

*

* @weblogic:pool max-beans-in-free-pool="1000"

* initial-beans-in-free-pool="10"

*

* ... 其他javadoc標記 ...

*/

public class ReceiverBean implements SessionBean, DOMSource {

這個標記將在面向WebLogic的部署描述器（weblogic-ejb-jar.xml）中配置緩沖池參數(shù)。

還有其他許多類這一級的標記,，這些標記使得我們能夠調整任何可以在部署描述器中指定的選項,。下面概要地介紹了可能在部署過程中要用到的一些“標準”標記：

@ejb:bean：唯一必需的標記，配置有關Bean的基本信息,。

@ejb:home：提供有關Home接口的信息,。可以要求XDoclet擴展一個定制的接口,，或者把接口放入指定的包,，等等。

@ejb:interface：類似于home標記,，但用來配置與組件接口（遠程的和/或本地的）有關的信息,。

@ejb:finder：在實體Bean Home接口上定義查找器方法。

@ejb:select：在實體Bean Home接口上定義select方法,。

@ejb:pk：為實體Bean定義主鍵,。XDoclet能夠生成主鍵類。

@ejb:data-object：數(shù)據(jù)對象（也就是值對象）可以通過這個標記自動生成,。

@ejb:ejb-ref：配置EJB引用,。

@ejb:ejb-external-ref：配置對其他應用中的EJB的引用，這里必需指定Bean的類型等信息,。

@ejb:resource-ref：配置資源引用,。

@ejb:security-role-ref：配置安全角色引用。

@ejb:transaction：為當前Bean的Home接口和Remote接口中的所有方法定義事務屬性,?？梢酝ㄟ^為單個方法提供的事務標記覆蓋。

@ejb:permission：允許role-name中指定的角色調用該Bean的Home接口和Remote接口中的所有方法,。

@ejb:security-identity：指定是否用調用者的安全標識符執(zhí)行EJB的方法,，還是用另外一個特定的安全標識符。

2.2 在方法這一級上的定義

下面我們來看看方法級的標記,。要讓某個方法成為遠程接口的一部分,，我們只需通過一個方法級的標記告訴XDoclet：

/**

* The method that the sender uses to pass the Document

*

* @ejb:interface-method view-type="remote"

*/

public void documentReady(Document incomingDocument) {

這個標記經(jīng)常要用到。一般地,，我們依次檢查Bean類里面每一個方法,，如果某個方法應該讓客戶程序調用，則在該方法聲明的前面加上這個標記,。如果希望客戶程序通過本地接口訪問這個方法,，只需把view-type值改成local就可以了,。

下面是另外幾個常用的EJB方法級的標記：

@ejb:relation：為EJB 2.0 CMP實體Bean定義一個關系。

@ejb:home-method：把方法定義為ejbHome*方法,。

@ejb:pk-field：標示主鍵域,。

@ejb:transaction：為當前的方法定義事務行為（指定一個合法的事務屬性：NotSupported，Supports,，Required,RequiresNew，Mandatory,，或者Never）,。

@ejb:permission：定義方法的許可權限（給出一個允許訪問該方法的角色的列表，用逗號分隔）,。

三,、運行XDoclet

現(xiàn)在我們完成了為ReceiverBean.java加上XDoclet標記的工作。下面我們要運行XDoclet,，讓它為我們生成所有部署B(yǎng)ean時需要的文件,。運行XDoclet工具最好的方式是通過Jakarta-Ant進行。Ant是一個廣泛應用的Java構造系統(tǒng),，現(xiàn)在幾乎每個人都在用它,。關于Ant的詳細說明，請參見Jakarta 網(wǎng)站,。

XDoclet的作者為我們編寫好了可以直接放入Ant構造文件（build.xml）的Ant任務,。任務主要分兩類：ejbdoclet和webdoclet。由于我們正在處理的是一個EJB,，下面我們來仔細地分析一下build文件里面的ejbdoclet部分：

<target name="ejbdoclet" depends="prepare">
<taskdef name="ejbdoclet"
classname="xdoclet.ejb.EjbDocletTask"
classpath="${java.class.path};${xdoclet.jar.path};
${log4j.jar.path};${ant.jar.path}"/>

<ejbdoclet sourcepath="${java.dir}"
destdir="${generated.java.dir}" ejbspec="2.0">

<fileset dir="${java.dir}">
<include name="**/ReceiverBean.java" />
</fileset>

<remoteinterface/>
<homeinterface/>
<deploymentdescriptor destdir="${build.dir}/ejb/META-INF"/>

<jboss destdir="${build.dir}/ejb/META-INF"
version="2.4" xmlencoding="UTF-8" />
<weblogic destdir="${build.dir}/ejb/META-INF"
xmlencoding="UTF-8"
validatexml="true"/>
<webSphere destdir="${build.dir}/ejb/META-INF" />
<orion destdir="${build.dir}/ejb/META-INF" />

</ejbdoclet>
</target>




這個文件片段包含了大量的信息,，因此我們要把它分解開來，逐條討論,。

3.1 <taskdef>標記

首先,，我們要告訴Ant構造系統(tǒng)有關<ejbdoclet/>標記的信息。我們定義了標記的名稱,，指定了實現(xiàn)該標記的類以及可供使用的CLASSPATH,。在這里，我們利用了在build.xml文件的前面設置的指向各個庫文件的屬性：


<taskdef name="ejbdoclet" classname="xdoclet.ejb.EjbDocletTask"
classpath="${java.class.path};${xdoclet.jar.path};${log4j.jar.path};
${ant.jar.path}"/>




3.2 <ejbdoclet>標記

最外面的標記<ejbdoclet>告訴Ant運行EJBDoclet任務,。我們在<ejbdoclet>標記中指定了代碼的位置,，在哪里生成XML描述器，以及我們遵從的EJB規(guī)范版本（同樣,，這里也使用了前面定義的屬性）：


<ejbdoclet
sourcepath="${java.dir}"
destdir="${generated.java.dir}"
ejbspec="2.0">




3.3 <fileset>標記

<fileset>指令告訴<ejbdoclet>到哪里去尋找Bean代碼,。本例將在${java.dir}的子目錄下尋找ReceiverBean.java：


<fileset dir="${java.dir}">
<include name="**/ReceiverBean.java" />
</fileset>




3.4 標準標記：接口和XML部署描述器

接下來的這組標記將確保XDoclet生成Remote接口、Home接口和標準XML部署描述器（ejb-jar.xml）：


<remoteinterface/>
<homeinterface/>
<deploymentdescriptor destdir="${build.dir}/ejb/META-INF"/>




3.5 面向廠商的標記：接口和XML部署描述器

最后一組標記用來生成面向廠商的部署描述器,。如果只在一種服務器上部署EJB,，我們只需設置一項即可,。但這里我們假設要讓Xbean EJB能夠部署到盡可能多的廠商的應用服務器上，所以要加入所有廠商的標記,。能夠在不了解這些應用服務器具體細節(jié)的情況下生成各種面向特定供應商的文件,，真是一件美妙的事情！


<jboss destdir="${build.dir}/ejb/META-INF"
version="2.4" xmlencoding="UTF-8" />
<weblogic destdir="${build.dir}/ejb/META-INF"
xmlencoding="UTF-8"
validatexml="true"/>
<webSphere destdir="${build.dir}/ejb/META-INF" />
<orion destdir="${build.dir}/ejb/META-INF" />




現(xiàn)在,，要為Xbean EJB生成各種文件,，我們只需在build文件所在的目錄執(zhí)行Ant。運行Ant時必須保證Ant的庫文件（ant.jar,，jaxp.jar和XML解析器）以及xdoclet.jar文件都在CLASSPATH中,。例如，假設在Windows環(huán)境中：


% set CLASSPATH=%CLASSPATH%;c:/lib/ant.jar;c:/lib/jaxp.jar;c:/lib/xerces.jar;
c:/lib/xdoclet.jar;c;/lib/log4j.jar;c:/lib/ejb.jar

% ant ejbdoclet




請參見本文下載代碼中完整的build.xml文件,。

四,、XDoclet的可擴展性

XDoclet具有很好的可擴展性。按照XDoclet的構造方式,，我們可以修改描述器文件和接口文件的輸出結果,，通過它的簡單的模板機制，我們還可以創(chuàng)建出自己的輸出,。每一個輸出文件有一個對應的模板文件,，模板文件以“.j”為擴展名，打開xdoclet.jar包可以看到許多這類摸板文件,。每一個摸板文件包含一組XML標記,，從這些XML標記簡單的邏輯很容易推測出摸板的輸出結果。下面是一個從現(xiàn)成EJB模板取出的簡單例子,，它將輸出從@ejb:bean display-name屬性取得的Bean的顯示名字：

<display-name>
<XDtClass:classTagValue tagName="ejb:bean"
paramName="display-name"/>
</display-name>




classTagValue XML標記為顯示指定標記的屬性提供了一個簡單的接口,。還有其他一些標記，比如支持循環(huán),，允許檢查某個標記是否存在,，等等。不論是調整輸出結果還是創(chuàng)建新的模板,，XDoclet都提供了相應的支持,。

在前面的例子中，會話Bean利用@ejb:env-entry標記把環(huán)境變量channelBean的值設置為com.your.ChannelBean,。我們是否真地想要在Bean類里面以硬編碼的方式指定這類信息呢,？應該不是。這里我們有兩種選擇：一種方案是在Ant的build腳本里面定義這個值,。然后,，如果部署時需要修改這個值，我們可以修改屬性,，再返回Ant,。要進行這種修改,，我們首先調整build.xml文件：


<property name="env-channelBean"
value="com.my.ChannelBean" />




然后修改Bean類文件：


/**
* @ejb:env-entry name="channelBean" type="java.lang.String"
* value="${env-channelBean}"
*/




另外一種方案是利用合并點（Merge Point）。EJB環(huán)境變量有一個合并點,，允許我們利用該能力加入自己的環(huán)境變量（類似于C語言的#include指令）,。只要創(chuàng)建一個ejb-entries-<ejbName>.xml文件，模板機制就會引用它,，它的內容將在最后輸出的ejb-jar.xml中出現(xiàn),。

結束語：本文探討了如何用XDoclet輔助EJB開發(fā)。XDoclet是一個免費的,、源代碼開放的工具,，能夠簡化EJB開發(fā)過程，允許我們用單個Bean類文件包含所有Bean需要的信息,，自動生成接口文件和描述器文件。XDoclet正在不斷地發(fā)展,，它的用途不再局限于EJB,。能夠標示出那些希望能夠通過SOAP使用的方法、配置Web應用（即使是用于Struts）無疑令人興奮,，但隨著時間的發(fā)展,，更多的功能將不斷涌現(xiàn)，甚至還有一些工具能夠用來生成XDoclet標記,，例如Middlegen code generation tool for EJB 2.0 Entity Beans,。

下載本文的代碼：JavaXDoclet_code.zip。