EJB.11.6 Container Provider Responsibilities

This section defines the responsibilities of the container provider.

Every client method invocation on an enterprise bean object via the bean's remote and home interface is interposed by the container, and every connection to a resource manager used by an enterprise bean is obtained via the container. This managed execution environment allows the container to affect the enterprise bean's transaction management.

This does not imply that the container must interpose on every resource manager access performed by the enterprise bean. Typically, the container interposes only the resource manager connection factory (e.g., a JDBC API data source) JNDI API lookup by registering the container-specific implementation of the resource manager connection factory object. The resource manager connection factory object allows the container to obtain the XAResource interface as described in the JTA specification and pass it to the transaction manager. After the setup is done, the enterprise bean communicates with the resource manager without going through the container.

EJB.11.6.1 Bean-Managed Transaction Demarcation

This subsection defines the container's responsibilities for the transaction management of enterprise beans with bean-managed transaction demarcation.

Note that only session beans can be used with bean-managed transaction demarcation. A bean provider is not allowed to provide an entity bean with bean-managed transaction demarcation.

The container must manage client invocations to an enterprise bean instance with bean-managed transaction demarcation as follows . When a client invokes a business method via the enterprise bean's remote or home interface, the container suspends any transaction that may be associated with the client request. If there is a transaction associated with the instance (this would happen if the instance started the transaction in some previous business method), the container associates the method execution with this transaction.

The container must make the javax.transaction.UserTransaction interface available to the enterprise bean's business method via the javax.ejb.EJBContext interface and under the environment entry java:comp/UserTransaction . When an instance uses the javax.transaction.UserTransaction interface to demarcate a transaction, the container must enlist all the resource managers used by the instance between the begin() and commit() ”or rollback() ” methods with the transaction. When the instance attempts to commit the transaction, the container is responsible for the global coordination of the transaction commit. ^[2]

^[2] The container typically relies on a transaction manager that is part of the EJB server to perform the two-phase commit across all the enlisted resource managers.

In the case of a stateful session bean, it is possible that the business method that started a transaction completes without committing or rolling back the transaction. In such a case, the container must retain the association between the transaction and the instance across multiple client calls until the instance commits or rolls back the transaction. When the client invokes the next business method, the container must invoke the business method in this transaction context.

If a stateless session bean instance starts a transaction in a business method, it must commit the transaction before the business method returns. The container must detect the case in which a transaction was started, but not completed, in the business method, and handle it as follows:

• Log this as an application error to alert the system administrator.

• Roll back the started transaction.

• Discard the instance of the session bean.

• Throw the java.rmi.RemoteException to the client.

The actions performed by the container for an instance with bean-managed transaction are summarized by Table EJB.11-1. T1 is a transaction associated with a client request, T2 is a transaction that is currently associated with the instance (i.e., a transaction that was started but not completed by a previous business method).

Table EJB.11-1. Container's Actions for Methods of Beans with Bean-Managed Transaction

Client's Transaction	Transaction Currently Associated with Instance	Transaction Associated with the Method
none	none	none
T1	none	none
none	T2	T2
T1	T2	T2

The following items describe each entry in the table:

• If the client request is not associated with a transaction and the instance is not associated with a transaction, the container invokes the instance with an unspecified transaction context.

• If the client is associated with a transaction T1, and the instance is not associated with a transaction, the container suspends the client's transaction association and invokes the method with an unspecified transaction context. The container resumes the client's transaction association (T1) when the method completes.

• If the client request is not associated with a transaction and the instance is already associated with a transaction T2, the container invokes the instance with the transaction that is associated with the instance (T2). This case can never happen for a stateless session bean.

• If the client is associated with a transaction T1, and the instance is already associated with a transaction T2, the container suspends the client's transaction association and invokes the method with the transaction context that is associated with the instance (T2). The container resumes the client's transaction association (T1) when the method completes. This case can never happen for a stateless session bean.

The container must allow the enterprise bean instance to serially perform several transactions in a method.

When an instance attempts to start a transaction using the begin() method of the javax.transaction.UserTransaction interface while the instance has not com-mitted the previous transaction, the container must throw the javax.transaction.NotSupportedException in the begin() method.

