铁手剑谱

第1.8式. 使用XDoclet 产生Struts配置文件

问题

当你修改或者新建一个Action 或ActionForm时，你需要修改对应的Struts 配置文件。

动作要领

使用XDoclet 工具，配合Ant，来处理Java代码中可以自动产生truts-config.xml文件的注解。

动作变化

现在的大多数应用软件系统都有可执行代码文件文本配置文件组成。这种方式可以使你更容易的在各种不同的环境之间移植，并且减少必须针对各种不同部署而修改的代码量。但是它带来了另外一个负担，那就是保持代码和配置文件之间的一致性。

XDoclet 工具，原本开发来是针对EJB的开发，它就可以解决这个问题。通过XDoclet，开发者能够在代码中放置能够描述与代码相关的配置属性的注解，这些注解非常类似于JavaDoc 标签。在构建时，你可以使用定制的Ant 任务，由它来使用XDoclet 从而处理这些标签并产生对应的XML 配置文件。

对Struts来说，XDoclet 可以产生struts-config.xml文件中的下列元素：

• action 元素
• form-bean 元素

另外， XDoclet 还可以创建字段级的Struts Validator 配置，通常是位于validation.xml 文件之中。最后，如果你要映射EJB 实体Bean的属性到Struts ActionForms, XDoclet 可以不产生ActionForm 的Java 源代码。

首先，你需要添加一个任务到你的Ant 的build 脚本文件中，该任务可称为XDoclet 任务。Example 1-9展示了一个为struts-example 应用产生struts-config.xml 文件的Ant任务。

Example 1-9. Webdoclet Ant target

<target name="webdoclet" depends="init">
  <taskdef 
      name="webdoclet"
      classname="xdoclet.modules.web.WebDocletTask"
      classpathref="project.class.path"/>
  <webdoclet
      mergedir="${merge.dir}"
      destdir="${generated.xml.dir}"
      excludedtags="@version,@author"
      force="${xdoclet.force}">
    <fileset dir="${src.dir}">
      <exclude name="**/*Registration*.java"/>
      <include name="**/*.java"/>
    </fileset>
    <strutsconfigxml
            version="1.1"/>
  </webdoclet>
</target>

这个目标（target）调用webdoclet 定制Ant任务，它是由XDoclet提供的。此任务可以产生多个Web应用相关的工件，包括 web.xml 文件， struts-config.xml 文件，validation.xml 文件。对Struts 应用来说，你可能不需要产生web.xml 文件；因为对Struts 应用，该文件并不经常改变。在Example 1-9中，webdoclet 任务被用于产生struts-config.xml 文件。

并不是所有的struts-config.xml 文件中的元素都可以或者应该从注解的代码中产生。像全局forward, 全局例外处理，消息资源，插件等都并不和特定的Action 或ActionForm 类相关。

XDoclet 是通过让你在位于特定的目录中的文件中放置静态配置来处理这些事情的。在构建时， XDoclet 将这些文件中代码中产生的元素进行合并。你可以通过mergedir 属性来指定这些静态文件的位置。destdir 属性则指定将创建的文件的存放目录。通常，你需要为这些产生的文件创建一个单独的目录，然后在其成功创建后将它们拷贝到适当的目录中一共打包或者部署。excludedtags 属性指定排除在XDoclet 处理之外的JavaDoc 标签。

最后， force 属性强制XDoclet 产生一个新的配置文件。如果这个属性为false, 新文件只有在对应的注解Java代码发生改变时才会产生。

fileset 元素告诉XDoclet 要处理哪些Java 源文件。你可以使用该元素来指示那个源文件包含XDoclet 注解。例如，struts-example 应用使用了两个Struts 配置文件：struts-config.xml 和 struts-config-registration.xml。如Example 1-9所示，你可以通过设置fileset元素来排除包含名称"Registration"的类从而排除放入struts-config-registration.xml 文件中的元素。

strutsconfigxml 元素指示XDoclet 产生struts-config.xml 文件。XDoclet 默认情况下将产生Struts 1.0兼容的配置文件。因此，如果你用Struts1.1你必须指定版本为"1.1"。XDoclet 也使用该属性提供对Struts 1.2 的支持。

