Developing Entity EJBs

Enterprise JavaBeans (EJBs) are application components that implement the EJB architecture specification and are part of the Java 2 Enterprise Edition (J2EE) platform. EJBs are ideally suited for the development and deployment of distributed, scalable, transactional, secure, portable, component-based business applications.

EJB-based business applications require an EJB container for runtime execution and all J2EE-compliant application servers, including WebLogic 8.1, provide an EJB container.

The principal motivation underlying EJB architecture is separation of concerns: it separates the application infrastructure–related concerns such as transaction processing and security from core application concerns such as business logic. Briefly, the EJB architecture achieves this separation of concerns by specifying a separation of responsibilities between an EJB container and an EJB developer. For example, it is the responsibility of an EJB container to transparently implement transaction processing, and it is the responsibility of an EJB developer to implement business logic. An EJB container may require some hints to do its job, but providing such hints to the container (through XML-based deployment descriptors) is very inexpensive compared to actually implementing these infrastructure-related activities. Overall, this strategy of separation of concerns makes business application development much more efficient than the alternatives.

There are four versions of the EJB architecture specification: 1.0, 1.1, 2.0, and 2.1. For all practical purposes, EJB version 1.0 is obsolete and the latest version, 2.1, is too recent to be widely available. BEA WebLogic Server 8.1 supports both versions 1.1 and 2.0. We strongly recommend EJB version 2.0 while developing in WebLogic Server 8.1.

An entity bean is an EJB. Besides the general motivation behind an EJB, the specific motivation behind using an entity bean is to provide an in-memory, shareable, object-oriented view for a business-domain entity that exists in persistent storage, typically as a row in a table in a relational database. In this article, the specific issues associated with the design, development, and deployment of an Entity EJB in the context of the WebLogic Server 8.1 environment are discussed. For a general tutorial on EJB technology, we recommend the J2EE tutorial at http://java.sun.com/j2ee.

Overview
Entity beans are designed to manage data in a relational database. Entity EJB development in BEA WebLogic Server 8.1 consists of designing, generating, packaging, and deploying an EJB.

From a design point of view, entity beans can be classified along two orthogonal axes: persistence and access. Along the axis of persistence, there are two types of entity beans: bean-managed persistence (BMP) and container-managed persistence (CMP). In the case of CMP, the EJB container manages the persistence of an entity bean; in the case of BMP, an entity bean developer through specified Java code manages the persistence of an entity bean. The choice between CMP and BMP is mutually exclusive. Along the axis of access, there are two types of entity beans: remote and local. A remote entity bean provides transparency of location and can be accessed from a different Java virtual machine; a local entity bean, by contrast, can only be accessed from within the same application server. The choice between local and remote is not mutually exclusive and one can design beans with a dual interface.

In the EJB architecture specification, each entity EJB component is comprised of a set of specified Java classes and a set of specified XML deployment descriptors. EJB packaging consists of packaging all the specified EJB Java class files and XML deployment descriptor files in a Java Archive (JAR) file. If there are helper Java class files that an entity EJB depends upon, such class files can either be included within the EJB JAR file, or can be packaged separately in a different JAR file.

EJB deployment consists of either directly deploying the EJB JAR file and any dependent JAR files within BEA WebLogic Server 8.1, or first packaging the EJB jar file and any dependent JAR files within an enterprise application archive (EAR) file, and then deploying the EAR file within WebLogic Server 8.1.

Designing an EJB
The principal design choices in the design of an entity bean are:

1. Whether to design a CMP or BMP entity bean
2. Whether to design a local, remote, or dual interface entity bean
3. Whether to design a coarse-grained or fine-grained entity bean
4. Whether to use data transfer objects or use individual get and set methods to access data from an entity EJB

These design choices for developing an entity EJB are discussed below.

CMP vs BMP
Keeping in mind that there may be rare legitimate exceptions to this rule, in general we strongly recommend using a CMP design. There are three main reasons for selecting a CMP over BMP.

1. Compared to BMP, CMP provides portability across various databases because CMP entity beans do not contain any database-specific persistence code. CMP is easy to design, implement and maintain.
2. In general, CMP has better performance than BMP because the database-specific code is automatically generated by an EJB container and is optimized for the target database.
3. CMP makes it very easy to programmatically navigate through a network of related EJBs, using local interfaces.

Local, Remote, or Dual Interface
Because CMP manages relationships between entity EJBs through a local interface, we strongly recommend always providing a local interface. We think a remote interface is rarely needed, but if careful evaluation demonstrates the need for a remote interface, go ahead and design a dual interface.

Local interfaces provide optimized access to an EJB by local clients; remote method invocation (RMI) semantics are not required to access an EJB with local interfaces by a local client.

