XDoclet 1.2 vs XDoclet 2

The burning question: Should you even bother with XDoclet 1.2 or should
you wait for XDoclet 2?
XDoclet 2 is a complete rewrite of XDoclet that addresses many of the
problems of XDoclet 1.2. These problems include:

In XDoclet 1.2, the source of metadata is limited to JavaDoc-style

tags. This means you can't generate code from an arbitrary source
of metadata, such as a database schema or XML.

XDoclet 1.2 modules are implemented as Ant tasks (and

subtasks). This limits XDoclet's use to be within an Ant or Maven
build.

Extending XDoclet 1.2 involves writing custom modules using a

clumsy template language, requiring you to learn a new language to
write XDoclet templates.

The biggest change with XDoclet 2 is in its underlying design. XDoclet
2 is actually made up of three parts: The core code generation engine
(Generama), metadata sources, and plugins.
Generama takes a metadata provider as input and feeds the metadata to
one or more plugins that generate code. The wonderful thing about a
metadata provider is that it doesn't have to come from JavaDoc--you can
write a metadata source to draw metadata from virtually anything,
including (but not limited to) database schemas, XMI files, or even
another language source file (imagine being able to use XDoclet with
Ruby).
On the output side, a plugin takes the metadata and feeds it to a
template for generating code. In generama, the template language is
pluggable and can be anything you want (as long as there's a plugin
for it). Out of the box, Generama comes with template plugins for
working with Velocity and Jelly.
So, now that I've told you about Generama, how does XDoclet 2 fit into
the picture? Well, XDoclet 2 is just an implementation of Generama
that uses a QDox metadata provider to draw from JavaDoc-style
tags. In other words, XDoclet 2 is just a specialized version of
Generama.
All this is well and good, but how does it affect you as an XDoclet
user? It depends on your perspective and a little bit on how well
XDoclet 2 plugin writers preserve backward compatibility.
If you are someone who uses XDoclet for custom code-generation and
don't use the out-of-the-box modules that come with XDoclet 1.2, then
a lot changes for you. Writing a custom XDoclet 2 plugin is completely
different than writing a custom XDoclet 1.2 module. How it's different
is a different topic altogether, but suffice it to say that you'll be
starting over if you switch to XDoclet 2.
If you use the out-of-the-box modules with XDoclet 1.2 then a switch
to XDoclet 2 won't be quite so bad for you. The doclet tags may or may
not change, depending on whether or not the plugin writer preserved
backward compatibility with XDoclet 1.2. With any luck, you won't need
to change any of your tagging when you make the switch.
On the other hand, your build file will most definitely change. In
XDoclet 1.2, modules were implemented as Ant tasks and subtasks. But
in XDoclet 2, there is only one Ant task--the "xdoclet" task. This
task takes plugins as subelements in the build file, with each plugin
responsible for generating a particular artifact.
For example, to generate remote interfaces, local interfaces, and
a deployment descriptor for EJBs in XDoclet 1.2, your build may
contain something like this:

To accomplish the same thing in XDoclet 2, your build would contain
something like the following:

The <component> elements load the plugins into the XDoclet
container. (XDoclet is a Picocontainer, by the way.)
Now that you've seen how XDoclet 2 will differ from XDoclet 1.2, the
question still remains: Should you bother with XDoclet 1.2 or wait
until XDoclet 2?
If you are working on a project that would benefit from code
generation (do you have any repetitive boilerplate code?) today then
don't wait...start taking advantage of XDoclet 1.2 right away. It's
worth it if it saves you the hassle of managing duplications in you
code. When XDoclet 2 comes along, the transition should be relatively
smooth.
The core of XDoclet 2 (Generama and the XDoclet 2 ant tasks) are
reasonably stable today. However, XDoclet 2 doesn't offer near the
same selection of plugins as XDoclet 1.2. For example, as of this
writing there still aren't XDoclet 2 plugins for generating utility
classes or value objects for EJBs and there's nothing Struts or
WebWork-related yet. These will surely come with time, but it will
still be some time before XDoclet 2 has a broad enough selection of
plugins to make it usable for most projects.
[ December 09, 2003: Message edited by: Craig Walls ]