David,
The following is an excerpt from an upcomping book I am working on. My
apologies about the ugly formatting -- it's cut and pasted from MS-Word.
Erik Hatcher also wrote an article that can be found at
http://www.ftponline.com/javapro/2003_07/online/ehatcher_07_18_03/.
- Bill Siggelkow
---
It is common place for modern software applications to be composed of
both executable code as well as text configuration files. While this
mechanism allows for greater ease of portability and deployment, it
places an additional burden on the developer to keep the code and the
configuration files consistent with each other.
The XDoclet tool, originally developed to address this issue with
respect to EJB development, addresses this problem. With XDoclet, the
developer places annotations in the code itself that is parsed and
processed at build time. The developer enters the comments as custom
Javadoc tags. XDoclet then processes these tags using custom Ant tasks.
For Struts, XDoclet can be used to generate the following elements for
the struts-config.xml file:
• action elements
• form-bean elements
In addition, XDoclet can create the field-level Struts Validator
configuration typically found in the validation.xml file. Finally, if
you are mapping properties of EJB Entity Beans to Struts ActionForms,
XDoclet can generate the ActionForm Java source code.
XDoclet can be downloaded from http://xdoclet.sourceforge.net. Follow
the installation instructions provided to install it. In addition, you
will need to have Ant installed as well.
First, you will need to add a task to your Ant build script to call the
XDoclet tasks. Example 1-9 shows an Ant target that can be used to
generate the struts-config.xml file for the struts-example web application.
Example 1-9. Webdoclet Ant target
name="webdoclet"
classname="xdoclet.modules.web.WebDocletTask"
classpathref="project.class.path"/>
mergedir="${merge.dir}"
destdir="${generated.xml.dir}"
excludedtags="@version,@author"
force="${xdoclet.force}">
version="1.1"/>
This target calls the webdoclet custom Ant task, provided by XDoclet.
This task can be used to generate several web-related artifacts
including the web.xml file, the struts-config.xml file, and the
validation.xml file. For Struts applications, the web.xml file does not
undergo frequent changes since all requests are routed through the
Struts ActionServlet. In Example 1-9, the webdoclet task is only being
used to generate the struts-config.xml file.
Not all elements of a struts-config.xml file can or should be based on
annotated source code. Portions of the file are relatively static and
will not change from one build to the next. To handle this situation,
the mergedir attribute is used to indicate the location of XML files
containing static Struts configuration elements that will be combined
with the generated elements at build time. The destdir attribute
specifies the location where the generated files will be created.
Generally, you want to create a separate directory for these files and
then copy the files into the appropriate directory for packaging and
deployment once they are generated. The excludedtags attribute
specifies JavaDoc tags that are to be excluded from processing by XDoclet.
It is common to exclude the @author and @version tags.
Finally, the force attribute indicates if XDoclet should always generate
new configuration files, or only generate new files if the classes have
changed.
The fileset element indicates to XDoclet the files that are to be
processed. Interestingly enough, the struts-example application uses
two Struts configuration files: the struts-config-registration.xml file
contains the Struts configuration specific to registration-related
features, while the struts-config.xml contains all other configuration
elements. In Example 1-9, the target generates only the
struts-config.xml file. Therefore, the fileset element excludes classes
that contain the name “Registration”.
The strutsconfigxml element indicates to XDoclet that the
struts-config.xml file should be generated. XDoclet generates a Struts
version 1.0-compliant file by default. Therefore, you must specify the
version as “1.1” if you are using Struts 1.1. It is anticipated that
XDoclet will provide support for Struts 1.2 via this attribute as well.
Once you have created this target in your build file, you can begin the
process of annotating your Action and ActionForm classes with the
appropriate tags. As when learning any new process or tool, it is best
to start simple. You can begin by simply adding the custom Javadoc tag
for generation of the form-bean element. XDoclet provides the
@struts.form tag for generation of a form-bean element. The following
code shows how
