Implementing an EJB 2.1 Stateful Session Bean

Table 11-2summarizes the important parts of an EJB 2.1 stateful session bean and the following procedure describes how to implement these parts. For a typical implementation, see "Using Java". For more information, see "What is a Stateful Session Bean?".

Table 11-2 Parts of an EJB 2.1 Stateful Session Bean

Part	Description
Home Interface (remote or local)	Extends javax.ejb.EJBHome and javax.ejb.EJBLocalHome and requires one or more create() factory methods, and a single remove() method.
Component Interface (remote or local)	Extends javax.ejb.EJBObject for the remote interface and javax.ejb.EJBLocalObject for the local interface. It defines the business logic methods, which are implemented in the bean implementation.
Bean implementation	Implements SessionBean. This class must be declared as public, contain a public, empty, default constructor, no finalize method, and implement the methods defined in the remote interface. Must contain ejbCreate methods equivalent to the create methods defined in the home interface. That is, each ejbCreate method is matched–by its parameter signature–to a create method defined in the home interface. Implements the container service methods, such as ejbRemove, and so on. Also, optionally implements the SessionSynchronization interface for container-managed transactions, which includes afterBegin, beforeCompletion, and afterCompletion.

1. Create the home interfaces for the bean (see "Implementing the Home Interfaces").

   The remote home interface defines the create method that a client can invoke remotely to instantiate your bean. The local home interface defines the create method that a collocated bean can invoke locally to instantiate your bean.

   1. To create the remote home interface, extend javax.ejb.EJBHome (see "Implementing the Remote Home Interface").

   2. To create the local home interface, extend javax.ejb.EJBLocalHome (see "Implementing the Local Home Interface").

2. Create the component interfaces for the bean (see "Implementing the Component Interfaces").

   The remote component interface declares the business methods that a client can invoke remotely. The local interface declares the business methods that a collocated bean can invoke locally.

   1. To create the remote component interface, extend javax.ejb.EJBObject (see "Implementing the Remote Component Interface").

   2. To create the local component interface, extend javax.ejb.EJBLocalObject (see "Implementing the Local Component Interface").

3. Implement the stateless session bean as follows:

   1. Implement the ejb<METHOD> methods that match the home interface create methods.

      For a stateful session bean, provide ejbCreate methods with corresponding argument lists for each create method in the home interface.

   2. Implement the business methods that you declared in the home and component interfaces.

   3. Implement the javax.ejb.SessionBean interface to implement the container callback methods it defines (see "Configuring a Life Cycle Callback Method for an EJB 2.1 Session Bean").

   4. Implement a setSessionContext method that takes an instance of SessionContext (see "Implementing the setSessionContext Method").

      For a stateful session bean, this method usually adds the SessionContext to the session bean's state.

4. Configure your ejb-jar.xml file to match your bean implementation (see "Using Deployment XML").

Using Java

Example 11-3 shows a typical implementation of a stateful session bean.

Example 11-3 EJB 2.1 Stateful Session Bean Implementation

package hello;
import javax.ejb.*;

public class HelloBean implements SessionBean {
    /* ----------------------------------------
    * State
    * -------------------------------------- */

    private SessionContext ctx;
    private Collection messages;
    private String defaultMessage = "Hello, World!";

    /* ----------------------------------------
    * Begin business methods. The following methods
    * are called by the client code.
    * -------------------------------------- */

    public String sayHello(String myName) throws EJBException {
        return ("Hello " + myName);
    }

    public String sayHello() throws EJBException {
        return defaultMessage;
    }

    /* ----------------------------------------
    * Begin private methods. The following methods
    * are used internally.
    * -------------------------------------- */

...

    /* ------------------------------------------------------
    * Begin EJB-required methods. The following methods are called
    * by the container, and never called by client code.
    * ------------------------------------------------------- */

    public void ejbCreate() throws CreateException {
        // when bean is created
    }

    public void ejbCreate(String message) throws CreateException {
        this.defaultMessage = message;
    }

    public void ejbCreate(Collection messages) throws CreateException {
        this.messages = messages;
    }

    public void setSessionContext(SessionContext ctx) {
        this.ctx = ctx;
    }

// Life Cycle Methods

    public void ejbActivate() {
    }

    public void ejbPassivate() {
    }

    public void ejbCreate() {
    }

    public void ejbRemove() {
    }
}

Using Deployment XML

Example 11-4 shows the ejb-jar.xml session element corresponding to the stateful session bean shown in Example 11-3.

Example 11-4 ejb-jar.xml For a Stateful Session Bean

...
    <enterprise-beans>
        <session>
            <ejb-name>Hello</ejb-name>
            <home>hello.HelloHome</home>
            <remote>hello.Hello</remote>
            <ejb-class>hello.HelloBean</ejb-class>
            <session-type>Stateful</session-type>
            <transaction-type>Container</transaction-type>
        </session>
    </enterprise-beans>
...

For more information on deployment files, see "Configuring Deployment Descriptor Files".