EJB.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.

EJB.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.

EJB.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.

• 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.

EJB.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.

There is no need for a session bean with bean-managed transaction to rely on the synchronization callbacks 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.

EJB.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.

EJB.6.5.5 Session Bean's ejbCreate(...) Methods

A client creates a session bean instance using one of the create 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 whose signature matches the signature of the create method invoked by the client. The input parameters sent from the client are passed to the ejbCreate method.

Each session bean class must have at least one ejbCreate method. The number and signatures of a session bean's create 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.

EJB.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.

Clients are not allowed to make concurrent calls to a session object. If a client-invoked business method is in progress on an instance when another client-invoked call, from the same or different client, arrives at the same instance, the container must throw the java.rmi.RemoteException to the second client. One implication of this rule is that it is illegal to make a "loopback" call to a session bean instance. An example of a loopback call is when a client calls instance A, instance A calls instance B, and B calls A. The loopback call attempt from B to A would result in the container throwing the java.rmi.RemoteException to B.

EJB.6.5.7 Transaction Context of Session Bean Methods

The implementation of a business method defined in the remote interface is invoked in the scope of a transaction determined by the transaction attribute specified in the deployment descriptor.

A session bean's afterBegin and beforeCompletion methods are always called with the same transaction context as the business methods executed between the afterBegin and beforeCompletion methods.

A session bean's newInstance, setSessionContext , ejbCreate , ejbRemove , ejbPassivate , ejbActivate, and afterCompletion methods are called with an unspecified transaction context. Refer to Section EJB.11.6.3 for how the container executes methods with an unspecified transaction context.

For example, it would be wrong to perform database operations within a session bean's ejbCreate or ejbRemove method and to assume that the operations are part of the client's transaction. The ejbCreate and ejbRemove methods are not controlled by a transaction attribute because handling rollbacks in these methods would greatly complicate the session instance's state diagram.