devxlogo

XDoclet Meets Eclipse: Code Generation Made Easy

XDoclet Meets Eclipse: Code Generation Made Easy

Doclet is a code generation engine that enables a concept known as Attribute-Oriented Programming. To use XDoclet, a programmer adds metadata (attributes) for classes and methods within the JavaDoc for their source. XDoclet can then scour your source files for these attributes and generates artifacts that are necessary for your application. XDoclet is executed from within Jakarta Ant, using a set of custom Ant tasks.

XDoclet can be used to generate files for Web applications, EJBs, Castor, Hibernate, JDO, Struts and a number of other tools.

In an earlier article, you learned about a plugin to the Eclipse environment that lets you configure and deploy to your JBoss application server. The same plugin will invoke the Xdoclet standard to let you automatically generate Java code for enterprise applications. (Please refer to the first article for instructions on how to install the plugin: http://www.devx.com/opensource/Article/20242.)

Author’s Note: If you’re running Eclipse 3.0 M7 release, the XDoclet portion of the plugin will not work. You must use Eclipse 3.0 M6 or earlier. See http://www.jboss.org/index.html?module=bb&op=viewtopic&t=46177.

XDoclet ships with modules for nearly all the leading Java application servers, including:

  • IBM WebSphere Application Server
  • JBoss
  • BEA WebLogic
  • Oracle IAS
  • Macromedia JRun

What are some of the benefits of code generation with XDoclet? Here are a few:

  • Minimizes the number of files that a developer has to maintain.
  • Reduced development time because developers write less code and maintain code in fewer places
  • Deployment files can be generated for multiple application servers, allowing for easier vendor independence
  • Developers can view deployment information in the source code, while the deployment team can still use the deployment descriptor
  • Metadata can be regenerated and integrated with the source code
  • (See more DevX articles and resources about code generation in the left column.)

    Big String, Small Code
    Stateless session EJBs are a great way of introducing a service layer into an application, but we all know how tedious it can be to generate five or six separate files just to implement an EJB with a single method. The wonderful thing about XDoclet is that the only file that you have to manually create is the EJB “bean” class. After providing attributes in the JavaDoc, XDoclet can generate all the interfaces and deployment descriptors necessary for the EJB to run in an application server.

    We wrote a stateless session EJB that does the extremely difficult task of (drum roll) capitalizing a string! We chose to invoke this EJB via a servlet so that we could showcase both the Web and EJB generation functionality provided by XDoclet. XDoclet will be used to generate a Web deployment descriptor, the EJB interfaces, and the EJB deployment descriptors.

    We will not cover the packaging features of the plugin in this article, but you can refer to the plugin’s documentation for more details. (See http://heanet.dl.sourceforge.net/sourceforge/jboss/Tutorial-1.2.2.pdf. Editor’s Note: If the preceding link fails to load the PDF, please copy and paste the URL into a new browser instance.) You should also download our source code, which includes the XDoclet configurations, the Packaging configurations, and all the files that XDoclet generates (see the download link in the left column).

    The two major classes you need to be concerned with are shown in listings 1 and 2. Listing 1 is the JavaDoc for the EJB, which has a method that capitalizes an incoming string. Listing 2 is the JavaDoc for the servlet, which simply performs a JNDI lookup of the EJB and makes a remote call to the EJB’s capitalization method.

    For those familiar with EJBs, you will notice that the @ejb.bean tag contains information that is usually specified in the ejb-jar.xml file (i.e., our EJB deployment descriptor).

    Similar to our tag for our EJB, the XDoclet tags incorporated in the servlet help define the data that goes into the web.xml file, the Web deployment descriptor.

    Webdoclet and Ejbdoclet
    In order to execute XDoclet, we need an Ant build file. This build file will call XDoclet tasks that generate the necessary files and put them in a specified location. The beauty of the XDoclet functionality provided by the plugin is that we don’t have to write any Ant code by hand. We can use the plugin’s GUI to define the XDoclet configuration that we want, and the GUI will generate the Ant script for us. Right-click on the project and go to Properties ?> XDoclet Configurations. Using this properties view, you can define XDoclet configurations for any type of XDoclet code generation you want. In this case, you’ll generate a Web and an EJB configuration.

    Figure 1. The XDoclet Configurations Menu: Here is where you define the configurations for your code generated projects.

    Figure 1 shows the XDoclet Configurations view. The top pane allows you to add and select configurations to edit. The bottom left pane displays the “doclets” and their “entries.” A doclet is equivalent to an Ant task and its entries are equivalent to Ant nested elements. The bottom right pane shows the property keys and values for each doclet.

    Figure 1 shows a portion of a doclet called ejbdoclet. This doclet is used to generate the EJB interfaces and deployment descriptors. Everything in the ejbdoclet configuration is generic except for the JBoss subtask. This can be substituted or used in conjunction with an entry for a different application server, such as WebSphere or WebLogic. This makes it possible to provide support for multiple application servers, thus allowing you to remain vendor-neutral.

    Here is how the generated ejb-jar.xml file compares to the JavaDoc in the EJB bean class:

    JavaDoc

    JavaDoc

    Generated

    /** 

    * @ejb.bean

     * display-name=”EJB Capitalizer”

    EJB Capitalizer

     * name=”Capitalizer”

    Capitalizer

     

    ejb.CapitalizerHome

     

    ejb.Capitalizer

     

    ejb.CapitalizerLocalHome

     

    ejb.CapitalizerLocal

     

    ejb.CapitalizerBean

     * type=”Stateless”

    Stateless

     

    Container

     * jndi-name=”ejb/CapitalizerHome”

     

     */

    The other doclet that we use is called webdoclet. Its main purpose is to generate the web.xml file, but it also has entries that allow it to generate application server-specific Web deployment descriptors. For example, it can generate the jboss-web.xml file for JBoss or the ibm-web-bnd.xmi and ibm-web-ext.xmi files for IBM Websphere Application Server.

    Here is how the generated web.xml file compares to the JavaDoc in the servlet class:

    JavaDoc

    JavaDoc

    Generated Code

    /** *

      * @web.servlet name = HelloWorldServlet”

    HelloWorldServlet

     

    web.HelloWorldServlet

     

     

     

     

     

    HelloWorldServlet

      * @web.servlet-mapping url-pattern = “/Howdy”

    /Howdy  

      */

     

     

    After defining your configurations, a Jakarta Ant build file called xdoclet-build.xml is generated in the top level of the project. This file is included with the source code for the article. After importing our project, you should be able to go to the XDoclet Configurations menu and look through the configuration.

    Figure 2. The src and gen_src Directories: You can see the files before and after Xdoclet generates them.

    In order to generate the code, you must right-click on the project in Eclipse’s Package Explorer view and click on ‘Run XDoclet.’ Again, the included source code for this article comes with all of the generated XDoclet files, so you might want to look through the files before trying to run XDoclet on your machine so you know what to expect. Figure 2 shows both the source and the generated source for the example program.

    Figure 3. Capped String: The sample program in action.

    After generating the XDoclet code, you probably want to package and deploy it as an EAR file. Our source code also provides the packaging configuration that generates a deployable EAR file. It is beyond the scope of this article to cover the process of EAR packaging. However, you can refer to the plugin’s documentation (http://heanet.dl.sourceforge.net/sourceforge/jboss/Tutorial-1.2.2.pdf?Editor’s Note: If the preceding link does not load a PDF, copy and paste the URL into a separate browser instance), which provides a detailed walkthrough on packaging. Figure 3 shows a screen shot of the application after being executed.

    Where to Keep Your Generated Code
    There are several ways of managing generated source files. Some developers encourage you mix your generated source in with your own source code. We prefer to keep all the generated code in a completely separate source folder. The way that you do it will probably be based on your personal preference and circumstances. As seen in Figure 2, we put the source code in a directory called src and we set up the XDoclet configurations to generate the XDoclet files in a directory called gen_src.

    JSR 175
    The attribute-oriented programming paradigm has gained a huge amount of attention in the software development community. For example, the C# language has a built-in facility for adding metadata. The Java community is recognizing the need for adding metadata as part of the Java language definition. JSR175 (see http://www.jcp.org/en/jsr/detail?id=175) will allow for “annotating fields, methods, and classes as having particular attributes that indicate they should be processed in special ways by development tools, deployment tools, or run-time libraries. We call such annotations metadata.” JSR 175 will implement the equivalent of XDoclet’s JavaDoc metadata definition. The XDoclet project will likely adopt the JSR 175 standard for defining metadata, and continue to develop its generation tools using that standard.

    In this article you were introduced to XDoclet, a code generation engine which implements a concept known as Attribute-Oriented Programming. XDoclet has found a huge following, as it can reduce the amount of code that a developer must hand write. Though we focused on the ejbdoclet and webdoclet doclets in particular, XDoclet can be used to generate a myriad of other files needed for such leading technologies as JDO and Struts.

    devxblackblue

    About Our Editorial Process

    At DevX, we’re dedicated to tech entrepreneurship. Our team closely follows industry shifts, new products, AI breakthroughs, technology trends, and funding announcements. Articles undergo thorough editing to ensure accuracy and clarity, reflecting DevX’s style and supporting entrepreneurs in the tech sphere.

    See our full editorial policy.

    About Our Journalist