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 ]