Declaring the Home Interface

Every entity or session bean must have a home interface that extends javax.ejb.EJBHome ,or a local home interface that extends javax.ejb.EJBLocalHome , or both. The home interface provides factory operations that allow clients to create and remove EJB instances. In the case of entity beans, this interface also allows clients to obtain references to existing entity beans and to execute business methods that aren't specific to a particular entity object. The methods for removing an entity object are included for you in the declarations of EJBHome and EJBLocalHome , but you're responsible for declaring your own methods to create and find entities and execute business logic.

Note

The EJB 2.0 Specification uses the term component interface when referring to the local and remote interfaces collectively. However, there isn't an equivalent name used when referring to both the home and the local home interfaces. This book follows the same convention used by the specification and identifies these interfaces generically as the home interface . When a point specific to a local client is being made, the interface is referred to as the local home interface . Similarly, remote home interface is used when necessary for clarity.

Creating an Entity Bean

You might define entity beans that represent read-only data in a system. You might also define entity beans whose attributes can be modified by a client with changes written to the underlying data store. Both of these situations can be supported without a client ever needing to create a new entity object. However, if you do want a client to be able to create a new entity, you must define at least one create method in the bean's home interface.

You should declare a create method for each way you want a client to be able to create an entity. This is similar to declaring multiple constructors in a class that accept different types of initialization parameters. To allow a client to create an entity without proving any initialization data, you might define a method like the following:

 public EnglishAuction create() throws CreateException; 

To support initialization data, you might use the following:

 public EnglishAuction createWithData(String name, String description)    throws CreateException; 

As you can see from these examples, which are valid for a local home interface, create methods follow a prescribed form. In particular, each of your create methods in a local home must

• Have a name that starts with create

• Be declared to return the local interface type

• Include javax.ejb.CreateException in its throws clause

The requirements for a remote home interface are similar in that each create method declared here must

• Have a name that starts with create

• Be declared to return the remote interface type

• Include java.rmi.RemoteException and javax.ejb.CreateException in its throws clause

As you'll see later, each create method you declare must have corresponding ejbCreate and ejbPostCreate methods in the bean implementation class. If these methods declare additional exceptions, those exceptions must be included in the throws clause of the create method as well. Home interface methods provided for remote clients represent remote calls, so declaring that they might throw a RemoteException is necessary just as it is for remote interface methods. CreateException is a standard exception used to report an error during creation from which a client might be able to recover. This exception is covered more in Chapter 13.

To learn more about reporting a problem during entity creation, see "CreateException," p. 367 .

Finding an Entity Bean

Often, more important than creating an entity object is locating one that already exists. To support this, you declare methods known as finder methods in the home interface. A finder method is responsible for locating all objects that match some particular criteria. At a minimum, every home interface supports finding an entity by primary key using a method declaration such as

 public EnglishAuction findByPrimaryKey(Integer primaryKey)    throws FinderException; 

The findByPrimaryKey method is required to have this exact name, to return the local (or remote) interface type, and to accept a single parameter of the primary key type. As with create methods, there are certain rules to follow when you declare your own finder methods. Each of your finder methods declared in the local home interface must

• Have a name that starts with find

• Be declared to return the local interface type or a collection of objects that implement the local interface

• Include javax.ejb.FinderException (see Chapter 13) in its throws clause

The requirements for a remote home interface are similar in that each of these finder methods must

• Have a name that starts with find

• Be declared to return the remote interface type or a collection of objects that implement the remote interface

• Include java.rmi.RemoteException and javax.ejb.FinderException in its throws clause

As an example, you might declare additional finders used by local clients to locate auctions based on their current state:

 public Collection findAllAuctions() throws FinderException;  public Collection findNonPendingAuctions() throws FinderException;  public EnglishAuction findAuctionForItem(Integer itemId)    throws FinderException; 

Removing an Entity Bean

EJBHome declares two methods that you can use to remove enterprise bean instances:

 void remove(Handle handle) throws RemoteException, RemoveException;  void remove(Object primaryKey) throws RemoteException, RemoveException; 

Local clients don't need to work with handles to enterprise beans, so EJBLocalHome declares only a single remove method:

 void remove(Object primaryKey) throws EJBException, RemoveException; 

The container implements these methods for you, so you don't have to worry about defining them. You should remember that the component interface also includes a remove method. The difference with the methods defined here is that you don't have to go to the effort to obtain a local or remote reference to an entity object to delete it if you know its handle or primary key value. The important point to make about the remove methods in both the component and home interfaces is that they result in the referenced entity being deleted from the underlying data store. After an entity has been removed, any call made to it by a client that still holds a remote interface reference to it results in a java.rmi.NoSuchObjectException . A local client call on an invalid local interface reference results in a javax.ejb.NoSuchObjectLocalException .

Declaring Home Interface Business Methods

Prior to the EJB 2.0 Specification, all entity bean business methods had to be accessed through the component interface. This meant that an invocation of a business method was always associated with a particular entity object even if the logic of the method didn't require access to that entity's state. If you needed to perform some processing related to a certain entity class but independent of an instance, you either declared the method as part of the component interface anyway or implemented it in a session bean. You can't declare EJB business methods as static , so there was no way to indicate the intent of these methods when they were declared within the entity bean class.

EJB 2.0 introduced the concept of the home method . As the name implies, a home method is a business method declared in the home interface instead of in the remote. Home methods are intended to support business logic that is closely tied to an entity bean class but not to a single instance. Because the home interface is a factory that is never associated with a single instance, home methods can't access any instance data when executing. The following rules govern home methods:

• A home method can be named anything in general, but its name can't start with create , find , or remove .

• The parameters and return type of a home method declared in a remote home interface must be legal RMI-IIOP types.

• The throws clause of a home method may include application exceptions as appropriate. When declared in a remote home interface, the throws clause must include java.rmi.RemoteException .

A use of a home method for the auction entity bean might be to report all the items that are currently up for auction:

 public Collection getItemsBeingAuctioned(); 

The EnglishAuctionHome Interface

Listing 5.10 puts all the possibilities together to present a possible local home interface for the auction entity bean. This listing includes several create and finder methods and an example of a home method declaration.

Listing 5.10 EnglishAuctionHome.java “A Local Home Interface for an Auction Entity Bean

 package com.que.ejb20.auction.model;  /**   * Title:        EnglishAuctionHome<p>   * Description:  Home interface for the EnglishAuction entity bean<p>   */  import java.util.Collection;  import javax.ejb.EJBLocalHome;  import javax.ejb.CreateException;  import javax.ejb.FinderException;  public interface EnglishAuctionHome extends EJBLocalHome {   /**     * Create an auction without initializing it     */    public EnglishAuction create() throws CreateException;    /**     * Create an auction and perform some limited initialization     */    public EnglishAuction createWithData(String name, String description)      throws CreateException;    /**     * Retrieve an auction using its primary key     */    public EnglishAuction findByPrimaryKey(Integer primaryKey)      throws FinderException;    /**     * Retrieve all the auctions     */    public Collection findAllAuctions() throws FinderException;    /**     * Retrieve all the auctions that are open, cancelled, or closed     */    public Collection findNonPendingAuctions() throws FinderException;    /**     * Home method for reporting all auction items     */    public Collection getItemsBeingAuctioned();  }