Specifying a Stateless Session bean

You already know that there are two different types of Session bean—stateful and stateless. You'll see examples of both types today, but the first example you will study is the stateless Agency bean you saw yesterday.

As you will by now have gathered, the responsibilities of Session beans (and indeed, Entity beans) are specified through their 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 you extend javax.ejb.EJBHome; and to define a remote interface you extend javax.ejb.EJBObject. Because both EJBHome and EJBObject extend the java.rmi.Remote interface, their methods are restricted as follows:

• All methods must throw RemoteException.

• All parameters and return types must either be Serializable or Remote objects.

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 reference, which is the remote interface for the Agency bean.

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 can also throw javax.ejb.CreateException to indicate that it was unable to initialize itself correctly.

The create() method in the home interface requires 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 (this class is discussed in detail in the next section, “Implementing a StatelessSession bean”):

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 of this method must match the argument list of the create() method in the home interface. 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 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

package agency;

import java.rmi.*;
import java.util.*;
import javax.ejb.*;

public interface Agency extends EJBObject
{
    String getAgencyName() throws RemoteException;

    Collection getApplicants() throws RemoteException;
    void createApplicant(String login, String name, String email)
        throws RemoteException, DuplicateException, CreateException
    void deleteApplicant (String login)
        throws RemoteException, NotFoundException;

    Collection getCustomers() throws RemoteException;
    void createCustomer(String login, String name, String email)
        throws RemoteException, DuplicateException, CreateException;
    void deleteCustomer(String login)
        throws RemoteException, NotFoundException;

    Collection getLocations() throws RemoteException;
    void addLocation(String name) throws RemoteException, DuplicateException;
    void removeLocation(String code) throws RemoteException, NotFoundException;

    Collection getSkills() throws RemoteException;
    void addSkill(String name) throws RemoteException, DuplicateException;
    void removeSkill(String name) throws RemoteException, NotFoundException;

    List select(String table) throws RemoteException;
}

You can see that the Agency Session bean provides functionality, or services, for 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 service methods in the remote interface, there must be a correspondingly named method in the Session bean. As was noted yesterday, 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. 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.