EJB Construction Options

Once you have chosen your business- tier architecture and identified the EJB components required for your application, it is time to construct the components. What is the best way to build EJB components ? Ask any 10 J2EE programmers and you re likely to get 10 different answers.

It is both a strength and a weakness of J2EE that many different techniques and tools are available for the construction, configuration, and packaging of EJB components. Some integrated development environments, for example, provide a rich GUI-based set of tools for defining, building, and deploying EJB components. Other tools such as XDoclet and EJBGen are file-based and provide techniques more suitable for command-line build processes. Some tools are very expensive, while others are free or included in WebLogic Server product. The trick is to find a tool or technique that fits in your budget and supports your specific project needs.

A complete discussion of all tools available in the J2EE community is beyond the scope of this book and would, in any case, be rendered quickly out of date by advances in the capability and EJB-version support of each tool or product. We ll concentrate instead on three candidate techniques for building EJB components in WebLogic Server that support many of the EJB 2.0 and WebLogic Server-specific features and capabilities.

Manual Construction and Configuration

The first option, manual construction and configuration, simply refers to the manual creation and editing of all Java source files and XML descriptor files required for the EJB components in your project. Table 7.5 represents the minimum set of files and descriptors for a simple J2EE application containing two entity beans, PersonBean and AddressBean , and a single stateless session bean, PersonSessionBean .

Table 7.5:  Required Files for Simple EJB Application

Source File	Description
PersonBean.java	Person entity bean class file
PersonLocal.java	Person local interface file
PersonHomeLocal.java	Person home local interface file
AddressBean.java	Address entity bean class file
AddressLocal.java	Address local interface file
AddressHomeLocal.java	Address home local interface file
PersonSessionBean.java	Person session bean class file
PersonSessionLocal.java	Person session local interface file
PersonSessionRemote.java	Person session remote interface file
PersonSessionHomeLocal.java	Person session home local interface file
PersonSessionHomeRemote.java	Person session home remote interface file
ejb-jar.xml	Standard EJB descriptor file
weblogic-ejb-jar.xml	WebLogic EJB descriptor file
weblogic-cmp-rdbms-jar.xml	WebLogic CMP EJB descriptor file

Although Table 7.5 illustrates the typical requirement of at least three to five Java source files for each EJB component, it does not tell the whole story. The three descriptor files, ejb-jar.xml , weblogic-ejb-jar.xml , and weblogic-cmp-rdbms-jar.xml , grow substantially with each additional EJB component, and they represent a significant development and maintenance effort. Even with a good XML editor, the proper construction of descriptor files can become quite tedious and error-prone for typical applications. The manual creation of descriptors becomes all but impossible when complex container-managed relationships exist between EJB components in the application.

Best Practice  

Manual construction techniques may be suitable during the learning process to emphasize all of the required files, formats, and descriptor elements. Avoid manual construction for production applications if a suitable tool is available.

The next two sections discuss tools provided by WebLogic Server to improve the EJB construction process.

Using WebLogic Builder Utility

The WebLogic Server installation provides a utility called WebLogic Builder that provides a GUI-based technique for constructing the descriptor files for a set of EJB components. The developer is still responsible for creating all Java source files for each EJB component, but the three XML descriptor files listed in Table 7.5 are then created using the WebLogic Builder utility.

To use WebLogic Builder, construct the required Java source files by hand and compile them to a build directory or other staging area. Run WebLogic Builder from the Start menu in Windows or by starting the utility from the command line using the startWLBuilder script. The utility will create an initial set of descriptors by interrogating the EJB class files in the staging area, and then it will allow you to modify all descriptor information in the utility itself, avoiding hand-editing of the descriptor files.

Once the configuration is complete, use the Save menu option to write the generated descriptor elements to the build/META-INF directory for subsequent compilation and packaging. The main menu also provides the option to view the current descriptors as XML, although editing the XML directly to make desired changes is not allowed. Changes made to descriptor files between executions of WebLogic Builder will be picked up and reflected in the configuration display as long as the features present in the descriptors are supported by the utility. See the online documentation at http://edocs.bea.com/wls/docs81/wlbuilder/index.html for details on supported and unsupported elements in descriptors.

Finally, WebLogic Builder provides a mechanism for executing the EJB compiler to package the resulting EJB components and the ability to deploy the components to a running instance of WebLogic Server.