The container must throw the java.lang.IllegalStateException if an instance of a bean with bean-managed transaction demarcation attempts to invoke the setRollbackOnly() or getRollbackOnly() method of the javax.ejb.EJBContext interface.

EJB.11.6.2 Container-Managed Transaction Demarcation

The container is responsible for providing the transaction demarcation for the enterprise beans that the bean provider declared with container-managed transaction demarcation. For these enterprise beans, the container must demarcate transactions as specified in the deployment descriptor by the application assembler. (See Chapter EJB.16 for more information about the deployment descriptor.)

The following subsections define the responsibilities of the container for managing the invocation of an enterprise bean business method when the method is invoked via the enterprise bean's home or remote interface. The container's responsibilities depend on the value of the transaction attribute.

EJB.11.6.2.1 NotSupported

The container invokes an enterprise bean method whose transaction attribute is set to NotSupported with an unspecified transaction context.

If a client calls with a transaction context, the container suspends the association of the transaction context with the current thread before invoking the enterprise bean's business method. The container resumes the suspended association when the business method has completed. The suspended transaction context of the client is not passed to the resource managers or other enterprise Bean objects that are invoked from the business method.

If the business method invokes other enterprise beans, the container passes no transaction context with the invocation.

Refer to Section EJB.11.6.3 for more details of how the container can implement this case.

EJB.11.6.2.2 Required

The container must invoke an enterprise bean method whose transaction attribute is set to Required with a valid transaction context.

If a client invokes the enterprise bean's method while the client is associated with a transaction context, the container invokes the enterprise bean's method in the client's transaction context.

If the client invokes the enterprise bean's method while the client is not associated with a transaction context, the container automatically starts a new transaction before delegating a method call to the enterprise bean business method. The container automatically enlists all the resource managers accessed by the business method with the transaction. If the business method invokes other enterprise beans, the container passes the transaction context with the invocation. The container attempts to commit the transaction when the business method has completed. The container performs the commit protocol before the method result is sent to the client.

EJB.11.6.2.3 Supports

The container invokes an enterprise bean method whose transaction attribute is set to Supports as follows.

• If the client calls with a transaction context, the container performs the same steps as described in the Required case.

• If the client calls without a transaction context, the container performs the same steps as described in the NotSupported case.

The Supports transaction attribute must be used with caution. This is because of the different transactional semantics provided by the two possible modes of execution. Only the enterprise beans that will execute correctly in both modes should use the Supports transaction attribute.

EJB.11.6.2.4 RequiresNew

The container must invoke an enterprise bean method whose transaction attribute is set to RequiresNew with a new transaction context.

If the client invokes the enterprise bean's method while the client is not associated with a transaction context, the container automatically starts a new transaction before delegating a method call to the enterprise bean business method. The container automatically enlists all the resource managers accessed by the business method with the transaction. If the business method invokes other enterprise beans, the container passes the transaction context with the invocation. The container attempts to commit the transaction when the business method has completed. The container performs the commit protocol before the method result is sent to the client.

If a client calls with a transaction context, the container suspends the association of the transaction context with the current thread before starting the new transaction and invoking the business method. The container resumes the suspended transaction association after the business method and the new transaction have been completed.

EJB.11.6.2.5 Mandatory

The container must invoke an enterprise bean method whose transaction attribute is set to Mandatory in a client's transaction context. The client is required to call with a transaction context.

• If the client calls with a transaction context, the container performs the same steps as described in the Required case.

• If the client calls without a transaction context, the container throws the javax.transaction.TransactionRequiredException exception.

EJB.11.6.2.6 Never

The container invokes an enterprise bean method whose transaction attribute is set to Never without a transaction context defined by the EJB specification. The client is required to call without a transaction context.

• If the client calls with a transaction context, the container throws the java.rmi.RemoteException exception.

• If the client calls without a transaction context, the container performs the same steps as described in the NotSupported case.

EJB.11.6.2.7 Transaction Attribute Summary

