# 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:

- 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, which 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, containing the bean properties that may 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 (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:

- public void setSessionContext(SessionContext ic);

  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 don't 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 away the instance's state.

- public void ejbActivate();

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