The Home Interface
Note: The following discussion of bean interfaces applies only to session and entity beans. Message-driven beans effectively run within a batch environment on the server and are represented only by the bean class — no interfaces are used.
A bean's home interface specifies methods that allow the client to create, remove, and find objects of the same type. The home interface may also provide definitions for home business methods for entity beans. Home business methods are methods that are not specific to a particular bean instance. While the developer writes the home interface, the container creates the implementation for client interaction. In essence, the home interface provides bean management and life cycle methods.
The client uses a JNDI lookup to locate a bean's home interface. The EJB 1.1 specification introduced the environment naming context (ENC) as a means of enhancing portability and avoiding name clashes in the JNDI namespace. In practice, this means that you should preface the lookup string with
java:comp/env/. The container is required to recognize a lookup coded in this manner as an alias or nickname rather than the direct JNDI name. A deployment descriptor entry links the alias to the actual JNDI entry. Use of the ENC also means that the developer doesn't have to worry about hardcoded JNDI names; the ENC effectively makes them softcoded. For more information about ENC, see Resources). The sample code below locates the remote home interface for a bean with a JNDI name of
ejb/MyEJB (this could be a completely different external name, depending on the
ejb-ref entry in the deployment descriptor). This code, and the following code for local home lookup, is virtually identical in every client's bean access routine:
InitialContext ic = new InitialContext(); Object oRef = ic.lookup( "java:comp/env/ejb/MyEJBBean" ); MyEJBRemoteHome MyEJBHome = (MyEJBRemoteHome)PortableRemoteObject. narrow( oRef, MyEJBRemoteHome.class );
PortableRemoteObject.narrow() method is required to ensure conversion to the proper remote interface type.
For a bean that provides a local home interface instead of, or in addition to, a remote home interface, the following code is typical:
InitialContext ic = new InitialContext(); MyEJBLocalHome MyEJBHome = (MyEJBLocalHome)ic.lookup( "java:comp/env/ejb/MyEJBBean" );
The remote home interfaces that you write extend the
javax.ejb.EJBHome interface; your local home interfaces extend the
javax.ejb.EJBLocalHome interface. Within the home interface, the specification normally requires that you implement at least one
remove() methods have very different effects for entity beans than for other bean types. As will be seen in the appropriate sections, for entity beans the methods create and delete persistent data (think SQL
DELETE statements for RDBMS datastores). For session beans, these methods create (or draw from a pool) and disassociate bean instances. The
create() methods also ask the container to return the component interface for the requested Enterprise JavaBean instance.
The prototype for a remote home interface
create() method looks like this:
MyEJBRemote create() throws RemoteException, CreateException;
For a local home interface
create() method, the code looks like this:
MyEJBLocal create() throws CreateException;
You may notice later that there is no direct corresponding
create() method in your bean. Instead, your bean defines, per the specification, an
ejbCreate() method to match each interface
create() method, which the container calls before persisting new data for entity beans and after bean instantiation for the other EJB types. The
ejbCreate() method for session and message-driven beans may be viewed as similar in purpose to the
init() method in applets and servlets.
The pattern of pairs of
ejbMethodName() is repeated often for bean contract methods, with
methodName() used for the client interface and
ejbMethodName() used in the bean's implementation. Remember that it is the container that actually calls the bean's methods, and it knows to preface the method name with "
ejb". See the relevant bean contract sections in the EJB 2.0 specification for complete information (available from Resources).