The Java Developers' Introduction to XDoclet

Like this article? We recommend

Extreme Programming with Ant: Building and Deploying Java Applications with JSP, EJB, XSLT, XDoclet, and JUnit

Learn More Buy

Like this article? We recommend

Like this article? We recommend 

Extreme Programming with Ant: Building and Deploying Java Applications with JSP, EJB, XSLT, XDoclet, and JUnit

Learn More Buy

Most of the instructions that exist on the net for XDoclet read like stereo instructions. They provide a tremendous amount of information, but it is scattered and disjointed—they don't give you a clear picture of how to use this tool. To clear up the confusion, this article outlines the base needed to get started using XDoclet. I will be using JBoss as the example application server to code against.

First, let me discuss the tools I will use. To make this tutorial as generic as possible, I do not use any specific IDE. Feel free to use whatever is your preference. All the examples detailed below can be written in any plain text editor: Notepad, vi, emacs, or something more complicated. To work along with these examples, you should download and set up the following tools:

• Ant: http://ant.apache.org/

• XDoclet: http://xdoclet.sourceforge.net/xdoclet/

• JBoss: http://www.jboss.org/

Entity Bean

Let's dive right in and start with an entity bean. First, here is the code for an entity bean without XDoclet (I am detailing only the bean itself; not any of the interfaces):

package com.dzrealms.example.entity;

import javax.ejb.EntityBean;
import javax.ejb.EntityContext;
import javax.ejb.RemoveException;
import javax.ejb.CreateException;

public abstract class ExampleBean implements EntityBean {

  public Integer ejbCreate() throws CreateException {
   return null;
  }

  public void ejbPostCreate() {

  }

  public abstract Integer getID();
  public abstract void setID(Integer i);
  public abstract String getName();
  public abstract void setName(String s);
  public abstract String getValue();
  public abstract void setValue(String s);

  public void setEntityContext(EntityContext context) {
  }

  public void unsetEntityContext() {
  }

  public void ejbRemove() throws RemoveException {
  }

  public void ejbActivate() {
  }

  public void ejbPassivate() {
  }

  public void ejbLoad() {
  }

  public void ejbStore() {
  }
}

This bean is not very special. It has a default creation method, an ID to be used as the primary key, a name, and a value. Normally, to create this EJB by hand, we would have to create at least one home interface and one reference interface—both of them being either remote or local. In addition, we would have to create or update the application.xml and the server-specific xml files to be able to utilize this bean. That's a lot of work!

With XDoclet, we will eliminate all that work. Although it requires the bean itself to be a bit more complex, the overall amount of work required is dramatically reduced.

Let's break down the components of XDoclet. XDoclet works by placing reading a set of javadoc tags in the source code and then generating the appropriate interfaces and xml files. These tags can get quite complex because there is a large amount of configurability available. The tags come in two flavors: method level tags and class level tags. The method level tags are just what the name suggests—they define information about a specific method. The class level tags do the bulk of the work so therefore we will tackle them first.

Class Level Tags

Here's what the class level tags for my ExampleBean class look like:

/**
 * @ejb.bean name="ExampleBean"
 *      jndi-name="example/remote/ExampleBean"
 *      local-jndi-name="example/local/ExampleBean"
 *      cmp-version="2.x"
 *      primkey-field="ID"
 *      schema="Example"
 *
 * @ejb.persistence table-name="example"
 *
 * @ejb.interface remote-class="com.dzrealms.example.entity.ExampleRemote"
 *        local-class="com.dzrealms.example.entity.ExampleLocal"
 *
 * @ejb.home remote-class="com.dzrealms.example.entity.ExampleHomeRemote"
 *      local-class="com.dzrealms.example.entity.ExampleHomeLocal"
 *
 * @jboss.entity-command name="mysql-get-generated-keys"
 * 
 * @jboss.unknown-pk class="java.lang.Integer"
 *          auto-increment="true"
 */

This is the least amount of information needed for XDoclet to function properly. These tags detail the local and remote JNDI names, the names of all of the homes, and the interfaces for this bean.

@ejb.bean

@ejb.persistence

@ejb.interface

@ejb.home

@jboss.entity-command

Because I am using JBoss as my application server, I need to tell XDoclet how to handle the generation of primary keys. This tag tells XDoclet to add mysql-get-generated-keys as the key generator. This will be added to the jboss specific descriptors.

@jboss.unknown-pk

Again, because I am using JBoss, I need to tell JBoss via XDoclet what the primary key is and whether or not it is auto-incremented. This tag handles that for me.

Method Tags

The tags listed above are the only tags that are required for a bean to be built properly by XDoclet. However, without methods, a bean is fairly useless. For each method that you want exposed in an interface, certain tags are required. The following sections describe the tags required based on method type.

Create Method

Create methods require one tag to be generated correctly. This tag has a default value that allows you to make it very simple. The following is an example of the tag required for the no parameter create method:

 /**
  * @ejb.create-method
  * @return Primary Key
  * @throws CreateException
  */ 
  public Integer ejbCreate() throws CreateException {
   return null;
  }

  public void ejbPostCreate() {

  }