Table EJB.11-2 provides a summary of the transaction context that the container passes to the business method and resource managers used by the business method, as a function of the transaction attribute and the client's transaction context. T1 is a transaction passed with the client request, while T2 is a transaction initiated by the container.

Table EJB.11-2. Transaction Attribute Summary

Transaction Attribute	Client's Transaction	Transaction Associated with Business Method	Transaction Associatedwith Resource Managers
NotSupported	none T1	none none	none none
Required	none T1	T2 T1	T2 T1
Supports	none T1	none T1	none T1
RequiresNew	none T1	T2 T2	T2 T2
Mandatory	none T1	error T1	N/A T1
Never	none T1	none error	none N/A

If the enterprise bean's business method invokes other enterprise beans via their home and remote interfaces, the transaction indicated in the column "Transaction Associated with Business Method" will be passed as part of the client context to the target enterprise bean.

See Section EJB.11.6.3 for how the container handles the "none" case in Table EJB.11-2.

EJB.11.6.2.8 Handling of setRollbackOnly() Method

The container must handle the EJBContext.setRollbackOnly() method invoked from a business method executing with the Required , RequiresNew , 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 , NotSupported , or Never transaction attribute.

EJB.11.6.2.9 Handling of getRollbackOnly() Method

The container must handle the EJBContext.getRollbackOnly() method invoked from a business method executing with the Required , RequiresNew , 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 , NotSupported , or Never transaction attribute.

EJB.11.6.2.10 Handling of getUserTransaction() Method

If an instance of an enterprise bean with container-managed transaction demarcation attempts to invoke the getUserTransaction() method of the EJBContext interface, the container must throw the java.lang.IllegalStateException .

EJB.11.6.2.11 javax.ejb.SessionSynchronization Callbacks

If a session bean class implements the javax.ejb.SessionSynchronization interface, the container must invoke the afterBegin() , beforeCompletion() , and afterCompletion(...) callbacks on the instance as part of the transaction commit protocol.

The container invokes the afterBegin() method on an instance before it invokes the first business method in a transaction.

The container invokes the beforeCompletion() method to give the enterprise bean instance the last chance to cause the transaction to roll back. The instance may cause the transaction to roll back by invoking the EJBContext.setRollbackOnly() method.

The container invokes the afterCompletion(Boolean committed) method after the completion of the transaction commit protocol to notify the enterprise bean instance of the transaction outcome.

EJB.11.6.3 Handling of Methods that Run with "an Unspecified Transaction Context"

The term "an unspecified transaction context" is used in the EJB specification to refer to the cases in which the EJB architecture does not fully define the transaction semantics of an enterprise bean method execution. This includes the following cases:

• The execution of a method of an enterprise bean with container-managed transaction demarcation for which the value of the transaction attribute is NotSupported , Never , or Supports. ^[3]

  ^[3] For the Supports attribute, the handling described in this section applies only to the case when the client calls without a transaction context.

• The execution of the ejbCreate , ejbRemove, ejbPassivate, and ejbActivate methods of a session bean with container-managed transaction demarcation.

The EJB specification does not prescribe how the container should manage the execution of a method with an unspecified transaction context ”the transaction semantics are left to the container implementation. Some techniques for how the container may choose to implement the execution of a method with an unspecified transaction context are as follows (the list is not inclusive of all possible strategies):

• The container may execute the method and access the underlying resource managers without a transaction context.

• The container may treat each call of an instance to a resource manager as a single transaction (e.g., the container may set the auto-commit option on a JDBC API connection).

• The container may merge multiple calls of an instance to a resource manager into a single transaction.

• The container may merge multiple calls of an instance to multiple resource managers into a single transaction.

• If an instance invokes methods on other enterprise beans, and the invoked methods are also designated to run with an unspecified transaction context, the container may merge the resource manager calls from the multiple instances into a single transaction.

• Any combination of the above.

Since the enterprise bean does not know which technique the container implements, the enterprise bean must be written conservatively not to rely on any particular container behavior.

A failure that occurs in the middle of the execution of a method that runs with an unspecified transaction context may leave the resource managers accessed from the method in an unpredictable state. The EJB architecture does not define how the application should recover the resource managers' state after such a failure.