Remote clients, which are located on a different virtual machine than the EJB container, require RMI and remote interfaces to access an EJB. The obvious theoretical disadvantage of solely designing a local entity is that only clients in the same application server are able to access the entity bean. However, this is only a theoretical disadvantage because in practice entity EJBs are rarely accessed from outside an application server.

Coarse Grained vs Fine Grained
This is a very controversial subject so carefully calibrate various opinions on this subject against your personal experience. Our opinion is that entity EJBs are most often used to represent individual entities in an application's business domain, so go ahead and make entity beans as fine grained as possible, but confine the design to only providing a local interface. The controversy around this issue started during EJB architecture specification 1.x versions, when entity EJBs could only be accessed through a remote interface. Any reasonable arguments against using fine-grained entity EJBs formulated during EJB 1.x versions have become obsolete in EJB architecture specification 2.0 and should be deprecated. Please be warned: there are some experts who would disagree with us, so we encourage you to experiment and form your own opinion on this subject.

Data Transfer Objects vs Get and Set Methods
This is another controversial subject. Our view is as follows:

• Expose all the get accessor methods for the CMP persistent fields in the local interface of an entity EJB.
• Create wrapper set methods for each CMP persistent field that is not part of an entity EJB's primary key, and expose these wrapper methods in the local interface of an entity EJB. The motivation behind the wrapper methods is that CMP requires all persistent fields to have abstract setXXX methods, and if you need to do any validation within these setXXX methods, you can do so in the wrapper method and then call the corresponding setXXX method. If such validation is not needed, then it is quite appropriate to skip the wrapper methods and directly include the setXXX methods through the local interface.
• In the rare circumstance that you need a remote interface for an entity EJB, define a data transfer object per entity EJB, and expose a get and set method using the data transfer object as a parameter in the remote interface of an entity EJB.

Generating and Packaging an EJB
In the EJB architecture specification, each entity EJB component is comprised of a set of specified Java classes and a set of specified XML deployment descriptors:

1. A required bean class that implements the core functionality of an entity bean
2. A remote interface, local interface, or dual interface that provides an appropriate client view for the entity bean
3. A remote home interface, local home interface, or dual home interface that provides an appropriate interface for life-cycle management of an entity bean
4. In the case of entity beans with a composite primary key, a required primary key class
5. An ejb-jar XML deployment descriptor file, as specified by EJB architecture specification version 2.0
6. A vendor-specific weblogic-ejb-jar XML deployment descriptor file, as specified by BEA WebLogic Server 8.1
7. In the case of a CMP entity bean, a vendor-specific weblogic-cmp-rdbms-jar XML deployment descriptor file, as specified by BEA WebLogic Server 8.1

The example entity EJB used here is a CMP entity EJB with a remote interface and is named AccountEJB. It can be found in the included sample files installed with WebLogic Server 8.1 under /weblogic81/samples/server/examples/src/examples/ejb20/basic/containerManaged directory.

The entity bean EJB classes and interfaces may be generated with the EJBGen tool.

EJBGen
EJBGen is an EJB 2.0 code generator that generates the local/remote, local-home/remote-home interfaces, primary key class, and the deployment descriptors from an EJB bean class. EJBGen tags are used in the EJB bean class to specify the different EJB design configurations (for example, local/remote and CMP/BMP). In WebLogic Server 8.1 SP01, the EJBGen classes are included in /weblogic81/server/lib/weblogic.jar. In WebLogic Server 8.1 SP02 & SP03, the EJBGen classes are included in /weblogic81/server/lib/ejbgen.jar file. Add ejbgen.jar to Classpath to use the EJBGen tool.

EJBGen is invoked with the command:

javadoc -docletpath ejbgen.jar -doclet weblogic.tools.ejbgen.EJBGen
<EjbBeanClass>.java

Some of its options are:

• -d [directory]: Directory in which the EJB classes/interfaces and deployment descriptors are created.
• -descriptorDir [directory]: Directory in which the deployment descriptors are created.
• -wls7: With the –wls7 option WebLogic Serve 7.1 deployment descriptors are generated.

If an earlier version of the BEA WebLogic Server deployment descriptors are to be converted to WebLogic Server 8.1 deployment descriptors, use the DDConverter.

DDConverter
DDConverter is a command-line tool to convert earlier versions of XML deployment descriptors (ejb-jar.xml, weblogic-ejb-jar.xml, and weblogic-cmp-rdbms-jar.xml) to the current version of the WebLogic Server. DDConverter is invoked with the command:

java weblogic.ejb20.utils.DDConverter [options] –d destDir file1 [file2...]

In this command, the file is an EJB 1.0 deployment descriptor or a JAR file containing EJB 1.1 deployment descriptors. Some of the DDConverter options are:

