CMP Entity Bean Example

Instead of writing cumbersome JDBC code, the CMP bean writer provides only the business logic and deployment descriptors. CMP can offer the developer faster development time and better performance than BMP entity beans. The CMP entity bean class is abstract. This enables the EJB container to implement persistence logic by generating a class that extends the bean class.

Container-Managed Fields

Every container-managed entity bean has a set of container-managed fields, which are saved and loaded from the database. Generally, each container-managed field corresponds to a column in a relational database. For instance, in a Student entity bean, container-managed fields could be the name, ssn (Social Security number), and grade.

Writing getXXX and setXXX Methods

The bean provider cannot declare container-managed fields. Instead, the bean writer declares abstract get and set methods for each container-managed field. For instance, instead of declaring a private String name in the bean class, the bean provider uses public abstract void setName(String name); and public abstract String getName();. These get and set methods are public and abstract because the EJB container provides the actual implementation. While this requirement seems a bit strange at first, it allows the EJB container to detect when fields are read and written. This enables the EJB container to optimize the calls to the database. For instance, if no fields are updated within a transaction, the WebLogic Server EJB container does not write back to the database.

Declaring the Container-Managed Fields

Each container-managed field must be declared in the ejb-jar.xml deployment descriptor. This enables the container to match the container-managed fields with the setXXX and getXXX methods in the bean class. The bean provider then includes the database mapping in a separate CMP deployment descriptor named weblogic-cmp-rdbms.xml, which contains the database table name and a mapping between each container-managed field and its corresponding database column.

A CMP entity bean must set the values of the primary key fields in its ejbCreate method. Then the ejbCreate method always returns null.

The EJB container determines the primary key value by extracting the primary key fields after the ejbCreate has returned. The bean needs to set the primary key fields in ejbCreate because the container does the database insert after it calls ejbCreate.

The convention of returning null instead of void enables a BMP entity bean to extend a CMP entity bean (more about this later). The Java language specification does not allow you to overload a method while changing only the return type. Therefore, the bean writer could not have a BMP version in which ejbCreate returns the primary key type and extend that bean with a CMP version returning void.

Student CMP Example

Our first example demonstrates the simplicity of CMP. This is the StudentBean:

package com.learnweblogic.examples.ch9.cmp;

import java.util.Collection;

import javax.ejb.EntityContext;
import javax.ejb.EntityBean;

public abstract class StudentCMPBean implements EntityBean {

  private EntityContext ctx;

  // container-managed fields
  public abstract String getName();
  public abstract void setName(String n);

  public abstract Integer getSsn();
  public abstract void setSsn(Integer ssn);

  public abstract int getGrade();
  public abstract void setGrade(int gr);


  public void setEntityContext(EntityContext c) {
    ctx = c;
  }

  public void unsetEntityContext() {
    ctx = null;
  }


  public Integer ejbCreate(String name, int ssn, int grade)
  {
    setName(name);
    setSsn(new Integer(ssn));
    setGrade(grade);

    return null;
  }

  // This implementation requires no post-create initialization
  // so this required method is empty
  public void ejbPostCreate(String name, int ssn, int grade) {}


  // These methods are required by the EntityBean interface but
  // are not used in this implementation.

  public void ejbRemove() {}

  public void ejbLoad() {}

  public void ejbStore() {}

  public void ejbActivate() {}
  public void ejbPassivate() {}

}

The bean class contains get and set methods for the bean's three container-managed fields: name, ssn, and grade.

ejb-jar.xml Deployment Descriptor

The ejb-jar.xml deployment descriptor specifies that our bean use CMP and the EJB 2.0 model. The <cmp-field> elements specify all the container-managed fields in this CMP entity bean. Note the EJB-QL query element for the findStudentsInGrade method.

<?xml version="1.0"?>

<!DOCTYPE ejb-jar PUBLIC
"-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN"
"http://java.sun.com/dtd/ejb-jar_2_0.dtd">


