Implementing an EJB 2.1 CMP Entity Bean

Table 13-1 summarizes the important parts of an EJB 2.1 CMP entity bean and the following procedure describes how to implement these parts. For a typical implementation, see "Using Java". For more information, see "What is an EJB 2.1 CMP Entity Bean?".

Table 13-1 Parts of an EJB 2.1 CMP Entity Bean

Part	Description
Home Interface (remote or local)	Extends `javax.ejb.EJBHome` for the remote home interface, `javax.ejb.EJBLocalHome` for the local home interface, and requires a single `create()` factory method, with no arguments, and a single `remove()` method.
Component Interface (remote or local)	Extends `javax.ejb.EJBObject` for the remote interface and `javax.ejb.EJBLocalObject` for the local interface. It defines the business logic methods, which are implemented in the bean implementation.
Bean implementation	Implements `EntityBean`. This class must be declared as public, contain a public, empty, default constructor, no `finalize`() method, and implements the methods defined in the component interface. Must contain one or more `ejbCreate` methods to match the `create` methods in the home interface. Contains empty implementations for the container service methods, such as `ejbRemove`, and so on.

Create the home interfaces for the bean (see "Implementing the EJB 2.1 Home Interfaces").

The remote home interface defines the create and finder methods that a client can invoke remotely to instantiate your bean. The local home interface defines the create and finder methods that a collocated bean can invoke locally to instantiate your bean.

For more information about finders, see "Understanding Finder Methods"
1. To create the remote home interface, extend javax.ejb.EJBHome (see "Implementing the Remote Home Interface").
2. To create the local home interface, extend javax.ejb.EJBLocalHome (see "Implementing the Local Home Interface").
Create the component interfaces for the bean (see "Implementing the EJB 2.1 Component Interfaces").

The remote component interface declares the business methods that a client can invoke remotely. The local interface declares the business methods that a collocated bean can invoke locally.
1. To create the remote component interface, extend javax.ejb.EJBObject (see "Implementing the Remote Component Interface").
2. To create the local component interface, extend javax.ejb.EJBLocalObject (see "Implementing the Local Component Interface").
Define the primary key for the bean (see "Configuring an EJB 2.1 CMP Entity Bean Primary Key").

The primary key identifies each entity bean instance and is a serializable class. You can use a simple data type class, such as java.lang.String, or define a complex class, such as one with two or more objects as components of the primary key.
Implement the CMP entity bean:
1. Implement the abstract get and set methods that correspond to the get and set method(s) declared in the home interfaces.
  
  For a CMP entity bean, the get and set methods are public abstract because the container is responsible for their implementation.
2. Implement the business methods that you declared in the home and component interfaces (if any). The signature for each of these methods must match the signature in the remote or local interface, except that the bean does not throw the RemoteException. Since both the local and the remote interfaces use the bean implementation, the bean implementation cannot throw the RemoteException.
  
  For an entity bean, these methods are often delegated to a session bean (see "What is a Session Bean?").
3. Implement any methods that are private to the bean or package used for facilitating the business logic. This includes private methods that your public methods use for completing the tasks requested of them.
4. Implement the ejbCreate methods that correspond to the create method(s) declared in the home interfaces. The container invokes the appropriate ejbCreate method when the client invokes the corresponding create method.
  
  The return type of all ebjCreate methods is the type of the bean's primary key.
  
  For a CMP entity bean, provide create methods that allow the client to pass in values that the container will persist to your database.
5. Provide an empty implementation for each of the javax.ejb.EntityBean interface container callback methods
6. Implement a setEntityContext method (that takes an instance of EntityContext) and unsetEntityContext method (see "Implementing the setEntityContext and unsetEntityContext Methods" ).
7. Optionally, define zero or more public, abstract select methods (see "Understanding Select Methods") for use within the business methods of your entity bean.
Create the appropriate database schema (tables and columns) for the entity bean.

For a CMP entity bean, you can specify how persistence attributes should be stored in the database or you can configure the container to manage table creation for you.

For more information, see:
- "Configuring Automatic Database Table Creation"
You can configure the container to create the required tables for CMP beans.
Configure your ejb-jar.xml file to match your bean implementation and to reference a data source defined in your data-sources.xml file (see "Using Deployment XML").
Complete the configuration of your entity bean (see "Using EJB 2.1 CMP Entity Bean API").

Using Java

