In addition to "home business methods," the Home interface is used by any client application to create, remove, and retrieve instances of the Entity Bean. The bean provider needs to provide only the desired interface; the container will automatically provide the implementation. If it is remote, the interface must extend the javax.ejb.EJBHome interface; if it is local, the interface must extend the javax.ejb.EJBLocalHome interface. The methods of a remote home interface must follow the rules for Java RMI. The signatures of the create and find... methods should match the signatures of the ejbCreate and ejbFind... methods that will be provided later in the Enterprise Bean implementation class (the same number and types of arguments, but different return types).
The return type is the Enterprise Bean's component interface.
The exceptions defined in the throws clause must include the exceptions defined for the ejbCreate and ejbPostCreate methods, and must include javax.ejb.CreateException and java.rmi.RemoteException (the latter is only for a remote interface).
The interfaces for these methods must not be defined—they are inherited from EJBHome or EJBLocalHome.
The method is void remove, taking as an argument the primary key object or the handle (for a remote interface).
The exceptions defined in the throws clause should be javax.ejb.RemoveException and java.rmi.RemoteException for a remote interface.
The exceptions defined in the throws clause should be javax.ejb.RemoveException and java.ejb.EJBException for a local interface.
Finder methods are used to search for an EJB object or a collection of EJB objects. The arguments of the method are used by the Entity Bean implementation to locate the requested entity objects. For bean-managed persistence, the bean provider is responsible for developing the corresponding ejbFinder methods in the bean implementation. For container-managed persistence, the bean provider does not write these methods; they are generated at deployment time by the platform tools; the description of the method is provided in the deployment descriptor, as defined in Section 8.7 Configuring Database Access for Container-Managed Persistence. In the Home interface, the finder methods must adhere to the following rules:
They must be named find<method> (for example, findLargeAccounts).
The return type must be the Enterprise Bean's component interface, or a collection thereof.
The exceptions defined in the throws clause must include the exceptions defined for the matching ejbFind method, and must include javax.ejb.FinderException and java.rmi.RemoteException (the latter, only for a remote interface).
At least one of these methods is mandatory: findByPrimaryKey, which takes as argument a primary key value and returns the corresponding EJB object.
Home methods are methods that the bean provider supplies for business logic that is not specific to an Entity Bean instance.
The throws clause of every home method on the remote home interface includes the java.rmi.RemoteException.
Home methods implementation is provided by the bean developer in the bean implementation class as public static methods named ejbHome<METHOD_NAME>(...), where <METHOD_NAME> is the name of the method in the home interface.
The Account Bean example, provided with the platform examples, is used to illustrate these concepts. The state of an Entity Bean instance is stored in a relational database, where the following table should exist, if CMP 1.1 is used:
create table ACCOUNT (ACCNO integer primary key,
CUSTOMER varchar(30),
BALANCE number(15,4));
public interface AccountHome extends EJBHome {
public Account create(int accno, String customer, double balance)
throws RemoteException, CreateException;
public Account findByPrimaryKey(Integer pk)
throws RemoteException, FinderException;
public Account findByNumber(int accno)
throws RemoteException, FinderException;
public Enumeration findLargeAccounts(double val)
throws RemoteException, FinderException;
} |