J2EE^TM Developer's Guide
Session Beans

A Session Bean Example

The session bean in this section represents the shopping cart in an online book store. The bean's client may add a book to the cart, remove a book, or retrieve the cart's contents. To construct a session bean, you need the following code:

The preceding files are required for any enterprise bean. To meet the needs of a specific application, an enterprise bean may also need some helper classes. The CartEJB session bean uses two helper classes, BookException and IdVerifier, which are discussed in the section, "Helper Classes" .)

The source code for all of these files are in the doc/guides/ejb/examples/cart directory, along with CartClient.java, the code for the client program.

Session Bean Class

The session bean class for this example is called CartEJB. Like any session bean, the CartEJB class must meet these requirements:

It implements the SessionBean interface.
The class is defined as public.
The class cannot be defined as abstract or final.
It implements one or more ejbCreate methods.
It implements the business methods.
It contains a public constructor with no parameters.
It must not define the finalize method.

The source code for CartEJB follows:

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

public class CartEJB implements SessionBean {

   String customerName;
   String customerId;
   Vector contents;

   public void ejbCreate(String person) throws CreateException {

      if (person == null) {
        throw new CreateException("Null person not allowed.");
      }
      else {
         customerName = person;
      }

      customerId = "0";
      contents = new Vector();
   }

   public void ejbCreate(String person, String id) 
     throws CreateException {

      if (person == null) {
        throw new CreateException("Null person not allowed.");
      }
      else {
         customerName = person;
      }

      IdVerifier idChecker = new IdVerifier();
      if (idChecker.validate(id)) {
         customerId = id;
      }
      else {
         throw new CreateException("Invalid id: " + id);
      }

      contents = new Vector();
   }

   public void addBook(String title) {

      contents.addElement(title);
   }

   public void removeBook(String title) throws BookException {

      boolean result = contents.removeElement(title);
      if (result == false) {
         throw new BookException(title + " not in cart.");
      }
   }

   public Vector getContents() {
      return contents;
   }

   public CartEJB() {}
   public void ejbRemove() {}
   public void ejbActivate() {}
   public void ejbPassivate() {}
   public void setSessionContext(SessionContext sc) {}

}

The SessionBean Interface

The SessionBean interface extends the EnterpriseBean interface, which in turn extends the Serializable interface. The SessionBean interface declares the ejbRemove, ejbActivate, ejbPassivate, and setSessionContext methods. The CartEJB class doesn't use these methods, but it must implement them because they're declared in the SessionBean interface. Consequently, these methods are empty in the CartEJB class. Later sections explain when you might use these methods.

The ejbCreate Methods

Because an enterprise bean runs inside an EJB container, a client cannot directly instantiate the bean. Only the EJB container can instantiate an enterprise bean. During instantiation, the example program performs these steps:

1. The client invokes a create method on the home object:

Cart shoppingCart = home.create("Duke DeEarl","123");

2. The EJB container instantiates the enterprise bean.

3. The EJB container invokes the appropriate ejbCreate method in CartEJB:

    public void ejbCreate(String person, String id) 
      throws CreateException {

      if (person == null) {
        throw new CreateException("Null person not allowed.");
      }
      else {
         customerName = person;
      }

      IdVerifier idChecker = new IdVerifier();
      if (idChecker.validate(id)) {
         customerId = id;
      }
      else {
         throw new CreateException("Invalid id: " + id);
      }

      contents = new Vector();
   }

Typically, an ejbCreate method initializes the state of the enterprise bean. The preceding ejbCreate method, for example, initializes the customerName and customerId variables with the arguments passed by the create method.

An enterprise bean may have one or more ejbCreate methods. The signatures of the methods meet the following requirements:

The access control modifier must be public.
The return type must be void.
The arguments must be legal types for Java RMI.
The modifier cannot be static or final.

The throws clause may include the javax.ejb.CreateException and other exceptions that are specific to your application. The ejbCreate method usually throws a CreateException if an input parameter is invalid.

