February 27, 2021
Hot Topics:

Developing a CMP Bean

  • By Saleem Siddiqui, Michael Landy, & Jeff Swisher
  • Send Email »
  • More Articles »

This material is from the book JBuilder Developer's Guide.

© Copyright Sams Publishing. All rights reserved.

It is now time to look at the process of building an entity bean. We will develop a simple CMP bean, but spend most of our time investigating and perfecting the process.

The process has some similarities to creating session beans. The following is the process we are going to use to investigate and build an entity bean:

  • Implement the home interface.

  • Define the appropriate finder methods.

  • Implement the component interface.

  • Define the bean implementation class.

  • Build the deployment descriptor.

  • Deploy the bean.

  • Test the bean.

Defining the Home Interface

The home interface for an entity bean is similar to the home interface of a session bean. To review, its purpose is to create an instance, find existing instances, or remove an instance; the same rules apply to an entity bean (see Listing 1).

Listing 1 Home Interface for Our Employee Entity Bean

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

public interface EmployeeHome extends javax.ejb.EJBLocalHome {
 public Employee create(Short empNo) throws CreateException;
 public Employee findByPrimaryKey(Short empNo) throws FinderException;

The create() method is used to create an instance of a class based on this primary key. For our employee table, the empNo is the primary key, thus we will also use empNo as the primary key of our entity bean. The second method type is called a finder method. With entity beans, to create an instance we use the create() method, but finding an existing instance is just as important if not more important. With that requirement, we need finder methods to provide the capability to locate a specific instance or collection of instances of data.

The findByPrimaryKey() is a method that has an argument representing the primary key; in our case, it is empNo. This searches for an employee with the given primary key either returning a remote interface to the instance or through an exception.


The findByPrimaryKey() method is required by all entity beans; any other finders are optional.

Finder methods do not just return a single instance, but they can also return a collection of instances. These types of finder methods are typically used when the primary key or an alternative unique key is not used. For example, we might want to be able to find employees who have a certain salary range, as shown in Listing 2. This finder method should return a collection of employees rather than a single instance.

Listing 2 Home Interface for Our Employee Entity Bean with the Addition of New Finder Methods

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

public interface EmployeeHome extends javax.ejb.EJBLocalHome {
 public Employee create(Short empNo) throws CreateException;
 public Collection findSalaryRange(BigDecimal low, BigDecimal high) throws FinderException;
 public Employee findByPrimaryKey(Short empNo) throws FinderException;

Notice that the findSalaryRange() does not return a single instance like the findByPrimaryKey() but a java.lang.Collection. This collection contains instances of the primary key, not the entire instance; the container then translates for you this instance into the remote interface. This method might return a huge collection of records, so it is important to make sure that you design the beans appropriately.

Defining the Component Interface

Our Employee interface defines all the methods required for us to access and mutate the data within the bean. For example, setFirstName() and getFirstName() methods are required to get access to the instance variables (see Listing 3).

Listing 3 Component Interface for the Employee Bean

import javax.ejb.*;
import java.util.*;
import java.sql.*;
import java.math.*;

public interface Employee extends javax.ejb.EJBLocalObject {
 public Short getEmpNo();
 public void setFirstName(String firstName);
 public String getFirstName();
 public void setLastName(String lastName);
 public String getLastName();
 public void setPhoneExt(String phoneExt);
 public String getPhoneExt();
 public void setHireDate(Timestamp hireDate);
 public Timestamp getHireDate();
 public void setDeptNo(String deptNo);
 public String getDeptNo();
 public void setJobCode(String jobCode);
 public String getJobCode();
 public void setJobGrade(Short jobGrade);
 public Short getJobGrade();
 public void setJobCountry(String jobCountry);
 public String getJobCountry();
 public void setSalary(BigDecimal salary);
 public BigDecimal getSalary();
 public void setFullName(String fullName);
 public String getFullName();

Implementing the Bean

One misconception about CMP beans is that you do not have to have a bean implementation class. This class supplies the necessary implementations required for the container to manage the persistence, as shown in Listing 4.

Listing 4 EmployeeBean Implementation Class

import javax.ejb.*;

abstract public class EmployeeBean implements EntityBean {
 EntityContext entityContext;
 public java.lang.Short ejbCreate(java.lang.Short empNo) throws CreateException {
  return null;
 public void ejbPostCreate(java.lang.Short empNo) throws CreateException {
  /**@todo Complete this method*/
 public void ejbRemove() throws RemoveException {
  /**@todo Complete this method*/
 public abstract void setEmpNo(java.lang.Short empNo);
 public abstract void setFirstName(java.lang.String firstName);
 public abstract void setLastName(java.lang.String lastName);
 public abstract void setPhoneExt(java.lang.String phoneExt);
 public abstract void setHireDate(java.sql.Timestamp hireDate);
 public abstract void setDeptNo(java.lang.String deptNo);
 public abstract void setJobCode(java.lang.String jobCode);
 public abstract void setJobGrade(java.lang.Short jobGrade);
 public abstract void setJobCountry(java.lang.String jobCountry);
 public abstract void setSalary(java.math.BigDecimal salary);
 public abstract void setFullName(java.lang.String fullName);
 public abstract java.lang.Short getEmpNo();
 public abstract java.lang.String getFirstName();
 public abstract java.lang.String getLastName();
 public abstract java.lang.String getPhoneExt();
 public abstract java.sql.Timestamp getHireDate();
 public abstract java.lang.String getDeptNo();
 public abstract java.lang.String getJobCode();
 public abstract java.lang.Short getJobGrade();
 public abstract java.lang.String getJobCountry();
 public abstract java.math.BigDecimal getSalary();
 public abstract java.lang.String getFullName();
 public void ejbLoad() {
  /**@todo Complete this method*/
 public void ejbStore() {
  /**@todo Complete this method*/
 public void ejbActivate() {
  /**@todo Complete this method*/
 public void ejbPassivate() {
  /**@todo Complete this method*/
 public void unsetEntityContext() {
  this.entityContext = null;
 public void setEntityContext(EntityContext entityContext) {
  this.entityContext = entityContext;

The client first calls the create() method of the entity bean's home interface. Remember that this is the client of the bean, not necessarily an end-user client. This then translates through the container to the implementation bean. These methods are called by the container for the persistence to take place properly. Let's take a look in detail at how the bean actually works. The best method to view the operation is to use a sequence diagram.

First, let's look at the creation of a new instance of an entity bean, as shown in Figure 1. The create() method tags arguments, which is typically a signature containing the primary key of an instance. After that, the container takes complete control going forward.

Figure 1
Sequence diagram for a client creating an entity bean.

Second, we might need to remove a bean. The remove() method is called by the client, allowing for the instance to be removed from the data source (see Figure 2). Again, the only call the client needs to make is remove(); the container then manages the rest of the interaction to remove the instance.

Figure 2
Sequence diagram for a client removing an entity bean.

Finally, let's look at a finder method, shown in Figure 3. When the client makes a call to one of the finder methods on the home interface, the home interface uses the data source to return the matching elements either singularly using the remote interface or by a list using a java.lang.Collection.

Figure 3
Sequence diagram for a client using one of the finder methods.

Page 1 of 4

This article was originally published on July 24, 2003

Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Thanks for your registration, follow us on our social networks to keep up-to-date