Using XDoclet: Developing EJBs with Just the Bean Class

Listen Print

Using XDoclet: Developing EJBs with Just the Bean Class

by Dion Almaer
01/30/2002

Have you developed an EJB? Have you been frustrated at having to create and manipulate the XML deployment descriptors, as well as the interfaces? I certainly have. I was recently working on an EJB for the Xbeans open source project and I decided to use another open source tool -- XDoclet -- to generate the XML descriptors and interfaces for me.

Using XDoclet will enable you to work more efficiently within the J2EE framework. You will have a simpler view of your beans and the relationships between them, and many of the annoyances will be taken out of your development.

This article will discuss the XDoclet tool, how to use it, and how to extend it. In this article, we will create a session bean that uses the Javadoc tags, and run XDoclet on the bean.

What is XDoclet?

XDoclet is a tool that has evolved from the original EJBDoclet tool that Rickard Oberg created. The idea was simple: Instead of managing multiple files for each EJB, view the entire component through the Bean class itself. How can this be done? Java doesn't have the "attributes" that .NET is touting, but it does have Javadoc tags. We can place special @ tags into Javadoc comments, and have a Doclet tool that looks for these tags. The tool then generates the appropriate XML descriptors and interfaces for the given set of beans. XDoclet built on the EJBDoclet idea by extending the framework beyond the realm of EJBs. Now you can generate Web Services, Web Application descriptors, and even extend the system to fulfill your individual needs.

The @ tags have a standard format, containing a "namespace" and a "tagname" that belongs to that namespace. Then properties of the tag are passed in via name="value" arguments to the tag. Here is a generic example:

/**
 * @namespace:tag name="value" name2="value2" ...
 */

The current namespaces used are:

ejb: Standard EJB information (not vendor specific).
jboss: Information specific to the JBoss application server.
weblogic: Information specific to the BEA WebLogic application server.
webSphere: Information specific to the IBM WebSphere application server.
orion: Information specific to the Orion application server (Oracle).
castor: Generates mapping information for the Castor framework.
mvcsoft: Generates files for the MVCSoft EJB2.0 persistence manager.
soap: Generates SOAP descriptors.
struts: Generates struts-config.xml from Form and Action.
web: Generates web.xml configuration for Web Applications.
jsp: Generates tag library extension descriptor information.

As you can see, there is substantial support for many frameworks beyond the EJB world (hence the change of name from EJBDoclet to XDoclet).

Session Bean: Create a Session Bean Using the Special Javadoc Tags

Now that we have talked about the tool, let's get into the real example. We will start with a Session EJB. This EJB is part of the Xbeans framework, but for this example, it doesn't matter what the bean does. All we care about is how we take a bean class, "mark it up" with Javadoc tags, and then use XDoclet to generate the meta files for us.

The file ReceiverBean.java will hold the following method: documentReady(Document doc). This method takes a DOM document and passes it to the next Xbean in the chain.

Class Level Definitions

At the class level, we need to define:

The fact that this is a stateless session bean.
The JNDI name.
Environment entries.
Vendor specific attributes (WebLogic pooling information).

Tag: @ejb:bean

The only required attribute for this tag is to tell XDoclet the name of the bean. We will also define the type of bean, the JNDI name to bind the home stub, and the display name:

/**
 *   This is the EJB Receiver Xbean
 *
 *   @ejb:bean type="Stateless"
 *             name="ejbReceiver"
 *             jndi-name="org.xbeans.ejb.receiver.Receiver"
 *             display-name="EJB Receiver Xbean"
 *
 * ... other javadoc tags ...
 */
