October 31, 2014
Hot Topics:
RSS RSS feed Download our iPhone app

Code Smarter, Not Harder, With XDoclet

  • October 31, 2003
  • By David Thurmond
  • Send Email »
  • More Articles »

XDoclet is a template-driven development tool that allows developers to generate code, configuration files, or even documentation. This article will demonstrate how to download, install, configure, and use XDoclet to take the drudgery out of writing J2EE code.

Tools

To use XDoclet, you will need the following:

  • Java 2 Standard Edition SDK
  • Apache Ant 1.4.1 or later
  • XDoclet 1.1.2 or later

Downloading

To get XDoclet, go to http://sourceforge.net/projects/xdoclet/. The latest production release is version 1.1.2, but version 1.2.0 Beta 3 is also available. You will also need Apache Ant, v1.4.1 or later, which is available at http://ant.apache.org/. The Java 2 Standard Edition SDK is also required, and can be downloaded from http://java.sun.com/.

Installation

To install XDoclet, unzip the file to a directory of your choice. By default, this directory will be named XDoclet-version. You will also need to configure several environment variables. First, CLASSPATH must contain the tools.jar file found in the lib directory of the Java 2 SDK distribution. Your system path must contain the bin directory of the Java 2 SDK distribution, so that XDoclet can invoke the standard javadoc creation tool. Also, the J2EE_HOME environment variable should be set. You also need to install Ant, and set the ANT_HOME environment variable to the location of the Ant installation. The Ant tool's bin directory must be included in the system path.

The following subdirectories are found within the XDoclet-version directory:

  • docs—The documentation for the XDoclet template tags and source code. The template docs, which are very important for creating a code generation template, can be found in docs/templates. If you wish to extend XDoclet's capabilities, the API documentation is in docs/api.
  • lib—Contains the XDoclet.jar file.
  • samples—Contains sample source code that uses XDoclet's predefined EJB, JSP, and Web tags.
  • src—Contains the source code for XDoclet.

Doclet Tags

XDoclet uses doclet tags within JavaDoc comments to provide information that is used within templates to generate code, configuration files, or documentation. Below is an example of a doclet tag.

/**
* @jsp:attribute name="color" required="false"
*/

In the doclet tag above, the value jsp is the namespace of the doclet tag; attribute is the tag name, and the name-value pairs name="color" and required="false" are parameters.

The namespace groups tags with similar functions together. Some examples are the ejb namespace, which includes many tags for EJB generation, and the jsp namespace, which includes tags for creating custom JSP tag code and configuration files.

The tag identifies one particular function within the namespace. For example, the ejb:bean tag is used to provide data for generating EJB home, remote, and local interfaces, as well as EJB deployment descriptor files. Tags must be unique within a namespace, but may be duplicated in different namespaces.

Parameters supply information for the doclet tag to use within code generation templates. A parameter could be used as a simple placeholder, or could tell a template to conditionally generate code. For example, in the doclet tag shown above, the parameters could be used as values within the taglib.tld file for the JSP tag.

XDoclet Templates

XDoclet templates contain the logic that the XDoclet template engine uses to generate code. By convention, template files end with a .j extension. Many examples are included within the XDoclet source code.

Each template contains a mixture of source code and template tags. There are two types of template tag; block tags and content tags. Content tags produce some type of content based on the parameters supplied. For example, the tag <XdtMethod:methodTagValue tagName="jsp:attribute" paramName="name"/> would insert the value "color" from the doclet tag example above into the code being generated.

Block tags generally perform some logical function, such as iterating through a list of classes, methods, or packages, or optionally generating code based on the parameters supplied. The tag pair <XdtClass:forAllClasses> ... </XdtClass:forAllClasses> would iterate through all of the classes, and would generate code specific to each class upon each iteration.

Generating Code

Once you have created a template, you must include a step in your build.xml file so that Ant can generate the code. A sample is shown below.

<target name="generate-tagdoc">
<taskdef name="tagdoc" classname="XDoclet.DocletTask"
         classpath="${XDoclet.jar.path};${log4j.jar.path};
                    ${ant.jar.path}" />
<tagdoc sourcepath="${java.dir}" destdir="${tagdoc.dir}"
        classpathref="compile.classpath"
        excludedtags="@version,@author,@return,@exception" >
  <fileset dir="${java.dir}">
    <include name="**/*Tag.java" />
  </fileset>
  <template templateFile="${template.dir}/tagdoc.j"
            destinationfile="{0}.html"/>
</tagdoc>
</target>

This user-defined Ant task instructs XDoclet to process source code in the java.dir for all source code that ends in Tag.java. The template file tagdoc.j will be used to generate code based on the doclet tags found in the source code, with the exception of @author, @version, @return, and @exception, which are excluded from being processed. The generated code will be placed in the tagdoc.dir directory, and will have the same package structure and filename as the source file, as designated by the token {0} in the output filename, but the output will have an .html extension. A single output file could also be specified, but using the {0} token in the output filename implies that the template engine should generate one single file per source file that is processed.





Page 1 of 3



Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Sitemap | Contact Us

Rocket Fuel