11 Implementing an EJB 2.1 Session Bean

This chapter explains how to implement an EJB 2.1 session bean, including:

"Implementing an EJB 2.1 Stateless Session Bean"
"Implementing an EJB 2.1 Stateful Session Bean"

Note:

You can download EJB code examples from: http://www.oracle.com/technology/tech/java/oc4j/demos.

For more information, see:

Implementing an EJB 2.1 Stateless Session Bean

Table 11-1 summarizes the important parts of an EJB 2.1 stateless 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 Stateless Session Bean?".

Table 11-1 Parts of an EJB 2.1 Stateless Session Bean

Part	Description
Home Interface (remote or local)	Extends `javax.ejb.EJBHome` and `javax.ejb.EJBLocalHome` and requires a single `create()` factory method, with no arguments, 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.
TimedObject Interface	Optionally implements the `javax.ejb.TimedObject` interface. For more information, see "Understanding EJB Timer Services").
Bean implementation	Implements `SessionBean`. This class must be declared as public, contain a public, empty, default constructor, no `finalize`() method, and implements the methods defined in the component interface. Must contain a single `ejbCreate` method, with no arguments, to match the `create`() method in the home interface. Contains empty implementations for the container service methods, such as `ejbRemove`, and so on.

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").
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").
Implement the stateless session bean:
1. Implement a single ejbCreate method with no parameter that matches the home interface create method.
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 Lifecycle 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 stateless session bean, this method usually does nothing (does not actually add the SessionContext to the session bean's state).
Configure your ejb-jar.xml file to match your bean implementation (see "Using Deployment XML").

Using Java

Example 11-1 shows a typical implementation of a stateless session bean.

Example 11-1 EJB 2.1 Stateless Session Bean Implementation

package hello;
import javax.ejb.*;

public class HelloBean implements SessionBean
{

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

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

    /* ----------------------------------------
    * 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 setSessionContext(SessionContext ctx)
    {
    }

// Lifecycle Methods

    public void ejbActivate()
    {
    }

    public void ejbPassivate()
    {
    }

    public void ejbCreate()
    {
    }

    public void ejbRemove()
    {
    }
}

Using Deployment XML

Example 11-2 shows the ejb-jar.xml session element corresponding to the stateless session bean shown in Example 11-1.

Example 11-2 ejb-jar.xml For a Stateless 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>Stateless</session-type>
            <transaction-type>Container</transaction-type>
        </session>
    </enterprise-beans>
...

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

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 Pats 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`.

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").
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").
Implement the stateless session bean:
1. Implement the ejb* 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 Lifecycle 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.
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;
    }

// Lifecycle 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".

Implementing the Home Interfaces

The home interfaces (remote and local) are used to create the session bean instance; thus, they define the create method for your bean. As Table 11-3 shows, the type of create methods you define depends on the type of session bean you are creating:

Table 11-3 Home Interface Create Methods

Session Bean Type	Create Methods
Stateless Session Bean	Can have only a single `create` method, with no parameters.
Stateful Session Bean	Can have more one or more create methods with whatever parameters define the bean's state.

For each create method, you define a corresponding ejbCreate method in the bean implementation.

Implementing the Remote Home Interface

A remote client invokes the EJB through its remote interface. The client invokes the create method that is declared within the remote home interface. The container passes the client call to the ejbCreate method—with the appropriate parameter signature—within the bean implementation. The requirements for developing the remote home interface include:

The remote home interface must extend the javax.ejb.EJBHome interface.
All create methods may throw the following exceptions:
- javax.ejb.CreateException
- javax.ejb.RemoteException
- optional application exceptions
All create methods should not throw the following exceptions:
- javax.ejb.EJBException
- java.lang.RunTimeException

Example 11-5 shows a remote home interface called HelloHome for a stateless session bean.

Example 11-5 Remote Home Interface for a Stateless Session Bean

package hello;

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

public interface HelloHome extends EJBHome
{
  public Hello create() throws CreateException, RemoteException;
}

Example 11-6 shows a remote home interface called HelloHome for a stateful session bean. You use the arguments passed into the various create methods to initialize the session bean's state.

Example 11-6 Remote Home Interface for a Stateful Session Bean

package hello;

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

public interface HelloHome extends EJBHome
{
  public Hello create() throws CreateException, RemoteException;
  public Hello create(String message) throws CreateException, RemoteException;
  public Hello create(Collection messages) throws CreateException, RemoteException;
}

Implementing the Local Home Interface

An EJB can be called locally from a client that exists in the same container. Thus, a collocated bean, JSP, or servlet invokes the create method that is declared within the local home interface. The container passes the client call to the ejbCreate method—with the appropriate parameter signature—within the bean implementation. The requirements for developing the local home interface include:

The local home interface must extend the javax.ejb.EJBLocalHome interface.
All create methods may throw the following exceptions:
- javax.ejb.CreateException
- javax.ejb.RemoteException
- optional application exceptions
All create methods should not throw the following exceptions:
- javax.ejb.EJBException
- java.lang.RunTimeException

Example 11-7 shows a local home interface called HelloLocalHome for a stateless session bean.

Example 11-7 Local Home Interface for a Stateless Session Bean

package hello;

import javax.ejb.*;

public interface HelloLocalHome extends EJBLocalHome
{
 public HelloLocal create() throws CreateException;
}

Example 11-8 shows a local home interface called HelloLocalHome for a stateful session bean. You use the arguments passed into the various create methods to initialize the session bean's state.

Example 11-8 Local Home Interface for a Stateful Session Bean

package hello;

import javax.ejb.*;

public interface HelloLocalHome extends EJBLocalHome
{
  public HelloLocal create() throws CreateException;
  public HelloLocal create(String message) throws CreateException;
  public HelloLocal create(Collection messages) throws CreateException;
}

Implementing the Component Interfaces

The component interfaces define the business methods of the bean that a client can invoke.

Implementing the Remote Component Interface

The remote interface defines the business methods that a remote client can invoke. The requirements for developing the remote component interface include:

The remote component interface of the bean must extend the javax.ejb.EJBObject interface, and its methods must throw the java.rmi.RemoteException exception.
You must declare the remote interface and its methods as public for remote clients.
The remote component interface, all its method parameters, and return types must be serializable. In general, any object that is passed between the client and the EJB must be serializable, because RMI marshals and unmarshalls the object on both ends.
Any exception can be thrown to the client, as long as it is serializable. Runtime exceptions, including EJBException and RemoteException, are transferred back to the client as remote runtime exceptions.

Example 11-9 shows a remote component interface called Hello with its defined methods, each of which will be implemented in the corresponding session bean.

Example 11-9 Remote Component Interface for EJB 2.1 Session Bean

package hello;

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

public interface Hello extends EJBObject
{
    public String sayHello(String myName) throws RemoteException;
    public String sayHello() throws RemoteException;
}

Implementing the Local Component Interface

The local component interface defines the business methods of the bean that a local (collocated) client can invoke. The requirements for developing the local component interface include:

The local component interface of the bean must extend the javax.ejb.EJBLocalObject interface.
You declare the local component interface and its methods as public.

Example 11-10 shows a local component interface called HelloLocal with its defined methods, each of which will be implemented in the corresponding session bean.

Example 11-10 Local Component Interface for EJB 2.1 Session Bean

package hello;

import javax.ejb.*;

public interface HelloLocal extends EJBLocalObject
{
    public String sayHello(String myName);
    public String sayHello();
}

Implementing the setSessionContext Method

You use this method to obtain a reference to the context of the bean. A session bean has a session context that the container maintains and makes available to the bean. The bean may use the methods in the session context to make callback requests to the container.

The container invokes setSessionContext method, after it first instantiates the bean, to enable the bean to retrieve the session context. The container will never call this method from within a transaction context. If the bean does not save the session context at this point, the bean will never gain access to the session context.

When the container calls this method, it passes the reference of the SessionContext object to the bean. The bean can then store the reference for later use.

Example 11-11 shows a session bean saving the session context in the sessctx variable.

Example 11-11 Implementing the setSessionContext Method

import javax.ejb.*;

public class myBean implements SessionBean {
   SessionContext sessctx;

   public void setSessionContext(SessionContext ctx) {
      sessctx = ctx;   // session context is stored in instance variable
   }
   // other methods in the bean
}