XDoclet 学习笔记二

XDoclet 学习笔记二

                               ----使用Xdoclet生成web.xml文件

•第一步︰定義 Servlet 元素

    第一步是在您的類別中把 servlet 元素定義為類別層級的 XDoclet JavaDoc 標示（如下所示）︰

... * @web.servlet name="BasicServlet"                   display-name="Basic Servlet"                   load-on-startup="1" ... */ public class BasicServlet extends HttpServlet {

     這段程式碼生成 web.xml 中 servlet 元素和子元素（如下所示）︰

<servlet>        <servlet-name>BasicServlet</servlet-name>        <display-name>Basic Servlet</display-name>       <servlet-class>rickhightower.servlet.BasicServlet</servlet-class> ...        <load-on-startup>1</load-on-startup>     </servlet>

     因為 XDoclet 工作的工作原理類似於 JavaDoc API，所以它像 JavaDoc API 為 JavaDoc 獲取完整的類別名稱那樣獲取 servlet 的完整的類別名稱。這不只有減少了輸入，還減少了犯錯誤的可能。後來，當您重構和決定變更類別名稱或 package 結構的時候，您不必手動地變更所有的部署描述子。

•第二步︰定義 Servlet 的初始參數

    在使用 Servlet 元素定義了 servlet 之後，您可以定義映射和初始參數。servlet-init-param被定義在 JavaDoc 註釋中（如下所示）︰

...   * @web.servlet-init-param name="hi" value="Ant is cool!"   * @web.servlet-init-param name="bye" value="XDoc Rocks!" ... */ public class BasicServlet extends HttpServlet {

     這些參數將生成部署描述子中的以下 >init-param>︰

<servlet>        <servlet-name>BasicServlet</servlet-name> ...        <init-param>           <param-name>hi</param-name>           <param-value>Ant is cool!</param-value>        </init-param>        <init-param>           <param-name>bye</param-name>           <param-value>XDoc Rocks!</param-value>        </init-param> ...     </servlet>

•第三步︰綜合應用 Ant 和 XDoclet 來設定元件

    您一般不願把初始化參數硬編碼到原始碼中。有關使用 <init-param> 的全部概念是使 Web 元件可被應用程式組譯器（application assembler）定製為 J2EE 應用程式。

    更好的方法是把初始參數設為指向類似 @bye@ 和 @hi@ 中的標示，然後使用啟用了過濾的 Ant 複製來為正確的應用程式傳遞正確的標示值。這裡假定您使用 Ant 來建置專案。

    您可以使用 Ant 過濾來把設定文件中的標示置換成它們在部署環境中的正確的值。過濾器是支援設定多個應用程式的 J2EE 元件的另一種方式。以下是根據條件來設定 web.xml 的範例 Ant 腳本︰

<project name="filtering" default="run">    <target name="spanishSetup" if="spanish">          <filter token="bye" value="adios"/>          <filter token="hi" value="hola"/>    </target>    <target name="englishSetup" unless="spanish">          <filter token="bye" value="goodbye"/>           <filter token="hi" value="hello"/>    </target>    <target name="setup" depends="spanishSetup,englishSetup"/>    <target name="run" depends="setup">          <copy todir="${workspace}/WEB-INF" filtering="true">                <fileset dir="./WEB-INF"/>          </copy>    </target>   </project>

    在上面的 Ant 範例中，englishSetup 目標中的過濾器把 bye 標示設為 goodbye，而spanishSetup 目標中的過濾器把 bye 標示設為 adios。

    稍後，當腳本使用啟用了過濾的複製工作時，它把過濾器應用於複製任務指定的文件集中的所有的文件。若 spanish 屬性被設定，則啟用了過濾的複製任務把所有的字串 @bye@ 取代成為 adios，若spanish 屬性沒有被設定，則 goodbye。

更容易的方法…… 
    雖然這是解決這個問題的一個方法，但是還有更容易的方法。Ant 屬性可被用來設定 XDoclet 中的每個屬性值。因為您用 XDoclet Ant 任務來生成相關的文件，所以 XDoclet 可存取所有的 ant 屬性。因此，您可以這樣來設定值︰

... * @web.servlet-init-param     name="hi"    *                     value="${basic.servlet.hi}"   *    * @web.servlet-init-param     name="bye"    *                     value="${basic.servlet.bye}" ... */ public class BasicServlet extends HttpServlet {

    然後，當您生成 web.xml 時，hi 和 bye 初始化參數被設定成 Ant 建置腳本中設定的basic.servlet.hi 和 basic.servlet.bye 屬性的目前值。

•第四步︰定義 Servlet 映射

    XDoclet JavaDoc 標示也可被用來定義 servlet 映射（如下所示）︰

* @web.servlet-mapping url-pattern="/Basic/*"   * @web.servlet-mapping url-pattern="*.Basic"   * @web.servlet-mapping url-pattern="/BasicServlet" ... */ public class BasicServlet extends HttpServlet {

    這將生成 web.xml 中的以下項目︰

<servlet-mapping>        <servlet-name>BasicServlet</servlet-name>        <url-pattern>/Basic/*</url-pattern>     </servlet-mapping>     <servlet-mapping>        <servlet-name>BasicServlet</servlet-name>        <url-pattern>*.Basic</url-pattern>     </servlet-mapping>     <servlet-mapping>        <servlet-name>BasicServlet</servlet-name>        <url-pattern>/BasicServlet</url-pattern>     </servlet-mapping>

•第五步︰定義 J2EE 資源

    除了上述內容外，您可以在 web.xml 中為類似 JDBC 資料源的資源定義資源參照，甚至定義 ejb 參照。Java 文件在類別層級包括這些 XDoclet JavaDoc 樣式的標示（如下所示）︰

/** ...   * @web.resource-ref description="JDBC resource"   *                   name="jdbc/mydb"   *                   type="javax.sql.DataSource"   *                   auth="Container" ... */ public class BasicServlet extends HttpServlet {

     以上程式碼生成 web.xml 中如下元素︰

...     <resource-ref>        <description>JDBC resource</description>        <res-ref-name>jdbc/mydb</res-ref-name>        <res-type>javax.sql.DataSource</res-type>        <res-auth>Container</res-auth>     </resource-ref>

•如何生成它？

    以下是 build.properties 文件的清單︰

  
  
####### Change These for your environment##############
# This is where you installed xdoclet xdocletlib=/xdoclet/lib
# Change these for your app servers.
# This is the deployment directory.
webapps=/tomcat4/webapps
# This lib is where the ant script expects to find the j2ee jar files.
 lib=/tomcat4/common/lib
# You should not have to change these
 src=./src
 WEBINF=./web/WEB-INF
 dest=${WEBINF}/classes
 
 docroot=./web
 output=./tmp
 
 appname=webdoclet
 
# You may change these at will. These get used by the Servlet example.
 basic.servlet.bye=dude
 basic.servlet.hi=mom   
 <path id="cpath">
    <fileset dir="${lib}"/>
 </path>
     
 <path id="xdocpath">
    <path refid="cpath"/>
         <fileset dir="${xdocletlib}">
             <include name="*.jar"/>
         </fileset>
 </path>       
 <webdoclet destdir="${dest}">
    <fileset dir="${src}">
        <include name="**/*Servlet.java" />
    </fileset>
 
    <deploymentdescriptor servletspec="2.3" destdir="${WEBINF}" />
 </webdoclet>