EJB Programmer's Guide: Developing Session Beans

Target Audience and Content

The target audience for this guide is the Enterprise Bean provider, i.e. the person in charge of developing the software components on the server side and, more specifically, the Session Beans.

The content of this guide is the following:

Target Audience and Content
Introduction
The Home Interface
The Component Interface
The Enterprise Bean Class
Tuning Stateless Session Bean Pool

Introduction

A Session Bean is composed of the following parts, which are developed by the Enterprise Bean Provider:

The Component Interface is the client view of the bean. It contains all the "business methods" of the bean.
The Home Interface contains all the methods for the bean life cycle (creation, suppression) used by the client application.
The bean implementation class implements the business methods and all the methods (described in the EJB specification), allowing the bean to be managed in the container.
The deployment descriptor contains the bean properties that can be edited at assembly or deployment time.

Note that, according to the EJB 2.0 specification, the couple "Component Interface and Home Interface" may be either local or remote. Local Interfaces (Home and Component) are to be used by a client running in the same JVM as the EJB component. Create and finder methods of a local or remote home interface return local or remote component interfaces respectively. An EJB component can have both remote and local interfaces, even if typically only one type of interface is provided.

The description of these elements is provided in the following sections.

Note: in this documentation, the term "Bean" always means "Enterprise Bean."

A session bean object is a short-lived object that executes on behalf of a single client.There are stateless and stateful session beans. Stateless beans do not maintain state across method calls. Any instance of stateless beans can be used by any client at any time. Stateful session beans maintain state within and between transactions. Each stateful session bean object is associated with a specific client. A stateful session bean with container-managed transaction demarcation can optionally implement the SessionSynchronization interface. In this case, the bean objects will be informed of transaction boundaries. A rollback could result in a session bean object's state being inconsistent; in this case, implementing the SessionSynchronization interface may enable the bean object to update its state according to the transaction completion status.

The Home Interface

A Session bean's home interface defines one or more create(...) methods. Each create method must be named create and must match one of the ejbCreate methods defined in the enterprise Bean class. The return type of a create method must be the enterprise Bean's remote interface type.
The home interface of a stateless session bean must have one create method that takes no arguments.

All the exceptions defined in the throws clause of an ejbCreate method must be defined in the throws clause of the matching create method of the home interface.

A remote home interface extends the javax.ejb.EJBHome interface, while a local home interface extends the javax.ejb.EJBLocalHome interface.

Example:

The following examples use a Session Bean named Op.

    public interface OpHome extends EJBHome {
        Op create(String user) throws CreateException, RemoteException;
    }

A local home interface could be defined as follows (LocalOp being the local component interface of the bean):

    public interface LocalOpHome extends EJBLocalHome {
        LocalOp create(String user) throws CreateException;
    }

The Component Interface

The Component Interface is the client's view of an instance of the session bean. This interface contains the business methods of the enterprise bean. The interface must extend the javax.ejb.EJBObject interface if it is remote, or the javax.ejb.EJBLocalObject if it is local. The methods defined in a remote component interface must follow the rules for Java RMI (this means that their arguments and return value must be valid types for java RMI, and their throws clause must include the java.rmi.RemoteException). For each method defined in the component interface, there must be a matching method in the enterprise Bean's class (same name, same arguments number and types, same return type, and same exception list, except for RemoteException).

Example:

    public interface Op extends EJBObject {
        public void buy (int Shares)  throws RemoteException;
        public int  read ()           throws RemoteException;
    }

The same type of component interface could be defined as a local interface (even if it is not considered good design to define the same interface as both local and remote):

    public interface LocalOp extends EJBLocalObject {
        public void buy (int Shares);
        public int  read ();
    }

The Enterprise Bean Class

This class implements the Bean's business methods of the component interface and the methods of the SessionBean interface, which are those dedicated to the EJB environment. The class must be defined as public and may not be abstract. The Session Bean interface methods that the EJB provider must develop are the following:

