Sun Microsystems Inc

Protocol between a session bean instance and its containerEnterprise JavaBeans 2.0, Public Draft Session Bean Component Contract

6.4.2 The effect of transaction rollback on conversational state

A session object’s conversational state is not transactional. It is not automatically rolled back to its initial state if the transaction in which the object has participated rolls back.

If a rollback could result in an inconsistency between a session object’s conversational state and the state of the underlying database, the bean developer (or the application development tools used by the developer) must use the afterCompletion notification to manually reset its state.

6.5 Protocol between a session bean instance and its container

Containers themselves make no actual service demands on the session bean instances. The container makes calls on a bean instance to provide it with access to container services and to deliver notifications issued by the container.

6.5.1 The required SessionBean interface

All session beans must implement the SessionBean interface.

The bean’s container calls the setSessionContext method to associate a session bean instance with its context maintained by the container. Typically, a session bean instance retains its session context as part of its conversational state.

The ejbRemove notification signals that the instance is in the process of being removed by the container. In the ejbRemove method, the instance typically releases the same resources that it releases in the ejbPassivate method.

The ejbPassivate notification signals the intent of the container to passivate the instance. The ejbActivate notification signals the instance it has just been reactivated. Because containers automatically maintain the conversational state of a session bean instance when it is passivated, most session beans can ignore these notifications. Their purpose is to allow session beans to maintain those open resources that need to be closed prior to an instance’s passivation and then reopened during an instance’s activation.

6.5.2 The SessionContext interface

A container provides the session bean instances with a SessionContext, which gives the session bean instance access to the instance’s context maintained by the container. The SessionContext interface has the following methods:

•The getEJBObject method returns the session bean’s remote interface.

•The getEJBHome method returns the session bean’s home interface.

Sun Microsystems Inc.

•The getCallerPrincipal method returns the java.security.Principal that identifies the invoker of the bean instance’s EJB object.

•The isCallerInRole method tests if the session bean instance’s caller has a particular role.

•The setRollbackOnly method allows the instance to mark the current transaction such that the only outcome of the transaction is a rollback. Only instances of a session bean with container-managed transaction demarcation can use this method.

•The getRollbackOnly method allows the instance to test if the current transaction has been marked for rollback. Only instances of a session bean with container-managed transaction demarcation can use this method.

•The getUserTransaction method returns the javax.transaction.UserTransaction interface. The instance can use this interface to demarcate transactions and to obtain transaction status. Only instances of a session bean with bean-managed transaction demarcation can use this method.

6.5.3 The optional SessionSynchronization interface

A session bean class can optionally implement the javax.ejb.SessionSynchronization interface. This interface provides the session bean instances with transaction synchronization notifications. The instances can use these notifications, for example, to manage database data they may cache within transactions.

The afterBegin notification signals a session bean instance that a new transaction has begun. The container invokes this method before the first business method within a transaction (which is not necessarily at the beginning of the transaction). The afterBegin notification is invoked with the transaction context. The instance may do any database work it requires within the scope of the transaction.

The beforeCompletion notification is issued when a session bean instance’s client has completed work on its current transaction but prior to committing the resource managers used by the instance. At this time, the instance should write out any database updates it has cached. The instance can cause the transaction to roll back by invoking the setRollbackOnly method on its session context.

The afterCompletion notification signals that the current transaction has completed. A completion status of true indicates that the transaction has committed; a status of false indicates that a rollback has occurred. Since a session bean instance’s conversational state is not transactional, it may need to manually reset its state if a rollback occurred.

All container providers must support SessionSynchronization. It is optional only for the bean implementor. If a bean class implements SessionSynchronization, the container must invoke the afterBegin, beforeCompletion and afterCompletion notifications as required by the specification.

Only a stateful Session bean with container-managed transaction demarcation may implement the SessionSynchronization interface. A stateless Session bean must not implement the SessionSynchronization interface.

Sun Microsystems Inc

Protocol between a session bean instance and its containerEnterprise JavaBeans 2.0, Public Draft Session Bean Component Contract

There is no need for a Session bean with bean-managed transaction to rely on the synchronization call backs because the bean is in control of the commit—the bean knows when the transaction is about to be committed and it knows the outcome of the transaction commit.

6.5.4 Business method delegation

The session bean’s remote interface defines the business methods callable by a client. The session bean’s remote interface is implemented by the session EJBObject class generated by the container tools. The session EJBObject class delegates an invocation of a business method to the matching business method that is implemented in the session bean class.

6.5.5 Session bean’s ejbCreate<METHOD>(...) methods

A client creates a session bean instance using one of the create<METHOD> methods defined in the session bean’s home interface. The session bean’s home interface is provided by the bean developer; its implementation is generated by the deployment tools provided by the container provider.

The container creates an instance of a session bean in three steps. First, the container calls the bean class’ newInstance method to create a new session bean instance. Second, the container calls the setSessionContext method to pass the context object to the instance. Third, the container calls the instance’s ejbCreate<METHOD> method whose signature matches the signature of the create<METHOD> method invoked by the client. The input parameters sent from the client are passed to the ejbCreate<METHOD> method.

Each session bean class must have at least one ejbCreate<METHOD> method. The number and signatures of a session bean’s create<METHOD> methods are specific to each session bean class.

Since a session bean represents a specific, private conversation between the bean and its client, its create parameters typically contain the information the client uses to customize the bean instance for its use.

6.5.6 Serializing session bean methods

A container serializes calls to each session bean instance. Most containers will support many instances of a session bean executing concurrently; however, each instance sees only a serialized sequence of method calls. Therefore, a session bean does not have to be coded as reentrant.

The container must serialize all the container-invoked callbacks (that is, the methods ejbPassivate, beforeCompletion, and so on), and it must serialize these callbacks with the client-invoked business method calls.