A Simple Case for code generation

In one of the projects I previously worked on, business logic was encapsulated in command objects that were maintained in a command factory. The command factory would source it contents from an XML file (command-mapping.xml) that would maintain the 'command name command implementation class' mapping. So everytime somebody added a command to the source control, they also had to make sure that XML file is updated. Even if developers made sure that the XML and the implementation classes are in sync, a typo somewhere could result in errors and worse it wouldn't show up until the code is actually run. This is a typical case of duplication of information and XDoclet has been designed to solve such problems. If the command name (metadata) can be specified in the command class itself, XDoclet would take care of generating the XML file. Ofcourse, it would mean developing custom doclet tags to specify the metadata (command name) in the source file, a template that generates the required file and a plugin that ties everything together. The following section discusses the custom doclet tags that can be used to add metadata to the Command implementation classes.

Developing custom XDoclet tags

A Java Command interface specifies the contract for all concrete commands to implement. 'GetPurchaseOrderCommand' is one such implementation. It uses the @command.class tag with an attribute 'name' to specify its name. The 'command.class' tag could be expanded in the future to support more attributes. You might wonder that the '.class' part of the tag name could have very well been omitted. But consider this - currently we are accepting 'class' level tags. In the future we might want to specify metadata at method level too and the tag naming w'd'nt look too intuitive if the intent did'nt reflect in the tag name itself (we can have @command.method later).

package org.xdoclet.plugin.commands

/**
 *
 *
 * @command.class generate=false
 *
 */

public interface Command{
 public void execute(Object obj);
}

package org.xdoclet.plugin.commands;

/**
 * 
 * @command.class name="GetPurchaseOrder"
 *
 */

public class GetPurchaseOrderCommand implements Command{
 public void execute(Object obj){
  //business logic to execute retrieve Purchase Order
 }
}

Now that we know how our tag needs to look like, the next logical step would be to describe the same. It is typically specified through an interface that extends QDox DocletTag. The interface name is obtained by appending "Tag" to the desired tag name. A tag named 'command' translates to interface CommandTag while 'command.class' translates to CommandClassTag inteface. Note that java bean method naming conventions are used to specify the tag attributes. A Tag with attributes foo, bar are specified through methods getFoo and getBar on the interface respectively. Because of an internal naming conflict, tag attribute 'name' has to be specified with a trailing underscore :

getName_()!

package org.xdoclet.plugin.command.qtags;

import com.thoughtworks.qdox.model.DocletTag;

/**
 * This is a Custom Tag
 *
 * @qtags.location class
 * @qtags.once
 *
 */

public interface CommandClassTag extends DocletTag {
    /**
     * @qtags.required
     */

    String getName_();

    /** 
    * A Marker tag that indicates whether the source file 
    * needs to be processed or not
    */
    /**
     * @qtags.default true
     */

    String isGenerate();
}

The above code snippet indicates that the tag specification itself is carrying some meta information in the form of @qtags.xxxx tags!

