XDoclet v1.1 Code and Descriptor Generation Tool Released

Discussions

News: XDoclet v1.1 Code and Descriptor Generation Tool Released

  1. XDoclet v1.1 has been released! XDoclet is an extended Javadoc Doclet engine. It's a generic Java tool that lets you create custom Javadoc @tags and based on those @tags generate source code or other files (such as ejb-jar.xml deployment descriptors) using a template engine it provides. XDoclet was created by Rickard Oberg, Chief Architect of TheServerSide.com

    You can download it from http://sourceforge.net/projects/xdoclet.

    The broader goal is to let you apply "Continuous Integration" in component-oriented development. The point is that you program your component and specify its meta-data in a per component fashion, you set the deployment meta-data per component. You don't have to worry about outdating deployment meta-data whenever you touch the code. The deployment meta-data is continuously integrated. And the whole process is, in its nature, round-trip. We call it "Continuous Reconfiguration". XDoclet is meant to be used as part of the build process utilizing Apache-Ant.

    The system is extensible. If desired, you can write a specific template for your specific task (supporting a new application server, defining the OR schema for a tool like TopLink for example, or even supporting Servlets as components!). Some pre-build @tags and templates are already supported by XDoclet, for example <ejbdoclet/> for EJB-related stuff, <webdoclet/> for web.xml deployment descriptor generation and so on.

    The new v1.1 has a lot of new stuff most importantly:

    Core:

    - Enhanced and refactored template tag handling system.
    - You can use ant properties in tag values, eg:
      @jboss:create-table "${jboss.create.table}"
      Just create put a <property name="jboss.create.table" value="blabla"/>. This is useful for keeping deployment-oriented settings out of source code.
    - Easy to use <template/> and <xmlTemplate/> sub-tasks that let you define template/@tags of your own.
    - Smarter timestamp/etc checking, so it regenerates in less cases if you haven't modified a file.

    ejbdoclet:

    - Many useful defaults.
    - All EJB sub-tasks are now optional.
    - Implemented automatic inheritance of pk/intf/home/etc. This way you have true component inheritance automatically.

    jBoss support:
    - Added support for CMP2 1-1 and 1-n relationships in JBoss 3.0 alpha.

    Weblogic support:
    - MDB and session beans support, plus various new options.
    - Added support for weblogic web deployment descriptor.
    - Added support for weblogic relations.

    Orion support:
    - Enhancements to <orion/> ejbdoclet subtask, cmp mapping fully supported.

    WebSphere 4.x support:
    - Some minor bug fixes plus Schema.dbxml generated only when there's at least one cmp bean.

    WebWork support:
    - Command support added.

    Struts support:
    - Added support for struts local forwards.
    - Multiple action forms per bean supported.

    New Sub-tasks:
    - Added <utilObject/> subtask, generates utility class for each ejb to easy lookup remote interfaces.
    - Caster support added.
    - DAO (Data Access Object) is now possible.
    - MVCSoft's persistence manager support added.

    IDE integration:
    - IntelliJ IDEA live templates :o)

    And lots of bug fixes, enhancements, new samples and more documents.

    You can download it from http://sourceforge.net/projects/xdoclet.

    The XDoclet Team.
  2. Hi,

    in a recent thread, a reverse engineering capability was mentioned: generating the xDoclet tags based on existing deployment descriptors.
    Is this feature implemented in v1.1 or is it for a next version?

    Note that I wonder why you say
    "And the whole process is, in its nature, round-trip"
    as long as this feature is not implemented yet. How is the process round trip if you do not pick up changes to the deployment descriptors?

    Don't get me wrong: I think xDoclet is a great tool with lots of possibilities, but I'm looking for this specific feature one mentioned.

    Regards,
    Pieter.
  3. <quote>
    Don't get me wrong: I think xDoclet is a great tool with lots of possibilities, but I'm looking for this specific feature one mentioned.
    </quote>

    Well, EJBGen has it :-) (Reverse EJBGen, http://beust.com/cedric/ejbgen)

    --
    Cedric

  4. <Cedric>
    Well, EJBGen has it :-) (Reverse EJBGen, http:/ /beust.com/cedric/ejbgen)
    </Cedric>

    No it doesn't :-)

    I mean AFAIK what ReverseEJBGen does is it generates NEW source files from a ejb-jar.xml (or maybe I'm wrong?), then you have to either derive from these files or copy/paste/match what it generated into existing code. So it's still a major labor intensive task for the user.

    What we're trying to do is to modify/mutate user's existing source files and just add @tags in appropriate places. XDoclet will add @tags to existing source code. This feature and the GUI (let's you see the class/methods and specify setting for each which then appears as @tags in code) need source code mutation capabilities in Doclet API, something Sun's API doesn't, so that's why we started implementing xjavadoc module (btw, it works actually, but is not fully tested/optimized).

    Cheers,
    Ara.
  5. <quote>
    I mean AFAIK what ReverseEJBGen does is it generates NEW source files from a ejb-jar.xml (or maybe I'm wrong?), then you have to either derive from these files or copy/paste/match what it generated into existing code. So it's still a major labor intensive task for the user.
    </quote>

    Correct. I decided to go that route, I don't think users will want EJBGen to tamper with their source files. Generating base classes and letting the user derive from them is cleaner, IMO.

    <quote>
    What we're trying to do is to modify/mutate user's existing source files and just add @tags in appropriate places.
    </quote>

    I'm not sure users will appreciate that, but you will see. Also, in that case, you need to handle reverse-engineering (the source files will be sometimes edited by the user, sometimes by your tool, which will make their life difficult).

    <quote>
    started implementing xjavadoc module (btw, it works actually, but is not fully tested/optimized).
    </quote>

    Yes, I'm curious to see what xjavadoc will be like. Keep us posted.

    --
    Cedric

  6. <cedric>
     <quote>
      What we're trying to do is to modify/mutate user's
      existing source files and just add @tags in appropriate
      places.
     </quote>
     I'm not sure users will appreciate that, but you will see.
    </cedric>

    Hi,
    why wouldn't that be appreciated? I think it's all in the "continuous integration" filosofy, which I think is a good thing. I think the advantage of putting it in the same file will be easier change control. Also, adding a superclass complicates the design.
    But probably that's all subjective.
    Also, I still need to check out EJBGen in practice.

    Anyway,
    it's good to know that so many talented people are working on open tools.

    Thanks,
    Pieter.
  7. <previous>
    "And the whole process is, in its nature, round-trip"
    as long as this feature is not implemented yet. How is the process round trip if you do not pick up changes to the deployment descriptors?
    </previous>

    No round trip on generated files is done in Xdoclet.

    If you want to add other beans in your dd, you can use Merge points. Ara brings this functionnality sometimes ago now. I guess it had never gets its "lettre de noblesse".

    Anyway here is how you do that: look into ejb-jar_xml.j for XDtMerge:merge. For example you will find a <XDtMerge:merge file="entity-beans.xml">
    Now in the ant task and for the subtask <deploymentdescriptor> add a parameter mergedir to a directory where you will create entity-beans.xml that contains all <entity> tags you want to add your your finalized ejb-jar.xml.
    I am sure you have already guessed what will happen...

    <ejbgen-response>
    And you do not need the sources to do that. I mean you can reuse ejb.jar (with .class) that you bought somewhere, add your xdoclet beans, include their ejb-jar.xml parts into your own generated one.
    </ejbgen-reponse>

    Some mergepoints will appear with a {0}, it means it is dependant of the bean currently processed.
    For example <XDtMerge:merge file="ejb-env-entries-{0}.xml">
    will look for a file ejb-env-entries-MyBean.xml when processing MyBean.java, ...

    A lot of merge points are available, if some are missing, please ping xdoclet-user.

    So, no, xdoclet does not permit round trip. Merge Point is a better alternative.
  8. The work on the reverse engineering tool has started, and an alpha version will be available in a couple of weeks. We probably won't have anything stable until one or two months from now, depending on how active people will be developing it. when something is good enough to try out, it will be announced on all xdoclet mailing lists, including the low-traffic xdoclet announcement list.

    It relies on a completely rewritten clone of javadoc called xjavadoc (built with javacc) which has an API very similar to sun's classic javadoc API, but with code mutation support. with xjavadoc, you can do something like:
    <pre>
    XClass clazz = xjavadoc.getClass("foo.Bar");
    XMethod method = clazz.getMethod("doIt(String s, int i)");
    XDoc methodDoc = method.getDoc();
    methodDoc.addTag("@some-tag bla bla bla");
    File rootDir = new File("modified");
    clazz.save(rootDir);
    </pre>

    xjavadoc is currently in alpha state, and it is a separate module in the xdoclet CVS tree. It's not included in the xdoclet 1.1 distro.

    Up the road are also gui tools (which will also use xjavadoc) and a validation tool called xtags. The XDoclet family of tools and people is growing!

    Cheers,
    Aslak
  9. <Pieter>
    Note that I wonder why you say
    "And the whole process is, in its nature, round- trip"
    as long as this feature is not implemented yet. How is the process round trip if you do not pick up changes to the deployment descriptors?
    </Pieter>

    Well, that's the vision statement, and the goal. We're not %100 there yet.

    By round-trip, "continuous" was the thing I had in my mind, if the deployment files are always in sync then it's like you modified them and the code is also in sync. We're working on "True round-trip".

    Ara.