• -d destDir: Directory for the output deployment descriptor.
• -EJBVer output EJB version: Specifies the output EJB version; default is 2.0.

Before you can deploy an EJB, it has to be packaged in a JAR or an EAR file.

EJB JAR File
The structure of an EJB JAR file consists of the EJB classes and interfaces, and the META-INF directory containing the deployment descriptors. Create a directory, source/ejb20/basic/containerManaged, and a directory source/ejb20/basic/containerManaged/META-INF. Copy Account.java, AccountBean.java, AccountHome.java, and ProcessingErrorException.java from the /weblogic81/samples/server/examples/src/examples/ejb20/basic/containerManaged directory to the source/ejb20/basic/containerManaged directory. Copy ejb-jar.xml, weblogic-ejb-jar.xml, and weblogic-cmp-rdbms-jar.xml from the /weblogic81/samples/server/examples/src/examples/ejb20/basic/containerManaged directory to the source/ejb20/basic/containerManaged/META-INTdirectory.

Create a JAR file from the compiled EJB Java class files and the deployment descriptors with Apache Ant, a Java-based build tool. The Apache Ant tool requires a build file. Create a build.xml file (see Listing 1) with targets to compile the EJB source files and generate a JAR file from the compiled class files.

Copy the build.xml file to the /source directory. Run the ejb-jar target in the build.xml. An EJB JAR file is generated in the source/dist directory. The EJB JAR may be compiled with the BEA WebLogic appc compiler. Compiling with the appc compiler is not required, but it is recommended by BEA WebLogic.

Appc
The appc compiler generates container classes from the EJB JAR file and validates the deployment descriptors. The advantage of compiling the EJB JAR class files with appc prior to deploying the EJB JAR file is that the errors, which might be generated when the EJB JAR is deployed on the server, are identified. To run the appc compiler weblogic.jar should be in the Classpath. Appc is invoked with the command:

java weblogic.appc [options] <jar file or directory>

Some of the appc options are:

• -output<file>: Specifies a output directory
• -keepgenerated: Keeps the generated .java files
• -compiler<java>: Sets the Java compiler to use

Deploying an EJB
A data source with a Java Naming and Directory Interface (JNDI) name is required to deploy an entity EJB JAR file. Creating a Connection Pool is explained in my previous article (WLDJ, Vol. 3, issue 1). Create a Tx Datasource with the JNDI name "examples-dataSource-demoPool". The JNDI name should be the same as that specified in the <data-source-name> element in the weblogic-cmp-rdbms-jar.xml deployment descriptor.

To deploy the entity EJB JAR file select the Deployments>EJB Modules node in the administration console. Click on the Deploy a new EJB Module link (see Figure 1).

A Deploy an EJB Module frame is displayed (see Figure 2). Select the upload your files(s) link in the Deploy an EJB Module frame. An Upload and Install an Application or Module frame will be displayed. Select an EJB JAR file to upload and click on the Upload button.

The Deploy an EJB Module frame is displayed. Select the myserver link. A list of subdirectories in the myserver directory gets displayed. Click on the upload directory link. In the upload directory select the EJB JAR to deploy and click on the Target Module button (see Figure 3). A Select Targets for this EJB module frame is displayed (see Figure 4).

Select one or more target servers in the Select targets for this EJB module frame and click on the Continue button. In the frame displayed, in the Name field, specify a name to be used for the EJB module to be deployed (see Figure 5).

Click on the Deploy button to deploy the EJB JAR file. The EJB JAR is deployed on the server and an EJB node gets added to the EJB Modules node (see Figure 6).

The EJB application may also be deployed to the BEA WebLogic Server by copying the EJB JAR file to the applications directory in the domain the application is to be deployed.

BEA WebLogic provides some recommendations for deploying an EJB on the WebLogic server.

1. EJBs should be deployed as an EJB JAR in an enterprise archive application (EAR application) to facilitate application migration and modification.
2. EJBs that have a reference to other EJBs should be deployed in the same application; the enable-call-by-reference element in weblogic-ejb-jar.xml should be set to True for better performance.
3. EJBs deployed on a WebLogic server cluster should be deployed homogeneously to each managed server in the cluster. If an EJB is deployed on only a single server in a cluster compile the EJB with the appc compiler before deploying.

Conclusion
EJB application development consists of creating the EJB classes, compiling the EJB classes and creating a JAR file from them, and deploying the EJB JAR to the BEA WebLogic Server. EJB application performance is improved by following some of the recommendations in designing, generating and deploying an EJB JAR to the BEA WebLogic Server.

Resources

Programming WebLogic Enterprise JavaBeans: http://edocs.bea.com/wls/docs8.1/ejb/index.html