aspose file tools*
The moose likes Other Java Products and Servers and the fly likes XDoclet 1.2 vs XDoclet 2 Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Products » Other Java Products and Servers
Bookmark "XDoclet 1.2 vs XDoclet 2" Watch "XDoclet 1.2 vs XDoclet 2" New topic
Author

XDoclet 1.2 vs XDoclet 2

Craig Walls
author
Ranch Hand

Joined: Sep 19, 2003
Posts: 335
    
    5
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 ]

    Spring in Action - Unleash POJO power in your applications!
    Modular Java - Discover the secret weapon to modularity on the Java platform!
    XDoclet in Action - Your complete guide to code generation with XDoclet.
     
    I agree. Here's the link: http://aspose.com/file-tools
     
    subject: XDoclet 1.2 vs XDoclet 2