Building CMP Entity Beans

When creating standard CMP entity beans, the standard ejb-jar.xml descriptor file is used to define the persistent fields for the CMP entity bean, its primary key class, and the nature of its relationships with other entity beans. The weblogic-ejb-jar.xml descriptor file hosts the WebLogic counterpart to this information. In addition, you need to create a weblogic-cmp-rdbms-jar.xml descriptor file that maps these "virtual fields" to actual table columns in the underlying database. The weblogic-cmp-rdbms-jar.xml file allows you to configure all aspects of WebLogic's RDBMS-based persistence services for CMP entity beans. It lets you specify the database columns associated with the persistent fields, the primary key columns that identify the EJB instances, and the foreign key columns that implement the EJB relationships.

Due to the sheer number of descriptor files and source files that need to be maintained, the easiest approach to developing entity beans is to use EJBGen, or IDEs such as WebLogic Workshop. The following sections show a working example of this approach, together with an outline of the descriptor files. If you don't want to use EJBGen, then you have to create, by hand, the same set of descriptor files described in the following sections.

11.1.1 A Simple EJB

Example 11-1 shows the complete code for a simple CMP entity bean. It uses WebLogic's GenericEntityBean class to simplify the development.

Example 11-1. The Department EJB abstract class

import javax.ejb.*;
import weblogic.ejb.*;

/**
 * @ejbgen:entity prim-key-
 * ejb-name = "DepartmentEJB"
 * data-source-name = "MyDataSource"
 * table-name = "tblDepartment"
 * abstract-schema-name = DepartmentSchema
 * @ejbgen:jndi-name
 * local = "ejb.DepartmentEJBLocalHome"
 * @ejbgen:finder ejb-ql="SELECT OBJECT(o) from DepartmentSchema as o" 
 * generate-on="Local" signature="Collection findAll( )"
 */
abstract public class DepartmentEJB extends GenericEntityBean implements EntityBean {
 /**
 * @ejbgen:cmp-field primkey-field="true" column="Id"
 * @ejbgen:local-method
 */
 public abstract Integer getId( );

 /**
 * @ejbgen:local-method
 */
 public abstract void setId(Integer arg);

 /**
 * @ejbgen:cmp-field column="Name"
 * @ejbgen:local-method
 */
 public abstract String getName( );

 /**
 * @ejbgen:local-method
 */
 public abstract void setName(String arg);

 public java.lang.Integer ejbCreate(java.lang.Integer Id) {
 setId(Id);
 return null; 
 }

 public void ejbPostCreate(java.lang.Integer Id) {}
}

The EJBGen tags capture a lot of additional metadata and deployment information about the Department EJB:

• The EJB has two CMP fields, Id and Name, both identified by the ejbgen:cmp-field tags. The primary-key field attribute also indicates that the Id field has been set as the EJB's primary key field.
• The EJB defines a findAll( ) finder method, which simply returns the collection of Department EJB instances.
• The EJB fields map to the columns of a table called tblDepartment.
• Other data, such as the EJB name, its JNDI name, and the data source name, are also are specified via the tags.

11.1.2 Associated Java Files

EJBGen now can generate a number of Java files using this code. For example, it can generate the EJB's local home and local interface files. Example 11-2 shows the local home interface generated for the Department EJB.

Example 11-2. Home interface for the Department EJB

public interface DepartmentLocalHome extends EJBLocalHome {
 public Collection findAll( ) throws FinderException;
 public DepartmentLocal findByPrimaryKey(Integer primaryKey) throws FinderException;
 public DepartmentLocal create(Integer Id) throws CreateException;
}

Note how EJBGen is able to insert the findAll( ) method automatically, due to the presence of the ejbgen:finder tag in the Department EJB abstract class. More interestingly, EJBGen also will generate a transfer object. Example 11-3 shows the transfer object that is generated for the Department EJB.

Example 11-3. Transfer object for the Department EJB

