Locating Enterprise Beans Using the Home Interface

   

Before a client can invoke a method on the enterprise bean's component interface, it must first obtain a reference to the object that implements this interface. The component that is responsible for creating instances of the component interface for an enterprise bean is the bean's home interface. This is the other Java interface that must be created for every enterprise bean you deploy.

Every enterprise bean that is exposed to a client has a home interface. As you'll see in Chapter 11, the message-driven bean is not exposed to a client directly and has no component interface. It therefore does not need a home interface. An enterprise bean's home interface defines the methods that allow clients to create, find, and remove EJB objects. Depending on whether the client will be a local client or a remote client, the home interface must extend one of two interfaces.

If you are building a home interface for local clients, you must create an interface that extends the javax.ejb.EJBLocalHome interface. There is only one method defined by the EJBLocalHome interface, which is the remove method . The remove method for the EJBLocalHome interface is used only for entity beans however, because this version takes a primary key. Calling this method on a home interface for a session bean will result in a javax.ejb.RemoveException being thrown. The remove method on the EJBLocalHome interface is a convenience method so that a client can remove an entity bean without acquiring a reference to its component interface.

Tip

As shown in Tables 3.1 and 3.2, the EJBLocalObject and EJBObject interfaces also contain a remove method that can be called, regardless of the type of EJB.


If the enterprise bean is intended for a remote client, the home interface should extend the javax.ejb.EJBHome interface. Table 3.3 describes the method signatures in the EJBHome interface.

Table 3.3. The Methods Defined in the javax.ejb.EJBHome Interface

Return

Method

Description

EJBMetaData

getEJBMetaData

Obtain the EJBMetaData interface for the enterprise bean.

HomeHandle

getHomeHandle

Get the HomeHandle for the home object.

void

remove(Handle handle)

Remove the EJB object identified by its Handle .

void

remove(Object key)

Remove the EJB object identified by the primary key. This will work only for entity beans.

Note

If you're wondering why you don't see methods such as create or find in either the local or remote home interfaces, there's a very good reason for this. It's because each create or find method can take different parameters in its method signature. There's no way to standardize on a set of create or find methods that will work in all situations. EJB developers need the flexibility to pass whatever arguments they need into the create or find methods to create or locate a bean instance.


Continuing with our OrderFulfillment example from earlier in the chapter, Listings 3.8 and 3.9 illustrate examples of a local and a remote interface, respectively.

Listing 3.8 The Local Home Interface for OrderFulfillmentProcessorBean
 import javax.ejb.CreateException;  import javax.ejb.EJBLocalHome;  public interface OrderFulfillmentProcessorHomeLocal extends EJBLocalHome {   /**     * This method corresponds to the ejbCreate method in the bean     * "OrderFulfillmentProcessorBean.java".     * The parameter sets of the two methods are identical. When the client calls     * <code>OrderFulfillmentProcessorHome.create()</code>, the container     * allocates an instance of the EJBean and calls <code>ejbCreate()</code>.     *     * @return                  OrderFulfillmentProcessor     * @exception               CreateException     *                          if there is a problem creating the bean     */    OrderFulfillmentProcessor create() throws CreateException;  } 
Listing 3.9 The Remote Home Interface for OrderFulfillmentProcessorBean
 import javax.ejb.CreateException;  import javax.ejb.EJBHome;  public interface OrderFulfillmentProcessorHome extends EJBHome {     /**       * This method corresponds to the ejbCreate method in the bean       * "OrderFulfillmentProcessor.java".       * The parameter sets of the two methods are identical. When the client calls       * <code>OrderFulfillmentProcessorHome.create()</code>, the container       * allocates an instance of the EJBean and calls <code>ejbCreate()</code>.       *       * @return                  OrderFulfillmentProcessor       * @exception               CreateException       *                          if there is a problem creating the bean       */      OrderFulfillmentProcessor create() throws CreateException;  } 

Notice that the main difference between the two types of home interfaces is that the local home extends EJBLocalHome and the remote home extends EJBHome .

The home interface for an enterprise can declare zero or more create methods, one for each way an instance of the bean can be initialized . The arguments of the create methods typically are used to initialize the state of the created object.

Note

The session bean home interface must define at least one create method, whereas the entity bean is not required to.


Just as with the component interface for an enterprise bean, the container will create an implementation object that implements the home interface of the enterprise bean.

The purpose of the home object is to provide a factory for creating objects that implement the component interface. There is typically only a single home object for a particular bean class. Because it's a factory, all clients can go through this factory to acquire a reference to a bean that the home factory is for. The container generates an object that implements your home interface and which provides a concrete implementation for clients to use. The home interface manages the life cycle of all instances of a particular bean. When client A needs to get a reference to an instance of the OrderFulfillmentProcessorBean , it asks the home object for that bean to do so. When client B asks for a different instance, the same home object does the work. Different home factories are used for local and remote client views, however.



Special Edition Using Enterprise JavaBeans 2.0
Special Edition Using Enterprise JavaBeans 2.0
ISBN: 0789725673
EAN: 2147483647
Year: 2000
Pages: 223

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net