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>