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>