Entity Bean Methods

The entity bean class implements the javax.ejb.EntityBean interface. Therefore, you need to implement the setEntityContext, unsetEntityContext, ejbActivate, ejbPassivate, ejbLoad, ejbStore, and ejbRemove methods defined in the javax.ejb.EntityBean interface. The bean may implement ejbCreate<method>(...) methods (and corresponding ejbPostCreate<method>(...) methods) used to initialize the bean instance. In addition, the bean class can implement business methods, home methods and remove methods. We'll discuss each of them in detail in the following sections.

setEntityContext and unsetEntityContext Methods

The EJB container calls the setEntityContext method to set the associated entity context. The entity context provides access to the runtime entity context, such as identifying the caller, accessing or changing the current transaction state, or obtaining the primary key associated with the instance. You can store the reference to the entity context object in an instance variable, if you need it later. Also, it is here that you allocate any resources to be held by the instance for its lifetime.

The EJB container calls the unsetEntityContext method before removing the instance. This is the last method that the container invokes on the instance. The Java garbage collector will eventually invoke the finalize() method on the instance. Here you free any resources that are held by the instance.

create Methods

The container calls this method so that you can initialize your entity bean instance. When a client invokes a create<method> method on the home interface, the EJB container invokes the corresponding ejbCreate<method> method.

The following local home interface illustrates the create method:

public interface StudentLocalHome extends EJBLocalHome {
 StudentLocal create(String studentId, String name, String password,
   String address) throws CreateException;
 ...
}

Typically, the ejbCreate<method> of a BMP validates the client-supplied parameters, inserts the entity state into the database, initializes the instance variables, and returns the primary key. In contrast, the ejbCreate<method> of CMP typically initializes the entity bean instance by assigning the input arguments to the persistent fields. After the ejbCreate<method> completes, the container inserts the row into the database.

The following example illustrates how a client creates a new entity object:

StudentLocalHome home =
Student student =
   home.create("1,", "Sam", "password", "123 Hollis Ave, Campbell, CA-95008");

ejbPostCreate<method> Methods

This method enables you to complete any remaining initialization of entity bean instances. For example, you may obtain the component interface of the associated entity object and pass it to another enterprise bean as a method argument.

The container invokes the matching ejbPostCreate<method>(...) method on an entity instance after it invokes the ejbCreate<method>(...) method with the same arguments.

ejbActivate and ejbPassivate Methods

The ejbActivate method enables you to acquire any resources (such as opening socket connections and so on) needed to service a particular client. The EJB container calls this method when it picks the entity instance from the instance pool and associates it to a specific entity object identity.

The ejbPassivate method enables you to release any resources you acquired in the ejbActivate method, such as closing socket connections. The EJB container calls this method when the container decides to disassociate the instance from an entity object identity and to put it back into the instance pool.

Business Methods

The business methods contain business logic that you want to encapsulate within your entity bean. Typically, the business methods don't access the database, which enables you to separate the business logic from the database access code. You define the business methods in the component interface and implement them in the entity bean class.

For example, the Account bean's component interface defines the business methods deposit() and withdraw() as follows:

public interface Account extends EJBObject {
  public void deposit(double amount)
    throws RemoteException;
  public double withdraw(double amount)
    throws AccountException, RemoteException;
  ...
}

The AccountEJB bean implements the business methods as follows:

abstract public class AccountEJB implements EntityBean {
   /* container managed fields */
   abstract public double getBalance();
   abstract public void setBalance(double val);
   ...
   public double deposit(double amount) {
    setBalance(getBalance() + amount);
    return getBalance();
   }

   public double withdraw(double amount)
     throws ProcessingErrorException {
    if (amount > getBalance()) {
      throw new ProcessingErrorException(
        "Request to withdraw " + amount +
        "; is more than balance " + getBalance());
    }
    setBalance(getBalance() - amount);
    return getBalance();
   }
   ...
}
						

ejbLoad() and ejbStore() Methods

The EJB container calls the ejbLoad() and ejbStore() methods when it needs to synchronize the state of the entity bean instance with the corresponding values in the database.

• ejbLoad()— The EJB container invokes this method to instruct the instance to synchronize its state by loading it from the underlying database.

  With BMP, the instance variables are refreshed by reading from the database. Also, you recalculate the values of any instance variables that depend on refreshed variables; for instance, calculate transient fields, decrypt a text field, or decompress a text field.

  With CMP, the container loads the bean's state from the database. You must recalculate the values of any instance variables that depend on persistent fields; for instance, calculate transient fields, decrypt a text field, or decompress a text field.

• ejbStore()— The EJB container invokes this method to instruct the instance to synchronize its state by storing it to the underlying database.

  With BMP, any updates cached in the instance variables are written to the database.

  With CMP, prepare the container-managed fields to be written to the database; for example, encrypt a text field, decompress a text field, and so on.

finder Methods

Finder methods allow clients to locate entity beans. The arguments of a finder method are used by the entity bean implementation to locate the requested entity objects. The name of each finder method in the home interface starts with the prefix find.

In the following snippet, the client locates the student entity beans by using the finder methods findByPrimaryKey and findByLastName:

public interface StudentLocalHome extends EJBLocalHome {

     public StudentLocal findByPrimaryKey(String key) throws FinderException;
     public Collection findByLastName(String lastName) throws FinderException;
     ...
}

In BMP, for every finder method defined in the home interface, you must implement a corresponding method that begins with the prefix ejbFind. For example, StudentEJB implements the method ejbFindByLastName, which corresponds to the findByLastName method defined in the home interface.

In CMP, you do not write the ejbFind methods in your entity bean class. The finder methods are generated by the container provider tools.

The following example illustrates how a client uses the findByPrimaryKey method:

StudentLocalHome home= ...;
StudentLocal student = home.findByPrimaryKey("1");

Home Methods

Home methods contain business logic that that is not specific to an entity bean instance. These methods are analogous to static methods. Just as static methods can't access instance variables, home methods can't access the bean's state.

The following example shows the home method getStudentCount, which returns the total number of students in a table:

public interface StudentLocalHome extends EJBLocalHome {
   public int getStudentCount();
   ...
}

You write an ejbHome<method> method, in the entity bean class, for every home method defined in the home interface. For example, you would implement ejbHomeGetStudentCount() in the StudentEJB entity bean class.

remove Method

The javax.ejb.EJBHome interface defines several methods that allow the client to remove an entity object:

public interface EJBHome extends Remote {
   void remove(Handle handle) throws RemoteException,
    RemoveException;
   void remove(Object primaryKey) throws RemoteException,
    RemoveException;
}

In BMP, the ejbRemove() method removes the entity state from the database and releases any resources that you acquired to service a particular client. In CMP, the ejbRemove() method releases any resources that you acquired to service a particular client. Table 8.2 summarizes the entity bean methods.