Next Generation of XDoclet 2 Announced


News: Next Generation of XDoclet 2 Announced

  1. Next Generation of XDoclet 2 Announced (18 messages)

    In an email to XDoclet2-users list Aslak Hellesoy introduced the next version of XDoclet 2, with initial releases coming shortly. Major changes in XDoclet 2 are a rebuilding of the framework as a thin extension on top of the new Generama/PicoContainer, with plugins for Velocity and Jelly. A separate project for XDoclet plugins has been setup, to help enable XDoclet to potentially join Jakarta.

    The email is included below. Back in April, TSS also published an interview with Aslak Hellesoy.

    -----Original Message-----
    From: xdoclet-user-admin at lists dot sourceforge dot net
    [mailto:xdoclet-user-admin at lists dot sourceforge dot net] On Behalf Of Aslak Hellesøy
    Sent: Wednesday, August 27, 2003 9:32 AM
    To: xdoclet-devel at lists dot sourceforge dot net
    Cc: xdoclet-user at lists dot sourceforge dot net;
    picocontainer-dev at lists dot codehaus dot org; qdox-user at lists dot codehaus dot org; KParkinson at thoughtworks dot com
    Subject: [Xdoclet-user] New XDoclet2 and Generama

    Hi folks,

    (Sorry for cross spamming, but I believe Generama/XDoclet2 might be of interest to all lists. Please try to reply only to xdoclet-devel at lists dot sf dot net, as the XDoclet project is the current home for these projects).

    The final XDoclet2 (hereafter XDoclet) framework based on a new library called Generama, Velocity, Jelly and PicoContainer is about to be released in beta. This is the next generation of XDoclet.

    During some recent refactorings of XDoclet, the Generama framework was factored out into a separate generic framework. A brief explanation of the Generama framework is necessary before continuing the explanation of XDoclet.

    G E N E R A M A F R A M E W O K

    Generama is a small IoC (Inversion of Control) architected plugin framework for Velocity and Jelly (currently a 27 k jar). It is possible to register one or more plugins (based on either Velocity or Jelly) that will generate a particular kind of output, using an associated velocity/jelly script with access to arbitrary metadata (placed in velocty/jelly context variables). The templates will expect metadata to be of a certain type, and therefore a given plugin will only work with metadata of the expected type. This is done by registering an appropriate MetadataProvider within Generama.

    Generama is based on PicoContainer ( In fact, Generama _is_ a PicoContainer, with all the core components that are composed to deliver Generama's functionality, registered by default. The Generama PicoContainer is only nearly ready to roll on its own though, and that is intentional by design. The remaining part is left to implement for clients of the Generama framework: That is to register three types of components:

    - A org.generama.MetadataProvider that provides metadata to the velocity/jelly scripts
    - A org.generama.WriterMapper that will decide where output should be written (usually to file).
    - At least one org.generama.Plugin that will generate output.

    This is done by the following steps:
    - Make a new instance of a concrete Generama subclass.
    - Register one or more plugins with it.
    - Call the Generama object's execute() method.

    This will cause all the plugins to be executed. When they execute, they will invoke their internal template engine (Velocity or Jelly) to generate output.

    Now you should have tons of generated files of whatever kind;-)

    Generama also comes with an Ant task. It's a generic task that lets you add plugins via <component> sub-elements. Writing an IDE plugin (for e.g. Eclipse or IDEA) should be very easy too. Volunteers for this are most welcome.

    Generama currently lives in XDoclet's generama CVS module. (Generama will be used in Middlegen, and could be a perfect base framework for a future version of AndroMDA too).

    G E N E R A M A P L U G I N S

    A Generama plugin typically consists of two files: First, a class that implements Plugin (or extends VelocityPlugin or JellyPlugin). Second, an associated velocity or jelly script. These scripts have access to the metadata object(s) via the ${metadata}variable and the associated plugin object via the ${plugin}variable. This makes it extremely easy to provide special logic to the scripts by implementing helper methods in the plugin classes themselves. Just implement a String getFoo() or String getBar(Zap) method in the plugin, and its template will be able to do magic things like ${} and ${plugin.getBar($zap)}. (For XDoclet 1.2 savvies, these helper methods replace the TagHandlers). Plugin developers only have to focus on two files: the template and the plugin class. Just remember to keep the template in the same package and the same name as the plugin class, and give it a .vm or .jelly
    extension. Further, testing helper methods in Plugins with JUnit should be very easy too.

    It is not entirely true that a plugin only consists of a plugin class and a script. The plugin developer Should also write tests for the plugin. Doing this TDD (Test Driven Development) is strongly recommended to drive the development process of a Generama plugin. Generama provides an abtract test framework based on JUnit to make this easy. These classes tests that a plugin generates what it is expected to generate. The test framework uses XMLUnit and CodeUnit to compare generated XML files resp. generated Java files against a static one. (CodeUnit is JUnit extension part of XJavaDoc. It compares Java files on the syntax level in a similar way to XMLUnit).

    In short, a plugin test consists of a test class, a file with expected output, and some sample input (for XDoclet plugins - see below - this will typically be one or more java sources with @tags).

    When writing a Generama plugin, start by extending the appropriate test class. They are abstract and you'll be surprised how easy it is to get started. It should be very obvious just by implementing the required abstract methods. Just remember to write the tests first. In Generama's test framework, the basic tests are already written, so all you have to do is to implement two methods: One saying how to get the metadata (test input), and another one saying how to get the expected output. So when you work on a plugin, you typically work in small iterations (each ending with a green JUnit bar) where you:

    1) Add more content to the expected output.
    2) Add more logic to the plugin class and/or script.
    3) Add more data to the sample input data.

    There are already examples on Generama plugins and how to test them in the xdoclet-plugins project (see below).

    X D O C L E T F R A M E W O R K

    XDoclet is only a small and simple extension of Generama with some additional preregistered components (currently a 16 k jar). The XDoclet class extends Generama and registers (among other things) a QDoxMetadataProvider, that will return instances of com.thoughtworks.qdox.model.JavaClass. (QDox is being used instead of XJavaDoc, primarily because of its superiour speed and more intuitive API). The XDoclet class is also abstract. The only thing needed to make it concrete is to make a subclass that implements the getFileProviderClass(). The XDocletTask for Ant uses one that returns a FileProvider that hooks into Ant filesets. XDoclet IDE plugins might want to provide an implementation that makes it possible to configure the returned files via the IDE.

    To those who tried to dive into XDoclet2 before and said "what the ... Where am I supposed to start?" should have a more pleasant experience this time. There are heaps of tests in the Generama, XDoclet and XDoclet Plugins projects to illustrate what the code does.

    X D O C L E T P L U G I N S

    XDoclet's plugins are nothing else then plain Generama plugins. The only special thing about them is that their velocity/jelly templates should expect the ${metadata} to be QDox's JavaClass. (Because XDoclet automatically registers a QDoxMetadataProvider!).

    When you look in the xdoclet2 CVS module, yo'll notice that there are no plugins at all(!). They now live at the xdoclet-plugins SF project. There are already a couple of plugins up there, mainly to get the development community going. If you want to be an XDoclet plugin developer, check out xdoclet-plugins and play a little with the code in there. Start writing your own plugin and experience how easy it is! When you have something working and really want to continue maintaining whatever plugin you have started on, submit some patches. After a while you'll earn your rights to commit to the CVS.

    There is one important reason for keeping the xdoclet-plugins project apart from the XDoclet and Generama projects. XDoclet / Generama might move to Jakarta. Due to Jakarta's strict meritrocacy rules, only a small number of developers will be granted commit rights in Jakarta. In order to attract a large developer community for XDoclet plugins, it is necessary to be able to grant commit rights more easily than at Jakarta.

    W H A T N O W

    - Generama and XDoclet will be released as alpha in the following week.
    - Developers who have committed code to XDoclet 1.2 the past three months will automatically get commit rights in the xdoclet-plugins
    project on SF.
    - Anyone who's interested in porting old XDoclet modules to the new plugin framework should install Maven 1.0-beta-10 or later. Committers will commit code to xdoclet-plugins. Other people will upload patches to xdoclet-plugins' JIRA.
    - Jakarta status will be applied for.
    - Those who want to contribute, but don't know exactly with what, tell the mailing list, and they will be assigned tasks in JIRA.

    There are lots of things that aren't covered in this short mail. Like doclet tag validation or how to migrate XDoclet modules to new plugins. Or how to build or run. Just fire the questions, and they will be answered.

    The code lives in xdoclet2 and generama CVS modules in the xdoclet SF project, and the xdoclet-plugins CVS module in the xdoclet-plugins SF

    Now the discussion!


    Threaded Messages (18)

  2. kudos[ Go to top ]

    Strange to see so little excitement and discussion regarding such a great tool as XDoclet.

    Kudos to XDoclet team.

    People, get familiar and use XDoclet, it saves enormous amount of time and efforts during the course of any project!
  3. kudos[ Go to top ]

    Let me repeat what Konstantin says here. XDoclet is a great tool and everyone should take a look at it and consider how it can be applied to your projects.

    What XDoclet means to me:
     - I'll never write another deployment descriptor again.
     - I'll never write another home/remote interface again.
     - I'll never have to manually deal with Hibernate mapping files again.
     - I'll never have to write a struts-config.xml file again.

    And it does some pretty cool stuff with MockObjects, too.
  4. XDoclet in Action[ Go to top ]

    Indeed, XDoclet is pretty cool. On that same note, this book looks promising:

  5. XDoclet book[ Go to top ]

    No, my friend. "XDoclet in Action" doesn't cover XDoclet 2. You may want this one:

    Best Regards,
  6. XDoclet book[ Go to top ]

    I am *not* working on the Wiley book, contrary to what it says (currently) on that site. I had briefly discussed the possibility of doing an XDoclet2 book with several publishers, but I never agreed to do an XDoclet2 book with anyone.

    In fact, I'm the tech. reviewer of Manning's XDoclet in Action book, which is superbly written and taught me several new things. Get XDoclet in Action! Don't wait for XDoclet2 to be viable - XDoclet 1.2 rocks as-is and will improve any J2EE project.
  7. kudos[ Go to top ]

    Probably so little discussion b/c everyone's worn out from the last pico discussion....
  8. kudos[ Go to top ]

    Strange to see so little excitement and discussion regarding such a great tool as XDoclet.

    > Kudos to XDoclet team.
    > People, get familiar and use XDoclet, it saves enormous amount of time and efforts during the course of any project!

    Not really that strange. XDoclet is a tool that came about because of the inadequacies of EJB. (anyone ever been exited by ANYTHING to do with EJB ??). Outside of EJB projects can someone tell me where XDoclet really 'saves enormous amount of time and effort' ?
  9. XDoclet uses[ Go to top ]

    We use it here, and we don't even use EJBs. We use it generate Hibernate configuration files and TLDs. I would say both are beneficial. Not having to tweak TLDs every time you ceate a new tag or add a parameter to an existing tag is nice. We just now "XDocletized" are Hibernate classes, so I can't speak on how much time that will save. However, it is nice to have everything in one place.

  10. XDoclet: Not just for EJBs anymore[ Go to top ]

    I agree that the EJB mess is a prime reason to use XDoclet and is the main reason XDoclet came into existence. But there's more to XDoclet than EJBs. There's TLD files, web.xml files, Hibernate mapping files, JDO mapping files, MockObjects, JMX interfaces, Struts' struts-config.xml and validation.xml files...

    And the list need not stop there. You see, XDoclet is not about generating a specific set of deployment descriptors, classes or interfaces. It's a general purpose code-generation framework. Yeah, there are some plugins/modules that come with XDoclet that accomplish some common code-generation tasks, but those plugins do not define the limits of XDoclet. XDoclet is easily extended to generate practically any code that you find yourself repeating.

    And it's not necessarily about saving time (although that is often one of the benefits). Aside from time-saving, XDoclet helps to achieve the DRY (Don't repeat yourself) principle (ala, "The Pragmatic Programmer"). It means that every piece of knowledge must have a single authoritative representation in a system. You can't achieve DRY with EJBs because there's deployment descriptors, interfaces, implementation classes, etc, etc. You can't achieve DRY with Hibernate because there's class files and the mapping file(s). You can't achieve DRY with JMX because there's the MBean class and the MBean interface (with standard MBeans, that is). And you may have some very un-DRY pieces of code in your own project.

    An interview with Dave Thomas (Pragmatic Programmer) at gives some good insight into the value of code-generation and how to achieve DRY code.

    Code generation is a good thing and has its place in many projects. Whether you use XDoclet or some other mechanism, you should look for opportunities to generate as much of your code as possible--make the computer do more of the work for you. XDoclet just happens to be a very good option for code generation.
  11. what's with XD1?[ Go to top ]

    While everyone seems to be excited about XD2, what's happening to the maintenance of XD1? I've been using it for over a year for EJB and Hibernate xml files, in that time however nobody seemed to care about updating it much anymore.

    With the exception of Andrew Stevens I see nobody replying to change requests or applying even submitted diffs to bugs.

    Jira has 370 odd unassigned issues now, tendency's a shame for such a great project!
  12. Sounds interesting. How does something like Generama overlap with what's going on at There was a good discussion here a while back about the similarities b/w andromda and the upcoming xdoclet 2. It seems to me that you could hook up andromda's metamodel with generam outputs and you'd basically replace their output engine. Thoughts?
  13. Correct.

    I haven't been in touch with the AndroMDA for a while, but remembering from the last time I looked at its sources, I think AndroMDA could really benefit from Generama.

    It would just be a matter of writing a UMLMetadataProvider and register that. And of course remove the AndroMDA's built-in generation framework, which deals with configuring of Velocity etc.
  14. How flexible is the writer mapping mechanism? Will it have access to metadata? For example, if you were code generating from a UML metadata structure, would you be able to handle something like mapping to an output file whose name and path would be determined by the UML class and package name? Also, is it tied in so that not only the metadata, but your plugin could control the output? So, for example, your plugin could contain helper methods that would modify the output name at runtime, changing a file and path name from a class and package name into something based on a plugin function or setting?
  15. The mapping mechanism is quite flexible.

    public interface WriterMapper {
        Writer getWriter(Object metadata, Plugin plugin) throws IOException;

    So in your implementation, you can access the plugin in the getWriter method.

    The thing is, Generama currently only supports a one-to-one or many-to-one association between metadata objects and output writers (files).

    In the XDoclet case, that means that for a set of Java sources, you can output either one file for all of them (typically the case for e.g. ejb-jar.xml *shrug*) or one file for each (typically the case for e.g. Local EJB interfaces.

    I'm not 100% sure, but I think the UML model AndroMDA uses is just one big object instead of several ones for each modeled class.

    If it is one big object, Generama will need a new feature, be able to pass in only one object and generate many files from that (one-to-many). That should be easy enough to add though.

    Currently the plugin doesn't itself control how it is being executed, so that functionality should be moved inside AbstractPlugin's generate(metadata) method. That way, an AndroMDA plugin could look inside the metamodel to figure out how many times it needs to generate, and where to.

    Also worth to mention picoGui . This is a GUI (!) for PicoContainer (and thereby implicitly for Generama, XDoclet, Middlegen and AndroMDA(?).

    It lets you create new containers (Generama, XDoclet...) and register and configure components (plugins are components). And then execute them. Kind of the same way as you'd do in Ant, but visually. I'm planning to slap a thin IDEA plugin around it, and voila, XDoclet IDE.

    We really hope that the upcoming IDE plugins will boost the developer community and help people switch from XDoclet 1.2 to XDoclet 2.

    I hope to see all you on the dev list if you want to discuss this further.
  16. Next Generation of XDoclet 2 Announced[ Go to top ]

    With the new features that are going to be added to J2SE1.5 will this not make XDoclet obsolete? Curious...


  17. Next Generation of XDoclet 2 Announced[ Go to top ]

    Read the interview with Aslak mentioned earlier, the same thing was asked in that. Future changes may remove the need for some uses of XDoclet (e.g. if metadata in the classes replaces deployment descriptors), but it'll still have a place. There's plenty of other needs for code generation.
  18. XDoclet-2 Help[ Go to top ]

    I am new user of XDoclet-2 plugin. I want to use XDoclet plugin with Eclipse. But how it should be pluged with Eclipse is the basic problem of mine. XDoclet-2 plugin is a simple Framework on the basis of Generama. I want to write my own XDoclet plugin but didn't get idea. If you have time please explain with example. Actually the main aim to make our own plugin is to decorate java source file. Example: Suppose if any user write a java application like this public class DecorateMe{ private String name; private int age; /** * @param none */ public DecorateMe(){ // some code } /** * @param name * @return void */ public void setName(String name){ = name; } public void setAge(int age){ this.age = age; } public String getName(){ return name; } public int getAge(){ return age; } } Now, user only decorate the constructor and the one setter mehod by JavaDoc Tags. i have to provide a plugin that is triggered some where and that plugin should be decorate this java source file in well manner and also provide some faclity to user so that he/she can choose our custom tags for decoration. Thanks in advance. vinay
  19. Hi, I want to generate struts.xml file using xdoclet2 and its plugins. Can you give me a sample code of how to do it. Thanks Ravi