Sun Microsystems Inc.

Clients are not allowed to make concurrent calls to a stateful 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 of a stateful session bean class, 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. This restriction does not apply to a stateless session bean because the container routes each request to a different instance of the session bean class.

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 Subsection 16.7.5 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.

6.6 STATEFUL Session Bean State Diagram

The following figure illustrates the life cycle of a STATEFUL session bean instance.

Sun Microsystems Inc

instance throws system does not exception from any method

exist

create<METHOD>(args)

The following steps describe the life cycle of a STATEFUL session bean instance:

•A session bean instance’s life starts when a client invokes a create<METHOD>(...) method on the session bean’s home interface. This causes the container to invoke newIn-

Sun Microsystems Inc.

stance() on the session bean class to create a new session bean instance. Next, the container calls setSessionContext() and ejbCreate<METHOD>(...) on the instance and returns the remote reference of the session object to the client. The instance is now in the method ready state.

•The session bean instance is now ready for client’s business methods. Based on the transaction attributes in the session bean’s deployment descriptor and the transaction context associated with the client’s invocation, a business method is executed either in a transaction context or with an unspecified transaction context (shown as tx method and non-tx method in the diagram). See Chapter 16 for how the container deals with transactions.

•A non-transactional method is executed while the instance is in the method ready state.

•An invocation of a transactional method causes the instance to be included in a transaction. When the session bean instance is included in a transaction, the container issues the afterBegin() method on it. The afterBegin is delivered to the instance before any business method is executed as part of the transaction. The instance becomes associated with the transaction and will remain associated with the transaction until the transaction completes.

•Session bean methods invoked by the client in this transaction can now be delegated to the bean instance. An error occurs if a client attempts to invoke a method on the session object and the deployment descriptor for the method requires that the container invoke the method in a different transaction context than the one with which the instance is currently associated or in an unspecified transaction context.

•If a transaction commit has been requested, the transaction service notifies the container of the commit request before actually committing the transaction, and the container issues a beforeCompletion on the instance. When beforeCompletion is invoked, the instance should write any cached updates to the database. If a transaction rollback had been requested instead, the rollback status is reached without the container issuing a beforeCompletion. The container may not call the beforeCompletion method if the transaction has been marked for rollback (nor does the instance write any cached updates to the database).

•The transaction service then attempts to commit the transaction, resulting in either a commit or rollback.

•When the transaction completes, the container issues afterCompletion on the instance, specifying the status of the completion (either commit or rollback). If a rollback occurred, the bean instance may need to reset its conversational state back to the value it had at the beginning of the transaction.

•The container’s caching algorithm may decide that the bean instance should be evicted from memory (this could be done at the end of each method, or by using an LRU policy). The container issues ejbPassivate on the instance. After this completes, the container saves the instance’s state to secondary storage. A session bean can be passivated only between transactions, and not within a transaction.

•While the instance is in the passivated state, the Container may remove the session object after the expiration of a timeout specified by the deployer. All object references and handles for the

Sun Microsystems Inc

session object become invalid. If a client attempts to invoke the session object, the Container will throw the java.rmi.NoSuchObjectException to the client.

•If a client invokes a session object whose session bean instance has been passivated, the container will activate the instance. To activate the session bean instance, the container restores the instance’s state from secondary storage and issues ejbActivate on it.

•The session bean instance is again ready for client methods.

•When the client calls remove on the home or remote interface to remove the session object, the container issues ejbRemove() on the bean instance. This ends the life of the session bean instance and the associated session object. Any subsequent attempt by its client to invoke the session object causes the java.rmi.NoSuchObjectException to be thrown. (This exception is a subclass of java.rmi.RemoteException). The ejbRemove() method cannot be called when the instance is participating in a transaction. An attempt to remove a session object while the object is in a transaction will cause the container to throw the javax.ejb.RemoveException to the client. Note that a container can also invoke the ejbRemove() method on the instance without a client call to remove the session object after the lifetime of the EJB object has expired.

Notes:

1.The Container must call the afterBegin, beforeCompletion, and afterCompletion methods if the session bean class implements, directly or indirectly, the SessionSynchronization interface. The Container does not call these methods if the session bean class does not implement the SessionSynchronization interface.

6.6.1 Operations allowed in the methods of a stateful session bean class

Table 2 defines the methods of a stateful session bean class from which the session bean instances can access the methods of the javax.ejb.SessionContext interface, the java:comp/env environment naming context, resource managers, and other enterprise beans.

If a session bean instance attempts to invoke a method of the SessionContext interface, and that access is not allowed in Table 2, the Container must throw the java.lang.IllegalStateException.

If a session bean instance attempts to access a resource manager or an enterprise bean, and that access is not allowed in Table 2, the behavior is undefined by the EJB architecture.

Sun Microsystems Inc.

•The ejbCreate<METHOD>, ejbRemove, ejbPassivate, and ejbActivate methods of a session bean with container-managed transaction demarcation execute with an unspecified transaction context. Refer to Subsection 16.7.5 for how the Container executes methods with an unspecified transaction context.