Getting Started with Enterprise JavaBeans™


J2EE/EJB Overview

Tutorial Home Section Home Previous Next



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 = 
            narrow( oRef, MyEJBRemoteHome.class );

     The 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" );

Figure OV-1: The javax.ejb.EJBHome and javax.ejb.EJBLocalHome interfaces
The javax.ejb.EJBHome interface The javax.ejb.EJBLocalHome interface

     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 create() method.

     The create() and 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 INSERT and 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, 

     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 methodName() and 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).

Tutorial Home Section Home Previous Next