WebLogic Builder obviously represents an improvement over creating descriptor elements manually, especially for developers just coming up to speed with EJB and WebLogic Server-specific features. Unfortunately, the need to hand-code all Java source files for the EJB components and the difficulty inherent in keeping generated files in synch with source files as changes are made limit its usefulness .

Best Practice  

Consider using WebLogic Builder during the learning process to see how advanced EJB and WebLogic Server features are implemented in the descriptors.

The descriptor generation utility embedded in the WebLogic Builder code is available from the command line as a stand-alone utility as well. Create a jar file containing the compiled EJB classes, or compile them to a specific build directory structure, and use the following command:

 java weblogic.marathon.ddinit.EJBInit <jar file or build directory> 

Using the WebLogic EJBGen Utility

The final construction technique we ll examine in this text is the EJBGen utility packaged with WebLogic Server. The EJBGen utility generates selected EJB component source files and all required descriptor files using only the EJB bean class file. In other words, you write one Java source file per EJB component, and EJBGen creates everything else. The simple example represented in Table 7.5 now requires the manual construction of only three source files: PersonBean.java , AddressBean.java , and PersonSessionBean.java .

How can any tool accurately create all of the local, home, and remote interface files, standard descriptor elements, WebLogic Server-specific descriptor elements, CMP mapping information, primary key classes, and other files for an EJB component from the bean class file alone? The answer is that it can t, of course, without some help. In the case of EJBGen, this help is provided by the developer in the form of specially formatted Javadoc tags placed in the bean class file to control the creation of all of the supporting files and descriptors.

The EJBGen Javadoc tags come in two basic forms: class-level tags and method-level tags.

Class-Level EJBGen Tags

Class-level tags are used to configure attributes of the EJB component at the class level. Examples include the local or remote JNDI name , pool and caching information, finder methods , and the presence of relationships with other beans. Class-level tags are placed at the top of the bean class in the normal class-level Javadoc location, as shown in this simple example for the PersonSessionBean stateless session bean component:

 package mastering.weblogic.ch07.example1.ejb; import javax.ejb.*; import javax.naming.*;  /**   * @ejbgen:session   *   ejb-name = PersonSessionEJB   *   default-transaction = Required   *   max-beans-in-free-pool = 500   *   * @ejbgen:jndi-name   *   local = PersonSessionHomeLocal   *   remote = PersonSessionHomeRemote   *   */  public class PersonSessionBean      extends mastering.weblogic.ch07.example1.ejb.base.BaseSession  { ... } 

Entity beans use class-level tags to define database resources, table names , finders , and container-managed relationships in a similar manner:

 package mastering.weblogic.ch07.example1.ejb; import java.util.Collection; import javax.ejb.EntityContext; import javax.ejb.EJBException; import javax.ejb.FinderException; /**  * @ejbgen:entity  *   ejb-name = PersonEJB  *   default-transaction = Required  *   prim-key-class = java.lang.Integer   *   data-source-name = MasteringDataSource   *   table-name = PERSON   *   max-beans-in-cache = 1000  *  * @ejbgen:jndi-name  *   local = PersonHomeLocal  *  * @ejbgen:finder   *   signature="Collection findByLastName(java.lang.String lastname)"   *   ejb-ql =   "SELECT OBJECT(o) FROM PersonEJB as o WHERE o.lastName LIKE ?1"   *   * @ejbgen:finder   *   signature="Collection findByFirstName(java.lang.String firstname)"   *   ejb-ql =   "SELECT OBJECT(o) FROM PersonEJB as o WHERE o.firstName LIKE ?1"   *   * @ejbgen:relation   *   name = Person-Addresses   *   target-ejb = AddressEJB   *   multiplicity = one   *   cmr-field = addresses  *  */ public abstract class PersonBean      extends mastering.weblogic.ch07.example1.ejb.base.BaseEntity  { ... } 

See the online documentation at http://edocs.bea.com/wls/docs81/ejb/EJB_tools_.html for a complete list of class-level EJBGen tags. Most tag names follow the naming convention of their respective descriptor elements.

Tag values may be hard-coded in the tags, as shown in the earlier code listings, or may be placed in properties files with placeholders in the source files. For example, the max-beans-in-cache value could be defined using the placeholder cachesize :

 * @ejbgen:entity  *   ejb-name = PersonEJB  *   ...  *   max-beans-in-cache = ${cachesize}  

