Declaring the Home Interface

The home interface for a session bean declares the methods for creating and removing session objects. You can also use a remote home interface to get a reference to the bean's EJBMetaData or the home handle. Both the EJBMetaData and the HomeHandle interfaces were described previously in Chapter 3, "EJB Concepts." One restriction related to a session bean's EJBMetaData is that you can't call the getPrimaryKeyClass method or a RuntimeException will be thrown.

Unlike entity beans, you can't declare finder methods or home methods for a session bean. Finder methods wouldn't make sense for a session bean because a session object's identity is hidden from the client. When a client needs to obtain a reference to a session object, any instance pulled from the pool and made available by the container in response to a call to a create method is just as good as any other. As for home methods, session bean business methods already have the flexibility to manipulate multiple entities stored in a database (usually by accessing multiple entity objects). In fact, the functionality provided by a home method in an entity bean is something you would have most likely implemented in a session bean method prior to EJB 2.0.

Creating a Session Bean

A client obtains a component interface reference to a session object by calling a create method on a reference to the bean's home interface. Unlike entity beans, you must declare at least one create method for a session bean. Because session beans don't support the concept of a finder method, a session object always must be "created" for a client to have one with which to work.

You're allowed to define multiple create methods if you want to give clients more than one way to initialize a session object. However, this is useful only for stateful session beans because they're the only ones capable of maintaining state supplied by a client across method calls. For a stateless session bean, you're only allowed to declare a single create method like the following example:

 public AuctionHouse create() throws CreateException, RemoteException; 

This or any other create method you declare must

• Have a name that starts with create (for a stateless session bean, the name must be exactly create and the method must not accept any arguments)

• Be declared to return the remote interface type if found in a remote home interface, or the local interface type if found in a local home interface

• Include javax.ejb.CreateException in its throws clause and java.rmi.RemoteException (if found in a remote home interface)

As with entity beans, you must implement a corresponding ejbCreate for each create method you declare, but there's no concept of an ejbPostCreate for session beans. Other than the rules already given, the declaration of your create methods must include any application exceptions declared in the throws clause of the corresponding ejbCreate method. The required CreateException is the standard application exception you can use to report problems with initialization parameters passed to the create method.

For more information on reporting initialization problems when creating an enterprise bean instance, see "CreateException," p. 367 .

Removing a Session Bean

When a remote client has finished with a session object, it should call the remove() method declared by EJBObject or remove(Handle handle) declared by EJBHome . A local client only has the option of calling the remove() method declared by EJBLocalObject . For either client type, calling the remove(Object primaryKey) method declared by EJBHome or EJBLocalHome results in a RemoveException because a session bean doesn't have a primary key.

Typically, a client calls a create method to get a reference to a session object component interface, calls business methods on the reference to do some work, and then calls remove on the reference to free up the bean instance. It's also possible for a remote client to obtain the handle to the object from the home interface and serialize it for later use. In particular, this can be done for a stateful session bean to reconnect to a session object holding the conversational state established for a client. Regardless of whether the handle is used to access a particular client's session object again, it can be used to remove the object from the container using the remove method declared by the home interface. Once a session object has been removed, any calls to its remote interface result in a java.rmi.NoSuchObjectException , and any calls to its local interface cause a javax.ejb.NoSuchObjectLocalException .

The AuctionCheckoutHome Interface

Listing 9.5 contains a home interface declaration for the auction checkout stateful session bean. This interface illustrates the use of multiple create methods. Unlike a component interface, a session bean home interface with multiple create methods gives away the fact that it belongs to a stateful bean.

Listing 9.5 AuctionCheckoutHome.java “A Home Interface for a Stateful Session Bean

 package com.que.ejb20.auction.controller;  /**   * Title:        AuctionCheckoutHome<p>   * Description:  Home interface for the Auction Checkout stateful   *               session bean<p>  */  import java.rmi.RemoteException;  import javax.ejb.CreateException;  import javax.ejb.EJBHome;  public interface AuctionCheckoutHome extends EJBHome {   /**     * Create a session object using default initialization     */    public AuctionCheckout create() throws CreateException, RemoteException;    /**     * Create a session object by supplying the auction and bidder primary keys     */    public AuctionCheckout create(int auctionId, int bidderId)      throws CreateException, RemoteException;  } 

The AuctionManagerHome and AuctionHouseHome interfaces are less interesting than the one shown in Listing 9.5. All you need to do in the home interface for a stateless session bean is declare a single create method that accepts no arguments.