The post create does not require any tags, and the ejbCreate method requires only the ejb.create-method tag. This tag can be further defined to control which home it is displayed in, but that is beyond the scope of this document.

Select Method

To create a select method within a bean, a single tag is required. This tag defines the query used in the select method:

 /**
  * @ejb.select query="select o.ID from Example o where o.name = ?1"
  * @param s Name we are searching with
  * @return Set of Primary Keys with that name
  * @throws FinderException
  */ 
  public abstract Set ejbSelectByName(String s) throws FinderException;

The query follows the rules for the Enterprise Query Language.

Bean Methods

The last types of methods that are generated are the bean methods. Normally these are getter and setter methods that represent a column in a table in the database. They can also be concrete methods that perform some form of business function on the bean itself. Both types of methods are defined the same way:

 /**
  * @ejb.interface-method
  * @ejb.persistence
  * @return the name of this bean
  */
  public abstract String getName();
  /**
  * @param s Set the name of this bean
  */
  public abstract void setName(String s);
  /**
  * @ejb.interface-method
  * @ejb.persistence
  * @return the value of this bean
  */
  public abstract String getValue();
  /**
  * @ejb.interface-method
  * @param s Set the value of this bean
  */
  public abstract void setValue(String s);

For a method to be displayed in the interface (either remote or local) the tag @ejb.interface-method needs to be added to that method's javadoc, which informs XDoclet to add the method to the available interfaces. Without this tag, the method is still available to the bean and therefore the container will not be exposed to the interfaces. I can define the name field as read-only. The set method does not contain the @ejb.interface-method tag; therefore, only the container can call this method.

The other tag shown is @ejb.persistence, which tells XDoclet that this getter refers to a persistence method. Every column that is to be populated into the bean needs to have this tag applied to the associated getter. If the name of the column in the database does not match the name of the field in the bean, the tag needs to be further defined:

  * @ejb.persistence column-name="COLUMN_NAME"

If the column-name tag is not included, XDoclet assumes that the column name is the same as the field name.

Ant Task

With the first bean now defined, it's time to create an Ant task to generate all the interfaces for me. The task for XDoclet is not built into Ant, so I have to define it. Here is the entire Ant build file that will execute XDoclet on the bean (this Ant file works on the assumption that all the source code is stored in a directory called src):

<project name="example" default="all" basedir=".">

  <property file="${user.name}.properties"/>
  <path id="xdoclet.classpath">
   <fileset dir="${xdoclet.home}/lib">
    <include name="*.jar"/>
   </fileset>
   <pathelement location="${j2ee.jar}"/>
   <fileset dir="${jboss.home}/server/default/lib">
    <include name="*.jar"/>
   </fileset>
  </path>

  <path id="classpath">
   <pathelement location="${j2ee.jar}"/>
  </path>

  <taskdef name="ejbdoclet" classname="xdoclet.modules.ejb.EjbDocletTask"
   classpathref="xdoclet.classpath"/>

  <target name="all">
   <mkdir dir="gen"/>
   <ejbdoclet destdir="gen" ejbspec="2.0">
    <fileset dir="src">
     <include name="**/*.java"/>
    </fileset>
    <remoteinterface/>
    <homeinterface/>
    <localinterface/>
    <localhomeinterface/>
    <deploymentdescriptor destdir="META-INF"/>
    <jboss version="3.2" datasource="java:/example-ds"
     datasourcemapping="oracle"
     destdir="META-INF" xmlencoding="UTF-8"/>
   </ejbdoclet>
   <mkdir dir="classes"/>
   <javac debug="true" destdir="classes">
    <src path="src"/>
    <src path="gen"/>
    <classpath refid="classpath"/>
   </javac>
  </target>
</project>

The first component of this build file is a property tag that tells Ant to load additional properties from another file that is named by the logged-in user. This other file merely points out specific locations of where XDoclet and JBoss are installed. My properties file would look like this:

xdoclet.home=/Users/mzarra/Development/Libraries/xdoclet-1.2.2
jboss.home=/opt/jboss

The next tag builds a classpath using the path tag. Using the locations specified in the property file tag, the classpath is defined with all the jars in the server lib directory and XDoclet's lib directories. I have also created another classpath that has only the j2ee jar in it. This second classpath will be using for compiling all of source code. For compiling the XDoclet libraries are unnecessary. If the project were to require additional libraries, I would add them to this second path.

The taskdef tag defines the actual XDoclet tag. Using the classpath defined above, the task ejbdoclet is defined so that it can be used in targets.

The final tag is the actual target. This tag first creates the gen directory in which the generated source code will be stored. Next, it executes the ejbdoclet task that was defined previously. The task itself requires the following parameters:

Inside of the ejbdoclet tag, there are additional subtasks that define what is to be generated. In this example, I have added tags to generate remote home interfaces, remote interfaces, local interfaces, local home interfaces, and deployment descriptors. There is also a tag specifying which application server I am using. If I add more servers here, the server-specific deployment descriptors for these servers will also be generated.

The final task compiles all the source code from the two source directories: It places the compiled code into a classes directory. Executing the default task generates all the source code and deployment descriptors.