Example 13-1 shows a typical implementation of an EJB 2.1 CMP entity bean. Example 13-2 shows the corresponding remote home interface and Example 13-3 shows the corresponding remote component interface.

Example 13-1 EJB 2.1 CMP Entity Bean Implementation

package cmpapp;

import javax.ejb.*;
import java.rmi.*;

public abstract class EmployeeBean implements EntityBean
{

    private EntityContext ctx;

    // cmp fields accessors
    public abstract Integer getEmpNo();
    public abstract void setEmpNo(Integer empNo);
 
    public abstract String getEmpName();
    public abstract void setEmpName(String empName);
 
    public abstract Float getSalary();
    public abstract void setSalary(Float salary);
 
    public void EmployeeBean()
    {
        // Empty constructor, don't initialize here but in the create().
        // passivate() may destroy these attributes in the case of pooling
    }

    public EmployeePK ejbCreate(Integer empNo, String empName, Float salary)
        throws CreateException
    {
        setEmpNo(empNo);
        setEmpName(empName);
        setSalary(salary);
        return new EmployeePK(empNo);
    }
 
    public void ejbPostCreate(Integer empNo, String empName, Float salary)
        throws CreateException
    {
        // when just after bean created
    }
 
    public void ejbStore()
    {
        // when bean persisted
    }
 
    public void ejbLoad()
    {
        // when bean loaded
    }
 
    public void ejbRemove()
    {
        // when bean removed
    }
 
    public void ejbActivate()
    {
        // when bean activated
    }
 
    public void ejbPassivate()
    {
        // when bean deactivated
    }
 
    public void setEntityContext(EntityContext ctx)
    {
        this.ctx = ctx;
    }
 
    public void unsetEntityContext()
    {
        this.ctx = null;
    }

}

Example 13-2 EJB 2.1 CMP Remote Home Interface

package cmpapp;

import java.rmi.*;
import java.util.*;
import javax.ejb.*;

public interface EmployeeHome extends EJBHome
{
     public Employee create(Integer empNo, String empName, Float salary)
         throws CreateException, RemoteException;

     public Employee findByPrimaryKey(EmployeePK pk)
         throws FinderException, RemoteException;

     public Collection findByName(String empName)
         throws FinderException, RemoteException;

     public Collection findAll()
         throws FinderException, RemoteException;
}

Example 13-3 EJB 2.1 CMP Remote Component Interface

package cmpapp;

import javax.ejb.*;
import java.rmi.*;

public interface Employee extends EJBObject
{
    // cmp fields accessors
    public Integer getEmpNo() throws RemoteException;
    public void setEmpNo(Integer empNo) throws RemoteException;

    public String getEmpName() throws RemoteException;
    public void setEmpName(String empName) throws RemoteException;

    public Float getSalary() throws RemoteException;
    public void setSalary(Float salary) throws RemoteException;
}

Using Deployment XML

Example 13-4 shows the ejb-jar.xml file entity element corresponding to the CMP entity bean shown in Example 13-1.

Example 13-4 ejb-jar.xml For an EJB 2.1 CMP Entity Bean

...
    <enterprise-beans>
        <entity>
            <description>no description</description>
            <display-name>EmployeeBean</display-name>
            <ejb-name>EmployeeBean</ejb-name>
            <home>cmpapp.EmployeeHome</home>
            <remote>cmpapp.Employee</remote>
            <ejb-class>cmpapp.EmployeeBean</ejb-class>
            <persistence-type>Container</persistence-type>
            <cmp-version>2.x</cmp-version>
            <abstract-schema-name>EmployeeBean</abstract-schema-name>
            <prim-key-class>cmpapp.EmployeePK</prim-key-class>
            <reentrant>False</reentrant>
            <cmp-field><field-name>empNo</field-name></cmp-field>
            <cmp-field><field-name>empName</field-name></cmp-field>
            <cmp-field><field-name>salary</field-name></cmp-field>
            <query>
                <description></description>
                <query-method>
                <method-name>findAll</method-name>
                <method-params/>
                </query-method>
                <ejb-ql>Select OBJECT(e) From EmployeeBean e</ejb-ql>
            </query>
            <query>
                <description></description>
                <query-method>
                <method-name>findByName</method-name>
                <method-params>
                <method-param>java.lang.String</method-param>
                </method-params>
                </query-method>
                <ejb-ql>Select OBJECT(e) From EmployeeBean e where e.empName = ?1</ejb-ql>
            </query>
        </entity>
    </enterprise-beans>
...