Implementing the EJB 2.1 Home Interfaces

The home interfaces are used to specify what methods a client uses to create or retrieve an entity bean instance.

The home interface must contain a create method, which the client invokes to create the bean instance. The entity bean can have zero or more create methods, each with its own defined parameters. For each create method, you define a corresponding ejbCreate method in the bean implementation.

All entity beans must define one or more finder methods in the home interface, where at least one is a findByPrimaryKey method. Optionally, you can define other finder methods, which are named find<name>, including predefined and default finders. For more information, see "Understanding Finder Methods".

In addition to creation and retrieval methods, you can provide home interface business methods within the home interface. The functionality within these methods cannot access data of a particular entity object. Instead, the purpose of these methods is to provide a way to retrieve information that is not related to a single entity bean instance. When the client invokes any home interface business method, an entity bean is removed from the pool to service the request. Thus, this method can be used to perform operations on general information related to the bean.

For example, in an employee application, you might provide the local home interface with a create, findByPrimaryKey, findAll, and calcSalary methods. The calcSalary method is a home interface business method that calculates the sum of all employee salaries. It does not access the information of a particular employee, but performs a SQL query against the database for all employees.

There are the following two types of home interface:

• The remote home interface extends javax.ejb.EJBHome (see "Implementing the Remote Home Interface")

• The local home interface extends javax.ejb.EJBLocalHome (see "Implementing the Local Home Interface")

Implementing the Remote Home Interface

A remote client invokes the EJB through its remote interface. The client invokes the create method that is declared within the remote home interface. The container passes the client call to the ejbCreate method–with the appropriate parameter signature–within the bean implementation. The requirements for developing the remote home interface include the following:

• The remote home interface must extend the javax.ejb.EJBHome interface.

• All create methods may throw the following exceptions:

  • javax.ejb.CreateException

  • javax.ejb.EJBException or another RuntimeException

Example 13-2 shows the remote home interface corresponding to the EJB 2.1 entity bean with container-managed persistence in Example 13-1 and Example 13-6 shows the remote home interface corresponding to the EJB 2.1 entity bean with bean-managed persistence in Example 13-5.

Implementing the Local Home Interface

An EJB can be called locally from a client that exists in the same container. Thus, a collocated bean, JSP, or servlet invokes the create method that is declared within the local home interface. The container passes the client call to the ejbCreate method–with the appropriate parameter signature–within the bean implementation. The requirements for developing the local home interface include the following:

• The local home interface must extend the javax.ejb.EJBLocalHome interface.

• All create methods may throw the following exceptions:

  • javax.ejb.CreateException

  • javax.ejb.EJBException or another RuntimeException