Remember that we wanted the command.class tag to be specified only at the class level?. QDox allows us to specify this tag metadata in the form '@qtags' tags. There are quite a few available (http://xdoclet.codehaus.org/QtagsTags). In our case, the following 'qtags' tags allow us to specify the restrictions that we would like to impose on our custom tag (command.class tag) usage.

@qtags.location class - This specifies that the command.class tag can be specified at class level only. The other possible values are

method,constructor and field.

@qtags.once - This allows us to specify the tag cardinality - that the command.class tag can be specified only once in the source

file.

@qtags.required - that 'name' is a required attribute and must be specified when using the command.class tag.

Calling the custom tag that we just developed, a XDoclet tag is probably a misnomer. They are in fact QDox DocletTags. We are just creating another Javadoc like @tags for QDox to recognize when parsing the source file. We developed the interface but somebody has to provide an implementation. The tool does it for us through another XDoclet code generation plugin!. We just need to invoke the QTagImplPlugin from the build file.

<component classname="org.xdoclet.plugin.qtags.impl.QTagImplPlugin" destdir="src/java"/>

This instructs XDoclet to generate the concrete tag implementation classes for the Tag interfaces we developed. Now that we are done with developing custom tags, it is probably a good time to discuss another area where XDoclet2 improves upon the earlier version - tag validation.

Tag validation

A tag definition can specify the following -

• It can specify the location where it can be specified. Eg - It can be a 'class' /'method' / 'attribute' level tag.
• A tag attribute can dictate the valid values that can be specified - basically an enumeration of values
• A tag might indicate the number of times it can occur in the source file (cardinality?)
• It can assume a default value when not specified in the source

XDoclet2 greatly improves over XDoclet 1.x in the area of tag validation.

XDoclet 1.x does not warn you

• if you specify an incorrect tag name, attribute etc (for eg because of a typo) or
• if you specify a correct tag at the wrong location. The tag is probably supported at the class level. But by mistake you end up the specifying the tag at the method level.

Eg : Specifying the following on a bean method does not make much sense

public abstract class CustomerBean extends EntityBean{
     //..
                  
     @ejb.bean
	name="CustomerBean"
     public abstract String getName();
     //..

Note that it definitely makes sense at the bean 'class' level. Unfortunately XDoclet 1.x does not provide any feedback to the user regarding this error. It basically lacks a tag validation feature. XDoclet2 addresses this issue though. As we saw earlier, XDoclet often tends to eats its own dog food _ It generated the TagLibrary class for us by looking at our custom tag definitions. It also generated the tag validation routine transparently to the plugin developer. It translates all the validation rules we specified in the Tag interface into methods in the implementation class. QDox invokes these methods at the time of extracting the meta information (specified through @tags) from our source files.

At this stage we have developed the custom tag interface and xdoclet even generated the implementation classes for that. QDox needs to be made aware of it and the following section tells us how.

How to let XDoclet know of the custom tags

QDox understands and parses java source file retaining the precious metadata in the process.

So how does QDox know that you have just developed a custom tag and that it needs to look for that tag as well in the source file? - Well, its not magic ( we have already seen enough ) and it does'nt, unless ofcourse you register the tag with Metadata provider's DocletFactory.

Luckily, registering the tag is a trivial task.

Constructor of custom CommandPlugin that we just developed indicates that the class has dependencies on

1. JellyTemplateEngine
2. QDoxCapableMetadataProvider and
3. WriterMapper

Generama by default supports Jelly, Velocity and Freemarker for template scripting by providing respective TemplateEngine implementations _ JellyTemplateEngine, VelocityTemplateEngine and FreeMarkerTemplateEngine. Atleast for now, it looks like XDoclet2 is being used only for java/j2ee stack code generation. Generama recognizes this - it provides and registers QDoxCapableMetadataProvider with the DI container (Pico) by default and when it starts up, Pico does what it has been designed to do - wiring up dependencies.

So now that we have access to the MetaDataProvider, letting the provider know about our custom tags is simple. QDox Provider maintains a DocletFactory where it holds on to all the tag definitions. Registering the new tag with the DocletFactory can be done as follows. It simply binds the name of the Tag against the tag implementation class.

public class CommandPlugin extends QDoxPlugin {

   public CommandPlugin(JellyTemplateEngine jellyTemplateEngine, 
         QDoxCapableMetadataProvider metadataProvider,WriterMapper writerMapper) 
             throws ClassNotFoundException {
    //...
    //..
		
    //register a tag with the given name (command) and implementation class

    metadataProvider.getDocletTagFactory().registerTag("command.class",
             org.xdoclet.plugin.command.qtags.CommandClassTagImpl.class);

  }
}

So far this looks good. A cursory look at the EJB Plugin documentation (or for that matter Hibernate plugin documentation) will reveal that it supports a multitude of tags. As of today it supports close to 31 tags! Registering each of these one by one could quickly become tedious and redundant, worse we might even forget to register a tag with QDox, thereby losing out on the metadata specified by that tag. Would'nt it be good if we could just specify the tag interface and somehow the Provider gets to know about it automatically? It is anyways redundant code that nobody wants to write. Relax, we got help here. XDoclet does it for us...almost.

The following snippet from the build file registers the QTagLibraryPlugin utility with Generama. This component looks at all the DocletTag in the specified directory and generates a TagLibrary class. As the name indicates this class acts as a 'library' of DocletTags associated with a plugin and registers them with the provider.

<target name="gen.qtags.impl">

  <property name="xdoclet.qtags.namespace" value="command"/>

  <xdoclet>
   <fileset dir="src">
     <include name="**/*.java"/>
   </fileset>
   <component
      classname="org.xdoclet.plugin.qtags.impl.QTagImplPlugin"
      destdir="${basedir}/src"
   />    
   <component
    classname="org.xdoclet.plugin.qtags.impl.QTagLibraryPlugin"
        destdir="${basedir}/src"
        packagereplace="org.xdoclet.plugin.${xdoclet.qtags.namespace}.qtags"
   />
 </target>

public class TagLibrary{

  // The Constructor handles the job of registering the tags with the MetadataProvider

  public TagLibrary(MetadataProvider metadataProvider){

    metadataProvider.getDocletTagFactory ().registerTag ("dao.call",
                  org.xdoclet.plugin.ejb.qtags.DaoCallTagImpl.class);
    metadataProvider.getDocletTagFactory ().registerTag ("ejb.aggregate",	
                  org.xdoclet.plugin.ejb.qtags.EjbAggregateTagImpl.class);
    metadataProvider.getDocletTagFactory ().registerTag ("ejb.bean",
                  org.xdoclet.plugin.ejb.qtags.EjbBeanTagImpl.class);
    metadataProvider.getDocletTagFactory ().registerTag ("ejb.create-method",
                  org.xdoclet.plugin.ejb.qtags.EjbCreateMethodTagImpl.class);
    //..
    //..

You are just expected to instantiate this class from within your plugin. I guess that is not too much to ask given the amount of redundant work XDoclet has already handled for us. But it does look a little out of place in the code where it is used (a hanging reference).

public class ACustomPlugin extends QDoxPlugin {

   public ACustomPlugin(JellyTemplateEngine jellyTemplateEngine,
    	QDoxCapableMetadataProvider metadataProvider,
        WriterMapper writerMapper) throws ClassNotFoundException {
	
        //Custom Plugin Code...
				
        //Does'nt look nice, does it?			
        new TagLibrary (metadataProvider);
    }
}

Developing a Custom Plugin

package org.xdoclet.plugin.command;

import java.util.Collection;
import java.util.*;

import org.generama.JellyTemplateEngine;
import org.generama.QDoxCapableMetadataProvider;
import org.generama.WriterMapper;
import org.generama.defaults.QDoxPlugin;

import com.thoughtworks.qdox.model.JavaClass;
import com.thoughtworks.qdox.model.DocletTag;

import org.xdoclet.plugin.command.qtags.TagLibrary;

public class CommandPlugin extends QDoxPlugin {

  public CommandPlugin(JellyTemplateEngine jellyTemplateEngine,
         QDoxCapableMetadataProvider metadataProvider, WriterMapper writerMapper) 
                      throws ClassNotFoundException {

    super (jellyTemplateEngine, metadataProvider, writerMapper);
    setFilereplace ("command-mapping.xml");
    setMultioutput (false);
        
    /*The following line of code is a programmatic way of registering the tags*/

    /*metadataProvider.getDocletTagFactory ().registerTag ("command.class",
                      org.xdoclet.plugin.command.qtags.CommandClassTagImpl.class);*/

    /* xdoclet2 recommended way of registering custom tags*/

    new TagLibrary(metadataProvider);
  }

  /**
   * A helper method on the Plugin class that fetches the name of the command. 		
   *  
   */

  public String getCommandName(Object metadata){
    JavaClass javaClass = (JavaClass) metadata;
    return javaClass.getNamedParameter("command.class","name");
  }

  // Checks if the source file is a Command interface and that you do 
  // want to consider it for code generation.

  public boolean shouldGenerate(Object metadata) {
    JavaClass javaClass = (JavaClass) metadata;
    boolean isCommand = javaClass.isA("org.xdoclet.plugin.commands.Command");
    boolean ignore = "false".equals(javaClass.getNamedParameter("command.class","generate"));
    if (isCommand && !ignore)
      return true;
    else
      return false;
  }
}

Now that we are done with developing the tags and the plugin, the next logical step would be to write the template. Since the result of the generation needs to be an XML file, as per recommendation, jelly template is being employed.

<j:jelly xmlns:j="jelly:core" xmlns:x="jelly:xml">
	<x:comment text="${dontedit}" trim="true"/>
	<commands>	           
     	<j:forEach var="class" items="${metadata}">
     	   <j:if test="${plugin.shouldGenerate(class)}">
     	      <command name="${plugin.getCommandName(class)}" 
                    	value="${class.fullyQualifiedName}"/>
           </j:if>
        </j:forEach>       
     </commands>       
</j:jelly>

This results in a file 'command-mapping.xml' :

<?xml version="1.0" encoding="ISO-8859-1"?>

<!--Generated file. Do not edit.-->
<commands>
  <command value="org.xdoclet.plugin.commands.GetPurchaseOrderCommand" name="GetPurchaseOrder"/>
  <command value="org.xdoclet.plugin.commands.SavePurchaseOrderCommand" name="SavePurchaseOrder"/>
  <command value="org.xdoclet.plugin.commands.UpdatePurchaseOrderCommand" name="UpdatePurchaseOrder"/>
</commands>

I had 3 Command implementations in my file system and the generated XML file reflects that. Command.java was also present in the same package as the implementation files and would have showed up in the XML file had we not added the attribute 'generate=false' at the class level. The plugin accordingly ingored that file. (see shouldGenerate() method).

Where did this comment come from in the source file ?

<!--Generated file. Do not edit.-->

Remember abstract Plugin class mapped a String to 'dontedit' key and added it to the template context? the template used it for displaying the comment. //TODO - Internationalizing comments through externalizer plugin.

This plugin always results in a file named command-mapping.xml since it is harcoded in the CommandPlugin class constructor. This file name can be overriden at run time by specifying it as the value of filereplace attribute in the <component> element .

The abstract plugin class accepts quite a few attributes from the build file but one can have any number of such attributes declared on the concrete Plugin class with corresponding setters.

The code for the Command plugin that we developed can be downloaded here. In order to build it using maven, it needs to be unzipped it to the same location as other XDoclet2 plugins (source). It is packaged as a xdoclet2 maven multiproject and can be built like any other plugin.

For eg on my machine, the following builds the command-plugin

$ cd /home/lab/XDoclet2/xdoclet-plugins-1.0.2/src
$ cd plugin-command
$ maven jar