cachesize would then be defined in a properties file:

 # # Example ejbgen property file # cachesize = 1000 

Include -propertyFile ejbgen.properties in the command line used to invoke EJBGen to enable this feature.

Best Practice  

Use parameter substitution throughout class-level EJBGen tags to provide an easy way to change common settings and names without touching the source files.

Method-Level EJBGen Tags

Method-level tags are used to configure descriptor elements and interface classes at the individual method level. The most common method-level tags control the presence of a bean method in one or more of the EJB interface classes and the mapping of CMP fields to database columns .

For example, a stateless session bean must declare which methods defined in the bean class should be published to the remote and local interfaces for the bean. In our simple example there is only one method, sayHello() , and we ve configured EJBGen to place this method on both the local and remote interfaces:

  /**   * @ejbgen:local-method   * @ejbgen:remote-method   */  public void sayHello() throws EJBException  {     LOG.info("Hello from PersonSessionBean!"); } 

The EJBGen utility will now include a declaration for this method in the generated interface files PersonSessionLocal.java and PersonSessionRemote.java .

Entity beans using container-managed persistence (CMP) define both the interface information and the mapping from bean attributes to database columns with method-level tags:

  /**   * @ejbgen:cmp-field column = FIRSTNAME   * @ejbgen:local-method   */  public abstract String getFirstName();  /** @ejbgen:local-method */  public abstract void setFirstName(String pFirstName); 

Both getFirstName() and setFirstName() will be included in the generated interface file PersonLocal.java , and appropriate elements will be created to map the firstName attribute to the FIRSTNAME column in the database table defined at the class level.

CMP entity beans with container-managed relationships identify the abstract get and set methods associated with the relationships:

  /**   * @ejbgen:cmr-field   * @ejbgen:local-method   */  public abstract java.util.Collection getAddresses();  /** @ejbgen:local-method */  public abstract void setAddresses(java.util.Collection addresses); 

These simple method-level tags, combined with the ejbgen:relation class-level tags in both components, provide enough information for EJBGen to create all of the required descriptor code in ejb-jar.xml and weblogic-cmp-rdbms-jar.xml automatically to define the relationship for the CMP process.

Invoking the EJBGen Utility

The EJBGen utility is a Doclet intended for use with the Javadoc processor built in to the Java development environment. To invoke EJBGen from the command line, run javadoc with the following parameters:

 javadoc    -docletpath ejbgen.jar    -doclet weblogic.tools.ejbgen.EJBGen    <source file or directory> 

There are many additional command-line parameters for controlling the location of generated files, naming conventions for generated Java classes, and many other features. See the online documentation for a complete list.

One important command-line parameter required in the current release of EJBGen is the version-control parameter, normally -wls7 or -wls81 . This parameter forces the creation of WebLogic Server-specific descriptor files using the correct WebLogic Server schemas, thereby allowing all of the new caching and concurrency features.

The example command line assumes that ejbgen.jar is located in the current directory. Because the EJBGen utility is included in the standard weblogic.jar archive in /server/lib , the -docletpath could point to that archive file rather than a stand-alone copy of ejbgen.jar :

 javadoc -docletpath %WL_HOME%\server\lib\weblogic.jar ... 

Because the tool is constantly undergoing revision and improvements, the EJBGen version packaged with WebLogic Server may not be sufficient for your particular requirements. Cedric Beust, one of the WebLogic Server engineers and the creator of the EJBGen utility, makes the latest version available at his Web site, http://www_.beust.com/ejbgen, and this version may be downloaded and used in place of the version in weblogic.jar . There is also an active mailing list for EJBGen. Now that EJBGen is an officially supported part of WebLogic Server 8.1, however, we expect that the included version will be kept up to date as new versions of the product are released. WebLogic Workshop 8.1 also fully supports EJBGen-based EJB development in that environment.

The EJBGen utility may also be invoked from within Ant build scripts using either javadoc tasks or exec tasks with appropriate command-line arguments. The downloadable example code for bigrez.com includes a build.xml file with an ejbgen task to create all of the EJB components for the example.

If it is not already obvious, let s make it clear: EJBGen is a very powerful, useful utility that provides a tremendous amount of functionality and flexibility. We ll use it extensively on bigrez.com , and we highly recommend it for your WebLogic Server EJB development efforts.

Best Practice  

The EJBGen utility provides a very powerful technique for building EJB applications and should be considered by every new EJB development effort.