public class DepartmentValue implements Serializable {
 public DepartmentValue( ) {}
 public DepartmentValue(java.lang.Integer id, java.lang.String name) {
 m_id = id;
 m_name = name;
 }
 private java.lang.Integer m_id;
 private java.lang.String m_name;

 public java.lang.Integer getId( ){ return m_id; }
 public void setId(java.lang.Integer n){ m_id = n; } 

 public java.lang.String getName( ){return m_name;}
 public void setName(java.lang.String n){m_name = n;}

 public boolean equals(Object other) { /* ... */ }
 public int hashCode( ) { /* ... */ }
}

11.1.3 EJB Deployment Descriptor

EJBGen also generates the deployment descriptors needed to deploy the Department EJB successfully: ejb-jar.xml, weblogic-ejb-jar.xml, and weblogic-cmp-rdbms-jar.xml. ejb-jar.xml is the standard entity descriptor file, and we won't consider it any further. Example 11-4 shows the WebLogic-specific weblogic-ejb-jar.xml descriptor file that is generated for the Department EJB.

Example 11-4. The weblogic-ejb-jar.xml descriptor for the Department EJB

 
 DepartmentEJB
 
 
 
 WebLogic_CMP_RDBMS
 8.1
 META-INF/weblogic-cmp-rdbms-jar.xml
 
 
 
 ejb.DepartmentEJBLocalHome
 

This file also can host other bean configuration properties, such as the cache and pool settings. The persistence-use tag in the weblogic-ejb-jar.xml file lets you specify an identifier for the type of persistence that is used by the entity EJB. It also lets you specify the location of the file that provides additional information about the abstract persistence model. Example 11-5 shows how the referenced weblogic-cmp-rdbms-jar.xml descriptor maps the EJB's persistent fields defined in the ejb-jar.xml file to the actual database columns.

Example 11-5. Configuring RDBMS-based EJB persistence

 DepartmentEJB
 MyDataSource
 
 tblDepartment
 
 id
 Id
 
 
 name
 Name
 
 

Let's take a closer look at the information captured in this deployment descriptor:

• The data-source-name element specifies the JNDI name of a configured data source that provides the EJB container with a pool of connections to the underlying database. Remember that if your entity bean supports transactions, you must specify the JNDI name of an XA-aware data source. You also could associate a separate data source (and therefore a separate connection pool) with each CMP entity EJB.
• The table-map element includes the name of a database table, and maps the CMP fields for the entity bean to its columns. You easily could map the same CMP fields for the entity bean to columns that are spread across multiple database tables. In that case, you need to ensure that the primary key CMP field is mapped to the primary key column(s) in each table involved. Also, you must ensure that there are no referential integrity constraints between the tables that map to the entity bean, or else you may encounter a runtime error when you attempt to remove an entity EJB instance.
• The database-type element indicates the type of the underlying DBMS; it can take one of the following values: DB2, Informix, Oracle, SQLServer, Sybase, and POINTBASE. WebLogic can use this element for various tasks, such as automatic table creation, caching EJB relationships, or any task that is specific to the actual database.

11.1.4 Creating the EJB JAR

Now you are ready to build the EJB JAR using a staging folder or JAR file. The content will include the compiled Java classes and the deployment descriptors:

/com/oreilly/ejbs/DepartmentLocalHome.class
/com/oreilly/ejbs/DepartmentLocal.class
/com/oreilly/ejbs/DepartmentEJB.class
/com/oreilly/ejbs/DepartmentValue.class
/META-INF/ejb-jar.xml
/META-INF/weblogic-ejb-jar.xml
/META-INF/weblogic-cmp-rdbms-jar.xml

In order to create the EJB JAR, use the appc compiler:

 java weblogic.appc -output ejb_foo.jar staging-dir

In WebLogic 7.0, you need to use the ejbc compiler:

 java weblogic.ejbc staging-dir ejb_foo.jar