Business Methods

The primary purpose of a session bean is to run business tasks for the client. The client invokes business methods on the remote object reference that is returned by the create method. From the client's perspective, the business methods appear to run locally, but they actually run remotely in the session bean. The following code snippet shows how the CartClient program invokes the business methods:

Cart shoppingCart = home.create("Duke DeEarl", "123");
. . .
shoppingCart.addBook("The Martian Chronicles"); 
shoppingCart.removeBook("Alice In Wonderland");
bookList = shoppingCart.getContents();

The CartEJB class implements the business methods in the following code:

public void addBook(String title) {

   contents.addElement(new String(title));
}

public void removeBook(String title) throws BookException {

   boolean result = contents.removeElement(title);
   if (result == false) {
      throw new BookException(title + " not in cart.");
   }
}

public Vector getContents() {
   return contents;
}

The signature of a business method must conform to these rules:

The method name must not conflict with one defined by the EJB architecture. For example, you cannot call a business method ejbCreate or ejbActivate.
The access control modifier must be public.
The arguments and return types must be legal types for Java RMI.
The modifier must not be static or final.

The throws clause may include exceptions that you define for your application. The removeBook method, for example, throws the BookException if the book is not in the cart.

To indicate a system-level problem, such as the inability to connect to a database, a business method should throw the javax.ejb.EJBException. When a business method throws an EJBException, the container wraps it in a RemoteException, which is caught by the client. The container will not wrap application exceptions such as BookException. Because EJBException is a subclass of RuntimeException, you do not need to include it in the throws clause of the business method.

Home Interface

A home interface extends the EJBHome interface. The purpose of the home interface is to define the create methods that a client may invoke. The CartClient program, for example, invokes this create method:

Cart shoppingCart = home.create("Duke DeEarl", "123");

Every create method in the home interface corresponds to an ejbCreate method in the bean class. The signatures of the ejbCreate methods in the CartEJB class follow:

public void ejbCreate(String person) throws CreateException   
. . . 
public void ejbCreate(String person, String id) 
   throws CreateException

Compare the ejbCreate signatures with those of the create methods in the CartHome interface:

import java.io.Serializable;
import java.rmi.RemoteException;
import javax.ejb.CreateException;
import javax.ejb.EJBHome;

public interface CartHome extends EJBHome {
    Cart create(String person) throws RemoteException,
                                      CreateException;
    Cart create(String person, String id) throws RemoteException, 
                                                 CreateException; 
}

The signatures of the ejbCreate and create methods are similar, but differ in important ways. The rules for defining the signatures of the create methods of a home interface follow:

The number and types of argments in a create method must match those of its corresponding ejbCreate method.
The arguments and return type of the create method must be valid RMI types.
A create method returns the remote interface type of the enterprise bean. (But an ejbCreate method returns void.)
The throws clause of the create method must include the java.rmi.RemoteException and the javax.ejb.CreateException.

Remote Interface

The remote interface, which extends javax.ejb.EJBObject, defines the business methods that a client may invoke. Here is the source code for the Cart remote interface :

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

public interface Cart extends EJBObject {
 
   public void addBook(String title) throws RemoteException;
   public void removeBook(String title) throws BookException,
                                               RemoteException;
   public Vector getContents() throws RemoteException;
}

The method definitions in a remote interface must follow these rules:

Each method in the remote interface must match a method implemented in the enterprise bean class.
The signatures of the methods in the remote interface must be identical to the signatures of the corresponding methods in the enterprise bean class.
The arguments and return values must be valid RMI types.
The throws clause must include the java.rmi.RemoteException.

Helper Classes

The CartEJB bean has two helper classes: BookExceptionand IdVerifier. The BookException is thrown by the removeBook method and the IdVerifier validates the customerId in one of the ejbCreate methods. Helper classes should reside in the EJB .jar file that contains the enterprise bean class

Prev | Next

TOC | Index