Specifying a Stateless Session Bean

As you will by now have gathered, the responsibilities of Session beans (and indeed, Entity beans) are specified through its remote and home interfaces. These are what the EJB container makes available to the remote clients.

To define a home interface for a stateless Session bean, extend javax.ejb.EJBHome. To define a remote interface, extend javax.ejb.EJBObject. Because both EJBHome and EJBObject extend the java.rmi.Remote interface, the rules for remote objects (in the Java sense of the word) must be followed.

The following is the home interface for the Agency session bean. If it looks familiar, it should be—you saw this for the first time just yesterday.

package agency;

import java.rmi.*;
import javax.ejb.*;
public interface AgencyHome extends EJBHome
{
    Agency create() throws RemoteException, CreateException;
}

The AgencyHome interface defines a single no-arg method called create(). This method returns an Agency, which is the remote interface for the Agency bean. Because this remote interface is remote (that is, extends java.rmi.Remote), what the client that calls this interface will receive is a reference to the remote Agency object. In other words, the client will obtain an RMI stub to the Agency.

The EJB specification requires that stateless Session beans must define this single no-arg version of the create() method. The bean can perform any initialization it requires there. The create() method throws java.rmi.RemoteException, as required for remote objects, and also throws javax.ejb.CreateException. This is an exception that the bean can throw to indicate that it was unable to initialize itself correctly.

The create() method in the home interface implies a corresponding ejbCreate() method in the bean class itself. This delegation to a method with an ejb prefix is prevalent throughout the EJB specification, so you will become quite familiar with it over the next few days. The corresponding code in the AgencyBean class is as follows:

package agency;

// some import statements omitted
import java.rmi.*;
import java.util.*;
import javax.ejb.*;

public class AgencyBean implements SessionBean
{
    public void ejbCreate() throws CreateException {
        // implementation omitted
    }

    // code omitted
}

Note that the ejbCreate() method also takes no arguments because the argument list must match. The throws clause includes javax.ejb.CreateException, because that was defined in the home interface, but does not include java.rmi.RemoteException. This is because the bean itself is not remote; it is the code generated by the vendor's deployments tools that is remote. The EJB specification requires also that ejbCreate() method returns void.

Listing 5.1 shows the remote interface for the Agency session bean. Again, you saw this yesterday:

Listing 5.1. Remote Interface for the Stateless Agency Bean

 1: package agency;
 2:
 3: import java.rmi.*;
 4: import java.util.*;
 5: import javax.ejb.*;
 6:
 7: public interface Agency extends EJBObject
 8: {
 9:     String getAgencyName() throws RemoteException;
10:
11:     Collection findAllApplicants() throws RemoteException;
12:     void createApplicant(String login, String name, String email)
13:         throws RemoteException, DuplicateException, CreateException;
14:     void deleteApplicant (String login) throws RemoteException, NotFoundException;
15:
16:     Collection findAllCustomers() throws RemoteException;
17:     void createCustomer(String login, String name, String email)
18:         throws RemoteException, DuplicateException, CreateException;
19:     void deleteCustomer(String login) throws RemoteException, NotFoundException;
20:
21:     Collection getLocations() throws RemoteException;
22:     void addLocation(String name) throws RemoteException, DuplicateException;
23:     void removeLocation(String code) throws RemoteException, NotFoundException;
24:
25:     Collection getSkills() throws RemoteException;
26:     void addSkill(String name) throws RemoteException, DuplicateException;
27:     void removeSkill(String name) throws RemoteException, NotFoundException;
28:
29:     List select(String table) throws RemoteException;
30: }
					

You can see that the Agency Session bean provides a number of sets of functionality, managing applicants, customers, locations, and skills. These services manipulate data within the database, but there is no underlying state for the bean itself. In each case, the methods throw java.rmi.RemoteException as required and also throw various other exceptions. The DuplicateException and NotFoundException are user-defined exception classes that simply extend java.lang.Exception.

For each of these methods in the remote interface, there is a corresponding method in the Session bean. As was noted before, this is not because the bean has implemented the remote interface (it hasn't) but because the EJB specification requires it so that the EJBObject proxy (the vendor-generated implementation of the remote interface) can delegate to the bean. The business methods for the AgencyBean have the same signature as those in the remote interface, with the exception that they do not throw java.rmi.RemoteException. Those are the steps to specifying a stateless Session bean's interface. Indeed, as you will see later today and tomorrow, specifying the interface of stateful Session beans and of Entity beans follows along very similar lines. In the next section, “Implementing a Stateless Session Bean,” you will see the implementation of some of these methods.