<ejb-jar>
  <enterprise-beans>
    <entity>
      <ejb-name>StudentCMPEJB</ejb-name>
      <home>com.learnweblogic.examples.ch9.cmp.StudentHome</home>
      <remote>com.learnweblogic.examples.ch9.cmp.Student</remote>
      <ejb-class>
        com.learnweblogic.examples.ch9.cmp.StudentCMPBean
      </ejb-class>
      <persistence-type>Container</persistence-type>
      <prim-key-class>java.lang.Integer</prim-key-class>
      <reentrant>False</reentrant>
      <cmp-version>2.x</cmp-version>
      <abstract-schema-name>StudentCMPBean</abstract-schema-name>

      <cmp-field>
        <field-name>name</field-name>
      </cmp-field>
      <cmp-field>
        <field-name>ssn</field-name>
      </cmp-field>
      <cmp-field>
        <field-name>grade</field-name>
      </cmp-field>

      <primkey-field>ssn</primkey-field>

      <query>
        <description>
            finds students in a given grade
        </description>
        <query-method>
          <method-name>findStudentsInGrade</method-name>
          <method-params>
            <method-param>int</method-param>
          </method-params>
        </query-method>
        <ejb-ql>
          <![CDATA[FROM StudentCMPBean s WHERE s.grade = ?1]]>
        </ejb-ql>
      </query>

    </entity>

  </enterprise-beans>


  <assembly-descriptor>
    <container-transaction>
      <method>
        <ejb-name>StudentCMPEJB</ejb-name>
        <method-name>*</method-name>
      </method>
      <trans-attribute>Required</trans-attribute>
    </container-transaction>

  </assembly-descriptor>
</ejb-jar>

weblogic-ejb-jar.xml Deployment Descriptor

The CMP EJB also requires a weblogic-ejb-jar.xml deployment descriptor that contains WebLogic Server–specific options and settings. The persistence stanza, required for CMP entity beans, specifies that this CMP entity bean is using the WebLogic Server 6.0 CMP engine, and that the CMP deployment descriptor is located in META-INF/weblogic-cmp-rdbms.xml. This is required for WebLogic Server to support plug-in CMP engines from other vendors. The examples in this book assume the WebLogic Server CMP engine.

<?xml version="1.0"?>

<!DOCTYPE weblogic-ejb-jar PUBLIC
"-//BEA Systems, Inc.//DTD WebLogic 6.0.0 EJB//EN"
 "http://www.bea.com/servers/wls600/dtd/weblogic-ejb-jar.dtd" >

<weblogic-ejb-jar>
  <weblogic-enterprise-bean>
    <ejb-name>StudentCMPEJB</ejb-name>

    <entity-descriptor>
      <persistence>
        <persistence-type>
          <type-identifier>WebLogic_CMP_RDBMS</type-identifier>
          <type-version>6.0</type-version>
          <type-storage>
            META-INF/weblogic-cmp-rdbms.xml
          </type-storage>
      </persistence-type>
      <persistence-use>
        <type-identifier>WebLogic_CMP_RDBMS</type-identifier>
        <type-version>6.0</type-version>
      </persistence-use>
      </persistence>
    </entity-descriptor>

    <jndi-name>StudentCMPEJB</jndi-name>
  </weblogic-enterprise-bean>

</weblogic-ejb-jar>

weblogic-cmp-rdbms.xml Descriptor

The third required deployment descriptor is the CMP deployment descriptor, weblogic-cmp-rdbms-jar.xml. The weblogic-cmp-rdbms-jar.xml includes the database information necessary to map the abstract persistence schema to the physical schema in the database. Each entity bean maps to a database table, and each container-managed field maps to a database column.

<?xml version="1.0"?>

<!DOCTYPE weblogic-rdbms-jar PUBLIC
 '-//BEA Systems, Inc.//DTD WebLogic 6.0.0 EJB RDBMS Persistence/
/EN'
 'http://www.bea.com/servers/wls600/dtd/weblogic-rdbms20-persis-
tence-600.dtd'>


<weblogic-rdbms-jar>
  <weblogic-rdbms-bean>

    <ejb-name>StudentCMPEJB</ejb-name>
    <data-source-name>DBPool</data-source-name>
    <table-name>studentcmptable</table-name>

    <field-map>
      <cmp-field>ssn</cmp-field>
      <dbms-column>ssn</dbms-column>
    </field-map>
    <field-map>
      <cmp-field>name</cmp-field>
      <dbms-column>name</dbms-column>
    </field-map>
    <field-map>
      <cmp-field>grade</cmp-field>
      <dbms-column>grade</dbms-column>
    </field-map>

  </weblogic-rdbms-bean>

</weblogic-rdbms-jar>

Building and Running the Example

This example is located in the examples/ch9/cmp directory on the accompanying CD-ROM. The example includes a build.cmd script to build and compile the EJB and its client. The tables.ddl file includes the necessary schema for the database. These tables should be created before deploying the EJBs. The deploy.cmd script copies the ejb-jar into the server's applications directory for it to be deployed. The runClient.cmd script can be used to run the EJB client.