public void setSessionContext(SessionContext ic);
This method is used by the container to pass a reference to the SessionContext to the bean instance. The container invokes this method on an instance after the instance has been created. Generally, this method stores this reference in an instance variable.
public void ejbRemove();
This method is invoked by the container when the instance is in the process of being removed by the container. Since most session Beans do not have any resource state to clean up, the implementation of this method is typically left empty.
public void ejbPassivate();
This method is invoked by the container when it wants to passivate the instance. After this method completes, the instance must be in a state that allows the container to use the Java Serialization protocol to externalize and store the instance's state.
public voidejbActivate();
This method is invoked by the container when the instance has just been reactivated. The instance should acquire any resource that it has released earlier in the ejbPassivate() method.

A stateful session Bean with container-managed transaction demarcation can optionally implement the javax.ejb.SessionSynchronization interface. This interface can provide the Bean with transaction synchronization notifications. The Session Synchronization interface methods that the EJB provider must develop are the following:

public void afterBegin();
This method notifies a session Bean instance that a new transaction has started. At this point the instance is already in the transaction and can do any work it requires within the scope of the transaction.
public void afterCompletion(boolean committed);
This method notifies a session Bean instance that a transaction commit protocol has completed and tells the instance whether the transaction has been committed or rolled back.
public void beforeCompletion();
This method notifies a session Bean instance that a transaction is about to be committed.

Example:

package sb;

import java.rmi.RemoteException;
import javax.ejb.EJBException;
import javax.ejb.EJBObject;
import javax.ejb.SessionBean;
import javax.ejb.SessionContext;
import javax.ejb.SessionSynchronization;
import javax.naming.InitialContext;
import javax.naming.NamingException;

// This is an example of Session Bean, stateful, and synchronized.

public class OpBean implements SessionBean, SessionSynchronization {

    protected int total = 0;        // actual state of the bean
    protected int newtotal = 0;        // value inside Tx, not yet committed.
    protected String clientUser = null;
    protected SessionContext sessionContext = null;

    public void  ejbCreate(String user) {
        total = 0;
        newtotal = total;
        clientUser = user;
    }

    public void ejbActivate() {
        // Nothing to do for this simple example
    }    

    public void ejbPassivate() {
        // Nothing to do for this simple example
    }

    public void ejbRemove() {
        // Nothing to do for this simple example
    }

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

    public void afterBegin() {
        newtotal = total;
    }

    public void beforeCompletion() {
        // Nothing to do for this simple example

        // We can access the bean environment everywhere in the bean,
        // for example here!
        try {
            InitialContext ictx = new InitialContext();
            String value = (String) ictx.lookup("java:comp/env/prop1");
            // value should be the one defined in ejb-jar.xml
        } catch (NamingException e) {
            throw new EJBException(e);
        }
    }

    public void afterCompletion(boolean committed) {
        if (committed) {
            total = newtotal;
        } else {
            newtotal = total;
        }
    }

    public void buy(int s) {
        newtotal = newtotal + s;
        return;
    }

    public int read() {
        return newtotal;
    }
}

Tuning Stateless Session Bean Pool

JOnAS handles a pool for each stateless session bean. The pool can be configured in the JOnAS-specific deployment descriptor with the following tags:

min-pool-size

This optional integer value represents the minimum instances that will be created in the pool when the bean is loaded. This will improve bean instance creation time, at least for the first beans. The default value is 0.

max-cache-size

This optional integer value represents the maximum of instances in memory. The purpose of this value is to keep JOnAS scalable. The policy is the following:
At bean creation time, an instance is taken from the pool of free instances. If the pool is empty, a new instance is always created. When the instance must be released (at the end of a business method), it is pushed into the pool, except if the current number of instances created exceeds the max-cache-size, in which case this instance is dropped. The default value is no limit.

example

  <jonas-ejb-jar>
    <jonas-session>
      <ejb-name>SessSLR</ejb-name>
      <jndi-name>EJB/SessHome</jndi-name>
      <max-cache-size>20</max-cache-size>
      <min-pool-size>10</min-pool-size>
    </jonas-session>
  </jonas-ejb-jar>