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 DemarcationThis 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]
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:
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
The following items describe each entry in the table:
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 DemarcationThe 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 NotSupportedThe 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 RequiredThe 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 SupportsThe container invokes an enterprise bean method whose transaction attribute is set to Supports as follows.
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 RequiresNewThe 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 MandatoryThe 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.
EJB.11.6.2.6 NeverThe 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.
EJB.11.6.2.7 Transaction Attribute SummaryTable 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
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() MethodThe 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 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() MethodThe 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() MethodIf 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 CallbacksIf 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 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):
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. |