一旦你在构建文件中创建了这个target，你就可以添加注解到Action 和ActionForm 类的代码中。对ActionForm, XDoclet 提供了@struts.form 标签来产生form-bean 元素。下面的代码展示了如何在struts-example 应用的SubscriptionForm中使用这个类一级的标签：

/**//**
 * 用于用户概要页面的
 *
 * @struts.form 
 *    name="subscriptionForm"
 */

public final class SubscriptionForm extends ActionForm  {
  
}

在webdoclet target 被执行时，将在struts-config.xml 中产生下面的form-beans 元素：

 <!-- ========== Form Bean Definitions =================================== -->
  <form-beans>
    <form-bean
      name="subscriptionForm"
      type="org.apache.struts.webapp.example.SubscriptionForm"
    />

    <!--
         If you have non XDoclet forms, define them in a file called
         struts-forms.xml and place it in your merge directory.
    -->
  </form-beans>

XDoclet 使用你在标签中指定的名称来产生form-bean 元素，并且使用ActionForm 的权限定类名来创建type 属性。这一特征也是XDoclet最大的优点之一。你的类的属性，比如类名、包名、方法名等，对XDoclet 都可使用，就像它们被用于产生Javadocs 一样。XDoclet 将在产生的文件的适当位置使用这些值。

你可以使用XDoclet 来从Action类中产生action 元素。XDoclet 使用@struts.action 标签来指定action 元素。另外，@struts.action-forward 标签则可以指定嵌套的forward 元素。同时@struts.action-exception标签可以用于产生action特定的宣称性例外处理。struts-example 中的LoginAction.java 类示于下方，其中还包括产生完整的action元素所需的注解：

/**//**
 * Implementation of <strong>Action</strong> that validates a user logon.
 * 
 * @struts.action
 *    path="/logon"
 *    name="logonForm"
 *    scope="session"
 *    input="logon"
 * 
 * @struts.action-exception
 *    key="expired.password"
 *    type="org.apache.struts.webapp.example.ExpiredPasswordException"
 *    path="/changePassword.jsp"
 */
public final class LogonAction extends Action {
  
}

标签中的语法必须严格匹配对应的XML元素的语法。如果你已经有定义了的 struts-config.xml 文件，一个好办法是将struts-config.xml中的XML元素剪切粘贴到Action 类中。使 XDoclet 能够认可这些标签作必要的修改。下面位于LogoffAction.java 文件中的注解展示了如何使用@struts.action-forward 标签：

/**//**
 * Implementation of <strong>Action</strong> that processes a
 * user logoff.
 *
 * @struts.action
 *    path="/logoff"
 * 
 * @struts.action-forward
 *    name="success"
 *    path="/index.jsp"
 */

public final class LogoffAction extends Action {
  
}

虽然XDoclet 对产生struts-config.xml 文件大有帮助，它也并不是万能的。某些action 元素并不与任何你创建的Action 类相对应。例如，struts-example 应用中就包含下面的action mapping：

<action path="/tour"
     forward="/tour.htm">
</action>

struts-config.xml 文件可以包含全局forwards, 全局例外， controller 元素，消息资源元素以及plug-in 元素。XDoclet 不能产生这些元素。但是它可以和饱含这些配置元素的文件进行合并以产生完整的struts-config.xml 文件。Table 1-5列出了在创建struts-config.xm文件时XDoclet希望在mergedir属性指定的目录中找到的文件清单。

大多数开发者都认为， XDoclet 对Struts 开发并不像他用在EJB 开发那么能干。比如，如果你在struts-config.xml中主要使用动态action forms ，那么从ActionForm 中产生form-bean 元素并不会为你带来任何好处。但是，如果你开发一个具有大量action元素的大型应用，并使用Ant, 那么 XDoclet 则是值得考虑的。XDoclet 也支持其它类型的配置文档，比如Hibernate mappings的生成。

相关招式

第1.7式提供了一个模版Ant build 脚本，你可以在其中添加XDoclet target。

关于XDoclet 的详细信息访问http://xdoclet.sourceforge.net.

你也可以阅读Manning 出版Craig Walls和Norman Richards所著的Xdoclet in Action ，其中包括Xdoclet在Struts, Webwork, JDO, EJB,JMX, SOAP，Web Service 等方面开发的应用。http://www.manning.com/walls