public class ReceiverBean implements SessionBean, DOMSource {

The most common attributes for the ejb:bean tag are:

name: The name of the EJB (used in descriptors).
type: Defines the bean's "type." For session beans, this is either Stateful or Stateless. For Entities, it is CMP or BMP.
jndi-name: Provides the JNDI name of the bean that will be used in the vendor-specific deployment descriptors (for "remote" interface).
local-jndi-name: Same as jndi-name, but used for the Local interface.
view-type: Indicates which "views" to the bean are to be supported. Either remote or local, or both.

As for all of the tags, check out the documentation to see the full list of options.

Tag: @ejb:env-entry

This tag defines an environment entry that will be configured in JNDI via the special java:comp/env context. We will define an environment entry that the bean will use to look up the next Xbean in the chain:

/**
 *   This is the EJB Receiver Xbean
 *
 * ... other javadoc tags ...
 *
 *   @ejb:env-entry name="channelBean" type="java.lang.String"
 *                  value="com.your.ChannelBean"
 *
 * ... other javadoc tags ...
 */
public class ReceiverBean implements SessionBean, DOMSource {

Tag: @weblogic:pool

Now we will configure the vendor-specific pooling characteristics, using WebLogic for the sake of argument. To denote that we are in a vendor-specific world, we have the weblogic namespace:

/**
 *   This is the EJB Receiver Xbean
 *
 * ... other javadoc tags ...
 *
 *   @weblogic:pool max-beans-in-free-pool="1000"   
 *                  initial-beans-in-free-pool="10"
 *
 * ... other javadoc tags ...
 */
public class ReceiverBean implements SessionBean, DOMSource {

This tag will configure the pooling parameters in the WebLogic-specific deployment descriptor (weblogic-ejb-jar.xml).

There are many other class-level tags allowing you to tweak anything that you can in the deployment descriptors. Here is a high-level glimpse at some of the "standard" tags that you may want to use in your development:

@ejb:bean: The only compulsory tag, it configures the basics for the bean.
@ejb:home: This tag provides information on the home interfaces. You can tell XDoclet to extend a custom interface, which home interfaces should be generated (none, remote, local,or both), the package the interfaces should be placed into, and more.
@ejb:interface: Similar to the home tag, but configures information related to the component interface (remote and/or local).
@ejb:finder: Defines finder methods on an entity beans home interface.
@ejb:select: Defines select methods on an entity beans home interface.
@ejb:pk: Defines the primary key for an entity bean. XDoclet can generate the primary key class for you.
@ejb:data-object: Data objects (a.k.a value objects) can be automatically generated for entity beans via this tag.
@ejb:ejb-ref: Configures EJB references.
@ejb:ejb-external-ref: Configures EJB references to beans that are located in other applications. Here you need to pass in information such as the type of bean, and home/remote classes.
@ejb:resource-ref: Configures a resource reference.
@ejb:security-role-ref: Configures a security role reference.
@ejb:transaction: Defines the transactional behavior for all methods in remote and home interfaces of this bean with transaction type of type. Can be overridden by using transaction tags on individual methods.
@ejb:permission: Allow the role role-name to call all methods in remote and home interfaces of this bean.
@ejb:security-identity: Specifies whether the caller's security identity is to be used for the execution of the methods of the enterprise bean or whether a specific run-as identity is to be used.

Method-Level Definitions

We want to tag at the method level. If we want a given method to be part of the remote interface, we simply tell XDoclet via a method level tag:

  /**
   *  The method that the sender uses to pass the Document
   *
   *  @ejb:interface-method view-type="remote"
   */
  public void documentReady(Document incomingDocument) {

You will always use this tag. You will go through the methods in your bean class, and if you wish a client to access it, you place this tag above the method signature. If you wanted the access to be via a local interface, you simply change the view-type value to local.

Here are some of the other EJB method-level tags:

@ejb:relation: Defines a relationship for an EJB2.0 CMP Entity bean.
@ejb:home-method: Define the method as an ejbHome* method.
@ejb:persistent-field: Creates the CMP field "X" in the generated CMP layer of type "foo", and concrete implementations of the getX/setX methods. For BMP, it will generate getX/setX methods that keep track of a dirty flag (so that ejbStore is only called when necessary).
@ejb:pk-field: Flags the primary key field.
@ejb:transaction: Defines the transactional behavior for this method (given a valid transactional attribute: NotSupported | Supports | Required | RequiresNew | Mandatory | Never.
@ejb:permission: Defines the methods permission (given a comma-separated list of roles that should be allowed to access this method).