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
<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>
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 this class-level tag is used in the SubscriptionForm of the struts-example application:
/**
* Form bean for the user profile page…
*
* @struts.form
* name="subscriptionForm"
*/
public final class SubscriptionForm extends ActionForm {
…
}
When the webdoclet target is executed, the following form-beans element will be created in the generated struts-config.xml file:
<!-- ========== 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>
Note that you did not need to specify the type attribute, which corresponds to the fully-qualified class name of the ActionForm, in the custom tag. XDoclet generates this value for you. This feature is one of the greatest benefits of XDoclet. Attributes of your classes, such as class names, packages, and method names are available to XDoclet just as they would be when you generate Javadocs for your application. XDoclet then uses these values where appropriate for the files being generated.
If you change the class name or package of a class, XDoclet will automatically generate the correct configuration element without any other intervention. While IDE refactoring tools can be used to handle these types of changes, using XDoclet yields a solution that can be integrated with your existing Ant build process.
You can now you add the custom tags to generate action elements from your Action classes. XDoclet uses the @struts.action custom tag to allow for specification of the action element. In addition, the @struts.action-forward tag can be used to specify nested forward elements. Likewise, @struts.action-exception tag can be used to generate action-specific declarative exception handling. The LoginAction.java class of the struts-example application is shown below with the annotations required to generate the complete action element:
/**
* 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 {
…
}
Note how closely the syntax of the custom tags matches the syntax of the corresponding XML elements. If you already have your struts-config.xml defined, then a good approach for using XDoclet is to simply cut and paste the XML elements from the struts-config.xml file into the Action class. Then make the changes necessary for XDoclet to recognize the tags. Following is the annotated class comments in the LogoffAction.java file that shows use of the @struts.action-forward tag:
/**
* 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 {
…
}
While XDoclet can go along way to generating the struts-config.xml file, it cannot do everything. Some action elements do not correspond to Action classes that you create. For example, the struts-example application includes the following action mapping:
<action path="/tour"
forward="/tour.htm">
</action>
In addition, the struts-config.xml file may contain global forwards, global exceptions, a controller element, message resource elements, and plug-in elements. XDoclet does not generate these elements. However, it can merge files containing these elements with the generated file to produce a complete struts-config.xml file. Table 1-3 lists the files that XDoclet expects to find in the directory specified by the mergedir attribute when creating the struts-config.xml file.
Table 1-3. XDoclet Struts Config merge files
Merge File Used For
struts-data-sources.xml An XML document containing the optional data-sources element.
struts-forms.xml An XML unparsed entity containing form-bean elements, for additional non-XDoclet forms.
global-exceptions.xml An XML document containing the optional global-exceptions element.
global-forwards.xml An XML document containing the optional global-forwards element.
struts-actions.xml An XML unparsed entity containing action elements, for additional non-XDoclet actions.
struts-controller.xml An XML document containing the optional controller element.
struts-message-resources.xml An XML unparsed entity containing any message-resources elements.
struts-plugins.xml An XML unparsed entity containing any plug-in elements.
An added benefit of separating the Struts configuration into these separate files is that contention for these resources is reduced when developing in a team environment.
------------------------------------------------------------------------
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
