Sun Microsystems Inc.

Figure 19 Client view of entity beans deployed in a container

container

8.3 Entity bean’s home interface

The container provides the implementation of the home interface for each entity bean deployed in the container. The container makes the home interface of every entity bean deployed in the container accessible to the clients through JNDI API. An object that implements an entity bean’s home interface is called an EJBHome object.

Sun Microsystem Inc

The entity bean’s home interface allows a client to do the following:

•Create new entity objects within the home.

•Find existing entity objects within the home.

•Remove an entity object from the home.

•Get the javax.ejb.EJBMetaData interface for the entity bean. The javax.ejb.EJBMetaData interface is intended to allow application assembly tools to discover the meta-data information about the entity bean. The meta-data information allows loose client/server binding and scripting.

•Obtain a handle for the home interface. The home handle can be serialized and written to stable storage; later, possibly in a different JVM, the handle can be deserialized from stable storage and used to obtain a reference to the home interface.

An entity bean’s home interface must extend the javax.ejb.EJBHome interface and follow the standard rules for Java programming language remote interfaces.

8.3.1 create methods

An entity bean’s home interface can define zero or more create(...) methods, one for each way to create an entity object. The arguments of the create methods are typically used to initialize the state of the created entity object.

The return type of a create method is the entity bean’s remote interface.

The throws clause of every create method includes the java.rmi.RemoteException and the javax.ejb.CreateException. It may include additional application-level exceptions.

The following home interface illustrates two possible create methods:

public interface AccountHome extends javax.ejb.EJBHome { public Account create(String firstName, String lastName,

double initialBalance)

throws RemoteException, CreateException; public Account create(String accountNumber,

double initialBalance)

throws RemoteException, CreateException, LowInitialBalanceException;

...

}

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

AccountHome accountHome = ...;

Account account = accountHome.create(“John”, “Smith”, 500.00);

Sun Microsystems Inc.

8.3.2 finder methods

An entity bean’s home interface defines one or more finder methods[5], one for each way to find an entity object or collection of entity objects within the home. The name of each finder method starts with the prefix “ find ”, such as findLargeAccounts(...). The arguments of a finder method are used by the entity bean implementation to locate the requested entity objects. The return type of a finder method must be the entity bean’s remote interface, or a type representing a collection of objects that implement the entity bean’s remote interface (see Subsection 9.1.8).

The throws clause of every finder method includes the java.rmi.RemoteException and the javax.ejb.FinderException.

The home interface of every entity bean includes the findByPrimaryKey(primaryKey) method that allows a client to locate an entity object using a primary key. The name of the method is always findByPrimaryKey; it has a single argument that is the same type as the entity bean’s primary key type, and its return type is the entity bean’s remote interface. The implementation of the findByPrimaryKey(primaryKey) method must ensure that the entity object exists.

The following example shows the findByPrimaryKey method:

public interface AccountHome extends javax.ejb.EJBHome {

...

public Account findByPrimaryKey(String AccountNumber) throws RemoteException, FinderException;

}

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

AccountHome = ...;

Account account = accountHome.findByPrimaryKey(“100-3450-3333”);

8.3.3 remove methods

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;

}

After an entity object has been removed, subsequent attempts to access the entity object by a client result in the java.rmi.NoSuchObjectException.

[5] The findByPrimaryKey(primaryKey) method is mandatory for all Entity Beans.