![[Note]](images.admon/note.gif) | |
| |
javax.ejb.SessionSynchronization Interface
A stateful session bean with container-managed transaction (CMT) demarcation can optionally implement the javax.ejb.SessionSynchronization interface.
The SessionSynchronization interface is defined as follows:
package javax.ejb;
public interface javax.ejb.SessionSynchronization {
void afterBegin() throws RemoteException;
void beforeCompletion() throws RemoteException;
void afterCompletion(boolean committed) throws RemoteException;
}
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 - e.g., if the Java Persistence API is not used.
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.
Begin transaction sequence:
Commit transaction sequence:
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 (CMT) 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 (BMT) demarcation 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.
javax.ejb.EJBContext.setRollbackOnly Method
An enterprise bean with container-managed transaction (CMT) demarcation can use the setRollbackOnly method of its EJBContext object to mark the transaction such that the transaction can NEVER COMMIT. Typically, an enterprise bean marks a transaction for rollback to protect data integrity before throwing an application exception, if the application exception class has not been specified to automatically cause the container to rollback the transaction.
For example, an AccountTransfer bean which debits one account and credits another account could mark a transaction for rollback if it successfully performs the debit operation, but encounters a failure during the credit operation.
The container must handle the EJBContext.setRollbackOnly method invoked from a business method executing with the REQUIRED, REQUIRES_NEW, or MANDATORY transaction attribute as follows:
The container must ensure that the transaction will never commit. Typically, the container instructs the transaction manager to mark the transaction for rollback.
If the container initiated the transaction immediately before dispatching the business method to the instance (as opposed to the transaction being inherited from the caller), the container must note that the instance has invoked the setRollbackOnly method. When the business method invocation completes, the container must roll back rather than commit the transaction. If the business method has returned normally or with an application exception, the container must pass the method result or the application exception to the client after the container performed the rollback.
The container MUST throw the java.lang.IllegalStateException if the EJBContext.setRollbackOnly method is invoked from a business method executing with the SUPPORTS, NOT_SUPPORTED, or NEVER transaction attribute.
javax.ejb.EJBContext.getRollbackOnly method
An enterprise bean with container-managed transaction demarcation can use the getRollbackOnly method of its EJBContext object to test if the current transaction has been marked for rollback. The transaction might have been marked for rollback by the enterprise bean itself, by other enterprise beans, or by other components (outside of the EJB specification scope) of the transaction processing infrastructure.
The container must handle the EJBContext.getRollbackOnly method invoked from a business method executing with the REQUIRED, REQUIRES_NEW, or MANDATORY transaction attribute.
The container MUST throw the java.lang.IllegalStateException if the EJBContext.getRollbackOnly method is invoked from a business method executing with the SUPPORTS, NOT_SUPPORTED, or NEVER transaction attribute.
