I've started a new (mostly) greenfield project recently and after two years of having to code in an existing application with a restrictive framework, I was eager to stretch my legs a bit and break out some of the good ol' tools that made me so productive in previous gigs - XDoclet being one of them.

For those who don't know, XDoclet is an open-source tool that lets you put special tags in your javadoc, which XDoclet finds in a post- or pre-compile step, and uses to generate more code, or configuration files, or whatever else you want to generate.  Most frequently, XDoclet is used to generate deployment descriptors and helper classes to go with the most important classes of a system.  Hibernate promotes (or at least, promoted) XDoclet as part of its suite of tools for easing configuration. Almost any book on Hibernate includes at least one chapter on using XDoclet to build your Hibernate configurations.

So, I pulled down XDoclet, and put it in the build, and started using it and discovered to my horror that XDoclet is not compatible with the new Java 5.0 enhancements.  This includes generics, the extended for loop, enums, annotations, and static imports. The reason for this is that internally XDoclet parses source code to find the javadoc tags using a javacc generated parser, which is only compatible with 1.4 syntax.  This was fine when I used it two years ago and we had not yet switched to JDK5, but was not going to be satisfactory under my new project where we want to use the new language features.

Facing the dilemma of abandoning either 5.0 language features or abandoning XDoclet, I began looking around for a solution.  A company called Raible Designs has a patch available, which I played with a little and it does in fact seem to work.  However, looking at XDoclet itself, I saw that it is not being kept up-to-date either - as I write this entry, the last update was "05 May 2005" - well over a year ago.  I was not feeling very warm or fuzzy at this point.

So I looked into XDoclet2, the successor project to XDoclet.  It definitely has JDK5 support - but it's still in beta.  Well, I had used other beta products successfully before, so I gave it a whirl.  It worked ok with JDK5 - but I started having little quirky issues- beta-type issues.  Things like the fact that when generating hibernate configurations using XDoclet2, the access method of using the getters didn't work and you had to use direct field access --- that is, if you used the latest stable release, which was 9 months old.  If you want to fix that problem, you need to pull down a snapshot release from their distribution repository (after reading the forums to find out which one is the right one, because they don't tell you on the webpage).

All of this makes me rather uncomfortable for the state of XDoclet (both 1 and 2) in general.  Right now, if you want a truly reliable XDoclet platform that works out of the box, you need to use 1.4.  JDK5 has been out for three years now and XDoclet technologies are still struggling to cope with the changes, and JDK6 (formerly known as Mustang) is right around the corner.

There is a school of thought that annotations in JDK5 superseded XDoclet or made it obsolete.  That may be true in its intent, and perhaps annotations are in fact a better way to do it.  But in my opinion, annotations only superseded the XDoclet tags in the javadoc, not the tool itself.  I don't know of anything that generates all the different types of artifacts from that metadata (regardless of format) like XDoclet does.

In addition, there is a large amount of code out there that relies on XDoclet to generate and build the systems they are part of.  If new JDKs keep XDoclet from working and the fixes/successors to XDoclet aren't stable and confidence-inspiring, XDoclet's support will disappear quickly.