vDoclet - EJB

What is vDoclet/EJB?

"vDoclet/EJB" is a set of vDoclet templates that can be used to generate EJB-related files. It's sometimes a hassle to maintain hand-coded remote and local-interfaces and deployment-descriptors, so we generate these things from your EJB implementation class.

Specifically, vDoclet/EJB is able to generate:

Derived Java code:

Remote-view interfaces (ie. remote and remote-home interfaces)
Primary key classes (for entity-beans)
"CMP-1.1 sub-classes", allowing your CMP-2.0 entity-bean to run in a CMP-1.1 container

Deployment-descriptors for:
- EJB-1.1
- JBoss 2.x
- WebLogic 6.x (CMP-1.1 only)

Quick-start

The first step is to add vDoclet/EJB tags to your raw EJB implementation classes. Once you know what tags to use, it's pretty easy.

EJB type

Add a class-level Javadoc tag that identifies what type of EJB this class defines, e.g. @ejb-entity, @ejb-session.

/**
 * @ejb-entity
 */
public abstract class StoryBean {

Remote view

If you want this EJB to be accessible thru a remote-interface, add a class-level @ejb-remote tag.

/**
 * @ejb-entity
 * @ejb-remote
 */
public abstract class StoryBean {

Then, add @ejb-remote tags to the Javadoc for all the methods you wish to make available via the remote-view.

    /**
     * @ejb-remote
     */
    public abstract String getAuthor();

For session-beans, and bean-managed entities, that's pretty much it.

Container-managed persistence

For container-managed entities, you need to give the container a add a little more detail. vDoclet/EJB assumes that you've written your CMP entities in the EJB-2.0 style, with abstract set- and get-methods for the your persistent-fields. If necessary, we'll generate a subclass that can be deployed in an EJB-1.1 container.

Start by mapping the bean to a database table using the @ejb-cmp-table tag:

/**
 * @ejb-entity
 * @ejb-remote
 * @ejb-cmp-table STORY
 */
public abstract class StoryBean {

Next, map persistent fields to database columns, by adding @ejb-cmp-column tags to the get-methods:

    /**
     * @ejb-remote
     * @ejb-cmp-column AUTHOR
     */
    public abstract String getAuthor();

vDoclet/EJB will generate a primary-key class for your entity if you add a @ejb-key-generate tag:

/**
 * @ejb-entity
 * @ejb-remote
 * @ejb-cmp-table STORY
 * @ejb-key-generate
 */
public abstract class StoryBean {

Tell it which persistent-fields to include in the key by marking them with @ejb-key-field:

    /**
     * @ejb-remote
     * @ejb-key-field
     * @ejb-cmp-column ID
     */
    public abstract long getId();

Other tags

See the Tag Reference section below for details of all the tags supported.

EJB bundles

When you run vDoclet/EJB on your code-base, it identify a number of source-files that define EJBs. In vDoclet-speak, we call the resulting collection of EJBs an "EJB bundle". The bundle represents a deployment-unit (EJB-JAR file).

Bundle properties

Most of the information that vDoclet/EJB uses to do it's job comes from Javadoc tags in your source-code. However, some information applies to the entire deployment-unit, rather than specific beans; we get this info from the "bundle properties" file. The bundle-properties file is called "vdoclet-ejb.properties", and lives in the root directory of your code-base.

Information that we get from the bundle-properties file includes:

DataSource definitions (for CMP)
Security roles
Defaults for bean-specific properties (timeouts, etc.)

CMP DataSource

If you have container-managed entity-beans, you'll need to set the datasource property in vdoclet-ejb.properties:

datasource = java:/newsDataSource

Running vDoclet/EJB

Run vDoclet/EJB from Ant as follows:

<target name="ejb/generate">
  <vdoclet srcDir="ejb/java"
           destDir="build/ejb/java"
           template="vdoclet/ejb/generate.vm">
    <classpath>
      <path refid="j2ee.classpath" />
      <pathelement location="lib/vdoclet.jar" />
    </classpath>
  </vdoclet>
</target>

An Example

As an example, consider an EJB from the "newstest" example included with vDoclet. "StoryBean" is a CMP entity-bean, representing a news-story. From the implementation-class, StoryBean.java, vDoclet/EJB generates:

Remote-view:	`Story.java` `StoryHome.java`
Primary-key:	`StoryKey.java`
CMP-1.1 subclass:	`StoryBeanSub.java`
EJB deployment-descriptor:	`ejb-jar.xml`
JBoss deployment-descriptors:	`jboss.xml` `jaws.xml`
WebLogic deployment-descriptors:	`weblogic-ejb-jar.xml` `weblogic-rdbms11-persistence-600.xml`

Tag Reference

The following is a partial list of the tags supported by vDoclet/EJB.

Key

@class-tag: apply to the EJB implementation class
@method-tag: apply to a method of the implementation class
bundle-property: enter into the bundle-property file

Naming

@ejb-base-name name: Set a common "base-name", used to generate names for derived interfaces, etc. (Default: the fully-qualified name of the bean-class, minus any "Bean" suffix.)
@ejb-name name: Set the name of the deployed EJB. (Default: "{@ejb-base-name}")

Session-beans

@ejb-session: Mark a session-bean.
@ejb-session-type type: type = Stateless | Stateful

Entity-beans

@ejb-entity: Mark an entity-bean.
@ejb-persistence-type type: type = Container | Bean; Determines whether persistance for this entity is managed by the Container (CMP) or by the Bean (BMP).
@ejb-cmp-table table: Map fields of the entity to the named database table.
@ejb-cmp-column column: Mark a get-method that defines a container-managed persistent field. Map the field to the named database column.
@ejb-key-generate: Generate a primary-key class for this bean, including all the marked key-fields.
@ejb-key-field: Mark a get-method that defines a key-field.
@ejb-isModified-generate: Generate a sub-class that overrides persistent field set-methods, setting an isModified() flag if a field is changed.
datasource = dataSourceUrl: Define the DataSource used for CMP.

Abstract beans

@ejb-abstract: Mark an "abstract" EJB. A corresponding remote interface will be generated, but the bean will not be deployed.

Remote-view generation

@ejb-remote: Generate remote-view interfaces for this bean. (This is implicit when ejb.version="1.1").
@ejb-remote: Include this method in the remote-view.
@ejb-remote-class className: Set the name of the remote-view interface. (Default: "{@ejb-base-name}")
@ejb-remote-extends className: Provide a super-class for the remote interface.
@ejb-remote-home-class className: Set the name of the remote-view home-interface. (Default: "{@ejb-remote-class}Home")
@ejb-remote-home-jndi jndiName: Set the JNDI-name for this EJB. (Default: "{@ejb-remote-home-class}")

Transactions

@ejb-transaction-type type: type = Container | Bean; Determines whether a session-bean's transactions are managed by the container or the bean.
@ejb-transaction attribute: attribute = NotSupported | Required | Supports | RequiresNew | Mandatory | Never
@ejb-transaction attribute: attribute = NotSupported | Required | Supports | RequiresNew | Mandatory | Never; Set the default transaction attribute for methods of this bean.

Security

@ejb-permission role: Allow the named role to access the tagged method.
@ejb-permission role: Allow the named role to access methods of this bean for which no explicit permissions have been specified.