Help coderanch get a
new server
by contributing to the fundraiser
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
  • Mikalai Zaikin

XDoclet 1.2 vs XDoclet 2

Posts: 422
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
  • 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
    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
    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
    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 ]
    So there I was, trapped in the jungle. And at the last minute, I was saved by this tiny ad:
    We need your help - Coderanch server fundraiser
      Bookmark Topic Watch Topic
    • New Topic