Skip Headers

Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g Release 3 (10.1.3) B14428-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 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 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 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 CMP entity bean in Example 13-1 and Example 13-6 shows the remote home interface corresponding to the EJB 2.1 BMP entity bean 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 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`