XDOCLET BEST PRACTICES in Java

Drawing Data Matrix 2d barcode in Java XDOCLET BEST PRACTICES

Javadoc comments are certainly the right place for a lot of information, but it is not appropriate for everything. For example, XDoclet has the capability to generate the Struts struts-config.xml based on @struts.action and @struts.form tags. In addition, a @struts.action-forward tag defines the local forwards. This could be seen as a major time saver to developers, but also oversteps the boundaries of Model-View-Controller in the Struts paradigm. In other words, a Struts Action should not know or care about the actual path(s) used. The moral of this story is that it is easy to get carried away with metadata. The point of a lot of common metadata, especially in Enterprise JavaBeans, is to actually separate information from the source code, such that the information bound at deployment time rather than build time. Often metadata needs to be pulled together from multiple places, some residing in @tags and some residing in external files. 12 demonstrates the use of merge points in an XDoclet template to accomplish the building of the infamous web.xml. This file contains servlet definitions that can be gathered from source code, but also allows for merging in the definition of third-party servlets.

Dependency checking While we are still waiting for XJavadoc to appear, we must make do with what we have. With XDoclet s current implicit reliance on Ant s <javadoc> task (which wraps Sun s javadoc command-line utility), the processing speed leaves a bit to be desired. Churning through Ant s own codebase and generating XML files for each of its tasks and a couple of properties files takes about 90 seconds. This is not the type of thing you would put on your main development build dependency graph. Internally, XDoclet does its own dependency checking, only regenerating files when needed, but it still goes through a lengthy javadoc phase to gather the complete model before deciding whether or not to regenerate files. There are a couple of solutions to this problem: Narrow the <fileset> processed by XDoclet to the smallest set of files necessary. Use <uptodate> to implement your own dependency checking and skip the entire process if the generated artifacts are newer than the source code.

The dependency checking capabilities of XDoclet will no doubt improve dramatically as it gains popularity and widespread use. Using <uptodate> In the build for our Ant task subproject, we can bypass the XDoclet step by checking all source file timestamps against the generated taskdef.properties file. The "init" target contains our timestamp check:

<uptodate property="taskdef.uptodate" targetfile="${build.classes.dir}/${taskdef.properties}"> <srcfiles dir="${src.dir}" includes="**/*.java"/> <srcfiles dir="${template.dir}" includes="taskdef.template"/> </uptodate>

Our "taskdef" target uses conditional target execution by specifying an unless clause:

The effect is that Ant only runs the XDoclet task when any file in the Java source is newer than our properties file. In a large project, we may want to be more selective in the patterns we pass to <uptodate>, so that Ant runs XDoclet only when relevant packages in the project have changed. In the example, we could restrict XDoclet to run only when files in the antbook.ant package were changed:

Why has XDoclet earned a complete chapter in a book on Ant XDoclet is a powerful build-time templating engine that provides access to Java code structure and metadata. At the time of writing, XDoclet was intertwined with Ant and was not a stand-alone utility. Even if it eventually becomes decoupled (and it should; tight code dependencies are bad!) from Ant s API, it will always be available as a set of Ant tasks. The primary use of XDoclet is to generate from a single source of metadata the necessary artifacts that are incorporated into a build distributable. Such uses include the generation of Property files Deployment descriptors Documentation Helper or adaptor Java code Other XML descriptor files

Being knowledgeable with XDoclet s capabilities is guaranteed to be a positive influence in your build process. Metadata should ideally only reside in a single source location and should be used to generate artifacts if necessary. By eliminating metadata duplication and placing it close to the source, developers can focus on business logic development rather than being bogged down with plumbing maintenance (Peltz 2000). SUMMARY 277