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 especially the Session Beans.

The content of this guide is the following:

  1. Target Audience and Content
  2. Introduction
  3. The Home Interface
  4. The Component Interface
  5. The Enterprise Bean Class

Introduction

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

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 (resp. remote) home interface return local (resp. remote) component interfaces. An EJB component may have both remote and local interfaces, even if typically only one kind of interfaces 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 don't 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, then implementing the SessionSynchronization interface may allow 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:

In the following examples we will 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 kind of component interface could be defined as a local interface (even if it is not a good design to define the same interface both as 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:

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:

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;
    }
}