9.13 Creating an XDoclet xdoclet.xml File

9.13.1 Problem

You need to create a new XDoclet xdoclet.xml file for a custom code generator.

9.13.2 Solution

Mark up your sub tasks with @ant.element tags and your tag handler classes with @xdoclet.taghandler tags. Add an Ant target to your buildfile that executes XDoclet's template subtask with XDoclet's xdoclet-xml.xdt template file.

9.13.3 Discussion

XDoclet 1.2 code generators require a deployment descriptor named xdoclet.xml. This file defines the namespace for an XDoclet tag handler class used in a template file, and defines the subtasks that are valid for a single XDoclet task. The file must exist in the meta-inf directory of your code generator's JAR file. The JAR file is known as an XDoclet module. Modules are discussed in more detail in the next recipe.

Example 9-14 shows how to mark up an XDoclet subtask. The only tag needed is an @ant.element tag. This tag defines two mandatory attributes: name and parent. The name attribute specifies the subtask name to use in the Ant buildfile. The parent attribute specifies the Ant XDoclet task that is allowed to execute the subtask. Remember that we do not need a subclass of xdoclet.DocletTask; therefore, we use DocletTask as the parent.

Example 9-14. Marked-up XDoclet subtask

/**
 * @ant.element
 *     name="junitperf"
 *     parent="xdoclet.DocletTask"
 *
 * @author Brian M. Coyner
 */

Example 9-15 shows how to mark up an XDoclet tag handler class. The only tag needed is an @xdoclet.taghandler tag with the mandatory attribute namespace. The namespace attribute tells the template file, which in our example is junitperf.xdt, the namespace to use when referencing this tag handler. Remember that template files, by convention, always include `XDt' as part of the namespace. You should never include `XDt' when defining the namespace here.

Example 9-15. Marked-up XDoclet tag handler

/**
 * @xdoclet.taghandler namespace="Perf"
 *
 * @author Brian M. Coyner
 */
public class JUnitPerfTagHandler extends XDocletTagSupport {

Now that our files are marked up, we need to generate the xdoclet.xml file. Example 9-16 shows how to use XDoclet's xdoclet-xml.xdt template file^[8] to generate the xdoclet.xml file for the JUnitPerfDoclet code generator. This example is similar to the example in Recipe 9.8. The only major difference is the template file being used.

^[8] As of XDoclet 1.2 beta, the xdoclet-xml.xdt template file is not available in the binary distribution. You will need to download the source distribution and look in the src/modules directory for this file.

Example 9-16. Generating the xdoclet.xml file

<target name="generate.xdoclet.xml">
  <taskdef name="xdoclet" classname="xdoclet.DocletTask">
    <classpath>
      <pathelement path="${env.XDOCLET_HOME}/lib/xdoclet.jar"/>
      <pathelement path="${env.XDOCLET_HOME}/lib/xjavadoc.jar"/>
      <pathelement location="${dir.lib}/commons-logging-1.0.jar"/>
    </classpath>
  </taskdef>

  <xdoclet
      destdir="${dir.build}">

    <fileset dir="${dir.src}">
      <include name="**/perf/"/>
      <exclude name="**/perf/Test*.java"/>
    </fileset>

    <template
        templateFile="${dir.resources}/xdoclet-xml.xdt"
        destinationFile="xdoclet.xml"/>
  </xdoclet>
</target>

After executing this target, an xdoclet.xml file should exist in the build directory. Here is the generated file:

<?xml version="1.0" encoding="UTF-8"?>

<!--
<!DOCTYPE xdoclet-module PUBLIC "-//XDoclet Team//DTD XDoclet Module 1.0//EN" "http://
xdoclet.sourceforge.net/dtd/xdoclet-module_1_0.dtd">
-->

<xdoclet-module>
    <!--
    com.oreilly.javaxp.xdoclet.perf.JUnitPerfDocletSubTask
    com.oreilly.javaxp.xdoclet.perf.JUnitPerfTagHandler
    -->

    <taghandler
        namespace="Perf"
        class="com.oreilly.javaxp.xdoclet.perf.JUnitPerfTagHandler"/>

    <subtask
        name="junitperf"
        implementation-class="com.oreilly.javaxp.xdoclet.perf.JUnitPerfDocletSubTask"
        parent-task-class="xdoclet.DocletTask"/>
</xdoclet-module>

9.13.4 See Also

Recipe 9.10 shows how to create a custom Ant Doclet subtask to generate JUnitPerf tests. Recipe 9.11 shows how to create the JUnitPerfDoclet tag handler class to perform simple logic and generate snippets of code. Recipe 9.12 shows how to create a custom template file that uses the JUnitPerfDoclet tag handler. Recipe 9.14 shows how to package JUnitPerfDoclet into a JAR module. Chapter 8 provides information on the JUnitPerf tool and how to update your Ant buildfile to invoke JUnitPerfDoclet.