Sun Microsystems Inc.

an unspecified transaction context. The container resumes the client’s transaction association (T1) when the method completes. This case can never happen for a Message-driven Bean.

•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 or a Mes- sage-driven 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 or a Message-driven 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 committed 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.

16.7.2 Container-managed transaction demarcation for Session and Entity Beans

The Container is responsible for providing the transaction demarcation for the session and entity 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 21 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.

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

Sun Microsystems Inc

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

Refer to Subsection 16.7.5 for more details of how the Container can implement this case.

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

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

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

Sun Microsystems Inc.

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.

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

16.7.2.6Never

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.

16.7.2.7Transaction attribute summary

The following table 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.

Sun Microsystems Inc

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 Subsection 16.7.5 for how the Container handles the “none” case in Table 11.

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