Software Configuration

It only runs on Java 2 JDKs, older JDKs are not supported.
Make sure tools.jar from JDK's lib directory is in your classpath.
Make sure JDK's bin directory is in path (needed for invoking javadoc.exe).
Make sure you use Jakarta Ant v1.4.x, XDoclet does not run on older ones.

Using XDoclet

Using XDoclet is simple. Just as you write Javadoc tags for your code (you do comment your code, don't you?), you now add XDoclet tags too. These tags are used by XDoclet as providers of meta-data that is then used to generate other files as required.

For a thorough example of how to use XDoclet, consult the samples. However, this page should give you enough of a start to XDoclet your code.

A typical XDoclet comment might look like this:

/**
 * This is an account bean. It is an example of how to use the
 * EJBDoclet tags.
 *
 * @see Customer Accounts are owned by customers, and a customer can
 * have many accounts.
 *
 * @ejb:bean   name="bank/Account"
 *             type="CMP"
 *             jndi-name="ejb/bank/Account"
 *             primkey-field="id"
 * @ejb:finder signature="Collection findAll()"
 *             unchecked="true"
 * @ejb:interface remote-class="test.interfaces.Account"
 */

There are three parts to that comment: The comment, the javadoc tag, and the XDoclet tags. The first two are your standard tags. Just because you are using XDoclet doesn't mean that you stop doing normal documentation. The third part of the comment is that part that we are interested in. An XDoclet tag is comprised of the following parts:

@namespace:tag-name parameter-name="parameter value"

Tags are grouped by namespaces, and have names that are unique within that namespace. Tags can have zero or more parameters, which are grouped in name="value" pairs. Looking at the above example, we find the first tag is in the ejb namespace, and is called bean. The ejb:bean tag defines data relating to Enterprise Java Beans. Every EJB will require a name, and it is specified here. The namespace is a mechanism for making sure no name collision happens. Namespaces include ejb, web, jboss, weblogic, struts and so on. So it's simply a way to group related tags. For details on individual tags, consult the ejbdoclet documentation.

Tag values can be specified as ant properties. For example:

@jboss:create-table create="${jboss.create.table}"

Where the jboss.create.table is a property defined in the ant project. For more information on ant properties consult the ant documentation.

Tags exist at both class and method level. As a general rule, if information can be determined by the name or type of a class, then it will be - and hence there will not be a requirement to specify that information with a tag. An example of this is the type parameter to the ejb:bean tag example above. The type in this instance refers to the Entity type (CMP or BMP), but if the class implemented the javax.ejb.SessionBean interface the type would be Stateful or Stateless.

To start using XDoclet you must first determine what it is you wish to use it for. The two most popular usages are EJBDoclet and WebDoclet. Generally you should define the XDoclet task for Ant, setup the configuration parameter. Here is an example:

<target name="ejbdoclet" depends="prepare">

<taskdef name="ejbdoclet" classname="xdoclet.ejb.EjbDocletTask" classpath="${xdoclet.jar.path};${log4j.jar.path};${ant.jar.path}" />

<ejbdoclet
    sourcepath="${java.dir}"
    destdir="${generated.java.dir}"
    classpathref="project.class.path"
    excludedtags="@version,@author"
    ejbspec="2.0"
    force="${xdoclet.force}">

	<fileset dir="${java.dir}">
		<include name="**/*Bean.java" />
	</fileset>

	<dataobject/>
	<remoteinterface/>
	<localinterface/>
	<homeinterface/>
	<localhomeinterface/>
	<entitypk/>
	<entitycmp/>
	<deploymentdescriptor destdir="${build.dir}/ejb/META-INF"/>

	<jboss version="2.4" xmlencoding="UTF-8" typemapping="Hypersonic SQL" datasource="java:/DefaultDS" destdir="${build.dir}/ejb/META-INF"/>

</ejbdoclet>

</target>

<target name="compile" depends="ejbdoclet">
	<!-- Compile EJBs -->
	<javac srcdir="${java.dir};${generated.java.dir}" destdir="${build.dir}/ejb" includes="test/ejb/*.java,test/interfaces/*.java">
</target>

As it's seen, compile target depends on ejbdoclet target. This means that before compiling anything all home/local/remote interfaces, primary key and data-object (also known as Value Objects) are generated, plus deployment descriptors. The first thing you have to do is define ejbdoclet task for Ant. To do so you use taskdef, where you specify xdoclet.ejb.EjbDocletTask as the class implementing ejbdoclet task. Note that classpath parameter has xdoclet.jar, log4j.jar and ant.jar (Ant 1.4 or higher) in it. These 3 jars are all needed.

Next you declare ejbdoclet task, with a set of configuration parameters and nested elements. For example, destdir specifies where to put generated files. As you can see there's an inheritance mechanisms also, you can override this destfir parameter for each nested element (or as we call it sub-task). <deploymentdescriptor/> does exactly that to put the generated ejb-jar.xml file somewhere else than where generated java sources for home/remote/pk/etc are placed. For a complete list of configurable parameters consult the documentation for the task and for each sub-task.

By default each task has some built-in sub-tasks. Some of them are mandatory really, for example <remoteinterface/> and <localinterface/>, can you imagine an EJB without a remote or local (EJb 2.0 only) interface? Some other tasks may be optional, for example <jboss/> is optional if you're not using jBoss application server.

There's even a third form of sub-tasks: <template/>. This is useful for cases where you want to design your own template file and generate a customized file. So, you need a simple way to let xdoclet use your template file. Here is an example:

<taskdef name="templatedoclet" classname="xdoclet.DocletTask" classpath="${xdoclet.jar.path};${log4j.jar.path};${ant.jar.path}" />

<templatedoclet sourcepath="${java.dir}" destdir="${generated.java.dir}" classpathref="project.class.path" excludedtags="@version,@author" >

	<fileset dir="${java.dir}">
		<include name="**/*Bean.java" />
	</fileset>

	<template templateFile="/mytemplate.j" destinationfile="hhhh.txt"></template>

</templatedoclet>

So you put a <template/> element in the task, specify the path to your template file and output file name (which will we stored in the directory specified in destdir parameter). This is very useful for those creative people who want to easily take advantage of XDoclet's framework-like capabilities and define their own set of @tags and templates generating something from those @tags. For more information on how to write template see Template How-To.

So whenever you do a build, ejbdoclet (or whatever other task) is run and you have always up-to-date files generated by xdoclet.

A checklist of things you will need to do to get XDoclet running is:

Modify (creating if required) your build.xml script (see ant for details).
Add XDoclet tags to your source code.
Stop worrying about all that boring code you use to have to write! XDoclet does it for you now.

The mailing lists provide a wealth of knowledge, and the developers are lurking on the xdoclet-user list, so feel free to ask questions, make suggestions, or just generally discuss XDoclet.

The XDoclet Team.