[JTA_SPEC-5] support for container-managed transactions independent of (decoupled from) EJB Created: 23/Aug/12  Updated: 23/Aug/13  Resolved: 23/Aug/13

Status: Closed
Project: jta-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: New Feature Priority: Major
Reporter: paul_parkinson Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

As part of better aligning managed bean technology across the
platform, one of the improvements we've targeted for this release
is the extension of "container-managed" transactions (CMT) beyond EJB.

CMT is one of the original ease-of-use facilities of EJB. It entails
the specification of declarative transaction attributes on enterprise
bean classes or methods. The container intercepts the corresponding
method calls and interposes the necessary operations to initiate,
suspend, or complete JTA transactions.

In order to allow CMT-like functionality to be more broadly supported,
we propose to standardize on CDI interceptors to implement transactional
interpositioning on managed bean methods.

More concretely, the proposal is the following:

We propose to standardize on an annotation + element values that
capture the semantics of the current EJB transaction attributes
(Required, RequiresNew, Mandatory, Supports, NotSupported, Never).

This annotation and standardized values would be added to the
javax.transaction package.

For example, this might look as follows:

@Inherited
@InterceptorBinding
@Target(

{TYPE,METHOD}

)
@Retention(RUNTIME)
public @interface Transactional {
TxType value() default TxType.REQUIRED
}

public enum TxType {
REQUIRED,
REQUIRES_NEW,
MANDATORY,
SUPPORTS,
NOT_SUPPORTED,
NEVER
}

The JTA specification would also define the semantics of the
corresponding interceptor classes. (Note that the classes themselves
would not be defined, but left to the JTA implementation.)

These transactional interceptors would then be applied using the
standard CDI protocols. They would be applicable to all CDI managed
beans as well as to classes defined as managed beans by the Java EE
specification such as servlets, JAX-RS resource classes, and JAX-WS
service endpoints.

There are a few open issues here that require consideration, e.g.:

(1) Whether the "value" attribute of the "Transactional" annotation
should be binding or @NonBinding. Note that this decision affects
the number of interceptor classes that would need to be defined.

(2) Interceptor ordering. This is currently an open topic in the CDI
expert group. Presumably it would be desirable for "system-level"
interceptors such as transactional interceptors to be executed before
user-defined "application-level" interceptors, but there needs to be
a mechanism to allow such orderings to be specified in a flexible way.

We would like to get feedback on this proposed approach and the
related issues from the group. Other specleads should feel free to
forward this message to their expert groups for further discussion, if
relevant.

The proposal for exception handling is as follows:

By default, "application exceptions" (i.e., checked exceptions /
instances of Exception and its subclasses other than RuntimeException)
do not result in the transactional interceptor marking the transaction
for rollback, and instances of RuntimeException and its subclasses do.

This default behavior can be overridden via the Transactional
annotation. More specifically, we propose adding to the
Transactional annotation an element to specify additional
exceptions that result in the interceptor marking the
transaction for rollback and an element to specify exceptions
that do not cause the interceptor to mark the transaction for rollback.

For example:

@Inherited
@InterceptorBinding
@Target(

{TYPE, METHOD}

)
@Retention(RUNTIME)
public @interface Transactional {
TxType value() default TxType.REQUIRED;
Class[] rollbackOn() default {};
Class[] dontRollbackOn() default {};
}

When a class is specified for either of these elements, the
designated behavior applies to subclasses of that class as well.
If both elements are specified, dontRollbackOn takes precedence.

Examples:

@Transactional(rollbackOn=

{Exception.class}

)

will override behavior for application exceptions, causing the
transaction to be marked for rollback for all application exceptions.

@Transactional(dontRollbackOn=

{IllegalStateException}

)

will prevent transactions from being marked for rollback by the
interceptor when an IllegalStateException or any of its subclasses
reaches the interceptor.

@Transactional(
rollbackOn=

{SQLException.class}

,
dontRollbackOn=

{SQLWarning.class}

)

will cause the transaction to be marked for rollback for all
runtime exceptions and all SQLException types except for SQLWarning.

Note that we are assuming that there is no special, built-in knowledge
about EJB application exceptions (i.e., runtime exceptions annotated
with @ApplicationException). As far as the interceptor is concerned,
these would be treated just as any other runtime exceptions unless
otherwise specified.



 Comments   
Comment by frenchc [ 30/Aug/12 ]

"We propose to standardize on an annotation + element values that capture the semantics of the current EJB transaction attributes (Required, RequiresNew, Mandatory, Supports, NotSupported, Never)."

This topic is also important for CDI IN_PROGRESS observers (which are similar to synchronous EJB RPC calls). See https://issues.jboss.org/browse/CDI-213

Comment by paul_parkinson [ 07/Dec/12 ]

Hi,

Below is a rough first run of the JTA 1.2 section 3.7 Transactional Annotation, http://java.net/jira/browse/JTA_SPEC-5

Thank you for any feedback as we need to close this down in the next couple weeks.

Regards,
Paul

3.7 Transactional Annotation

The javax.transaction.Transactional annotation provides the application the ability to control transaction boundaries on CDI managed beans, as well as classes defined as managed beans by the Java EE
specification such as servlets, JAX-RS resource classes, and JAX-WS service endpoints, declaratively. This provides the semantics of EJB transaction attributes in CDI without dependencies such as RMI. This support is implemented via an implementation of a CDI interceptor that conducts the necessary suspending, resuming, etc. [*todo specify the number used for the transactional interceptor, so that others can choose to order their interceptors before or after the transactional interceptor; coordinate with CDI for this]

By default checked exceptions do not result in the transactional interceptor marking the transaction for rollback and instances of RuntimeException and its subclasses do. This default behavior can be overridden by specifying which exceptions result in the interceptor marking the transaction for rollback. The rollbackOn element can be set to indicate which exceptions should cause the interceptor to mark the transaction for rollback. Conversely, the dontRollbackOn element can be set to indicate which exceptions should do not cause the interceptor to mark the transaction for rollback. When a class is specified for either of these elements, the designated behavior applies to subclasses of that class as well. If both elements are specified, dontRollbackOn takes precedence.

The following are some example usages of rollbackOn and dontRollbackOn elements.

  • The following will override behavior for application exceptions, causing the transaction to be marked for rollback for all application exceptions.
    @Transactional(rollbackOn= {Exception.class}

    )

  • The following will prevent transactions from being marked for rollback by the interceptor when an IllegalStateException or any of its subclasses reaches the interceptor.
    @Transactional(dontRollbackOn= {IllegalStateException.class}

    )

  • The following will cause the transaction to be marked for rollback for all runtime exceptions and all SQLException types except for SQLWarning.
    @Transactional(
    rollbackOn= {SQLException.class}

    ,
    dontRollbackOn=

    {SQLWarning.class}

    )

EJB application exceptions (i.e., runtime exceptions annotated with @ApplicationException) are treated just as any other runtime exceptions unless otherwise specified.

When Transactional annotated managed beans are used in conjunction with EJB container managed transactions the EJB container behavior is applied before the bean is called. When the bean is called the CDI behavior is applied before calling the bean's methods. It is best practice to avoid such use of Transactional annotations in conjunction with EJB container managed transactions in order to avoid possible confusion.

“Java Transaction API Reference” on page 30 has a full description of this annotation

[...]

/**

  • Annotation used by applications to control transaction boundaries on CDI managed beans, as well as
  • classes defined as managed beans by the Java EE specification such as servlets, JAX-RS resource classes, and JAX-WS
  • service endpoints, declaratively. This provides the semantics of EJB transaction attributes in CDI without
  • dependencies such as RMI. This support is implemented via an implementation of a CDI interceptor that conducts the
  • necessary suspending, resuming, etc. [*todo specify the number used for the transactional interceptor, so that others
  • can choose to order their interceptors before or after the transactional interceptor; coordinate with CDI for this]
  • [*open issue as to whether the "value" attribute of the "Transactional" annotation should be binding or not]
    *
  • By default checked exceptions do not result in the transactional interceptor marking the transaction for rollback
  • and instances of RuntimeException and its subclasses do. This default behavior can be overridden by specifying
  • which exceptions result in the interceptor marking the transaction for rollback. The rollbackOn element can be set
  • to indicate which exceptions should cause the interceptor to mark the transaction for rollback. Conversely, the
  • dontRollbackOn element can be set to indicate which exceptions should do not cause the interceptor to mark the
  • transaction for rollback. When a class is specified for either of these elements, the designated behavior applies
  • to subclasses of that class as well. If both elements are specified, dontRollbackOn takes precedence.
    *
  • EJB application exceptions (i.e., runtime exceptions annotated with @ApplicationException) are treated just as any
  • other runtime exceptions unless otherwise specified.
    *
  • When Transactional annotated managed beans are used in conjunction with EJB container managed transactions the EJB
  • container behavior is applied before the bean is called. When the bean is called the CDI behavior is applied before
  • calling the bean's methods. It is best practice to avoid such use of Transactional annotations in conjunction with
  • EJB container managed transactions in order to avoid possible confusion.
    *
    *
  • @since JTA1.2
    */
    @Inherited
    @InterceptorBinding
    @Target( {ElementType.TYPE, ElementType.METHOD}

    )
    @Retention(value = RetentionPolicy.RUNTIME)
    public @interface Transactional {
    TxType value() default TxType.REQUIRED;

public enum TxType

{REQUIRED, REQUIRES_NEW, MANDATORY, SUPPORTS, NOT_SUPPORTED, NEVER}

Class[] rollbackOn() default {};

Class[] dontRollbackOn() default {};

}

Comment by irobins [ 18/Jan/13 ]

I continue to believe we're making life too hard for container providers for the combined CDI and EJB use case that is a "best practice to avoid" and I think we could spend a lot of time arguing over the behavioural details of edge cases.

The current proposed wording in the draft is:

"When Transactional annotated managed beans are used in conjunction with EJB container managed
transactions the EJB container behavior is applied before the bean is called. When the bean is called
the CDI behavior is applied before calling the bean's methods. It is best practice to avoid such use of
Transactional annotations in conjunction with EJB container managed transactions in order to avoid
possible confusion."

I agree we don't want to complicate the deployment process by requiring it to detect and prevent the combination of CMT and @Transactional annotations. But I also don't want to complicate our implementation or end up with an implementation that is in conflict with any compliance tests. So part of this discussion needs to be over the definition of the specific compliance tests and allowed outcomes and which spec (JTA, EJB or CDI) they'll be part of. By the way, I'd really like to see a JTA TCK for JTA compliance rather than it being all entangled in the Java CTS.

In the spirit of not requiring the deployment process to detect and prevent, could I suggest something like:

"When Transactional annotated managed beans are used in conjunction with EJB container managed transactions the EJB container behavior is unspecified and not portable. Valid container implementations include, but are not limited to:
the bean may fail to deploy
the Transactional annotation may be ignored
the EJB container behavior is applied before the bean is called. When the bean is called the CDI behavior is applied before calling the bean's methods.
It is best practice to avoid such use of Transactional annotations in conjunction with EJB container managed transactions in order to avoid possible confusion. and lack of portability."

Let me continue the discussion over why I don't like the option to require support of both annotations on the same bean.

I enumerated some of the confusing scenarios below although I imagine there are plenty more. Going through just these:
e.g. #1 : @TransactionAttribute(MANDATORY) + @Transactional(NEVER)

I believe the end result MUST BE:
Throw javax.transaction.TransactionRolledbackException to remote client; throw javax.ejb.TransactionRolledbackLocalException to local client.

Anything else would require a change to the EJB spec.
Paul said:
"I may send a separate dedicated email on this topic but we do need to also decide what exception is to be thrown when a bean with TxType Never is called from within a transactional context as currently it throws an EJBException. Eg, should we throw InvalidTransactionException?"

My comment to this is that I think your current implementation is correct and consistent with the EJB spec. But as you say, its awkward given the new proposed JTA text:
"If a managed been annotated with a TxType of NEVER is called from within a transaction context, an InvalidTransactionException is thrown."

e.g. #1a : @Transactional(NEVER) on a CMT EJB with no TransactionAttribute

This is even more confusing since default EJB CMT is REQUIRED and the result therefore needs to be the same as the first case above.

e.g. #2 Exception handling

For an ISE how would I reconcile:

@TransactionAttribute(REQUIRES_NEW) + @Transactional(REQUIRED, dontRollbackOn=

{IllegalStateException.class}

)
The EJB container is required to rollback the transaction in the case of an ISE despite the CDI annotation. So the outcome must be a rollback on ISE despite the explicit dontRollbackOn

More evidence for allowing unspecified behaviour.

e.g #3. @TransactionAttribute(MANDATORY) + @Transactional(REQUIRES_NEW)

In the case of any system exception, the EJB container exception processing behaviour depends on whether the EJB runs in the caller's transaction or not. A MANDATORY EJB is always considered to be running in the caller's transaction and in the case of the bean throwing a system exception (EJB 3.1 Table 15) must mark the caller's transaction rollback_only and throw EJBTransactionRolledbackException. This would also be the case if you had a distinct client -> EJB (Mandatory) -> Bean (RequiresNew)

On the other hand you could interpret this as the case where the bean is not running in the client's context in which case the EJB container should throw EJBException and not mark the caller's transaction rollback_only. I think this would be an incorrect interpretation but given there is only one bean involved I think it is debatable.

e.g #4 Client has no context. EJB specifies: @TransactionAttribute(REQUIRES) + @Transactional(REQUIRES_NEW)
I'd expect some implementations may start a single transaction and some do a start, suspend, start second.
This isn't an issue so long as neither approach is prevented.

Also - not related to EJB: Mixing @Transactional with direct access to UserTransaction
Just as the EJB spec prevents access to UserTransaction inside a CMT bean, we need either the JTA spec to prevent access to UserTrasnaction within a managed bean that uses @Transactional otherwise the interceptor cannot efficiently provide transactional integrity. whose snaction

Regards...Ian

Comment by irobins [ 16/Feb/13 ]

Two further concerns on sections 3.7 and 3.8 for this new feature:
#2
In Paul's mail he said:

  • perhaps explicitly mention that while UserTransaction should not be used inside a Transactional CMT, unlike EJB, use will not actually be restricted

I'd assumed the opposite so I agree we need to explicitly document something. I think it needs to be an exception in the same way it is for EJB CMT. If the container is managing the transaction then the management is compromised by having the bean able to manipulate it.

#3
Section 3.8 says:
"The javax.transaction.cdi.TransactionScoped annotation provides the ability to
specify a standard scope to define beans whose lifecycle are scoped to the currently
active JTA transaction. The transaction scope is active when the return from a call to
UserTransaction.getStatus or TransactionManager.getStatus is one ofthe following
states:
Status.STATUS_ACTIVE
Status.STATUS_MARKED_ROLLBACK
Status.STATUS_PREPARED
Status.STATUS_UNKNOWN
Status.STATUS_PREPARING
Status.STATUS_COMMITTING
Status.STATUS_ROLLING_BACK
...
A javax.enterprise.context.ContextNotActiveException must be thrown if an object
with this annotation is used when the transaction context is not active.The object with
this annotation is associated with the JTA transaction where it is first used and this
association is retained through any transaction suspend or resume calls as well as
any beforeCompletion Synchronization calls until the transaction is completed."

I interpret this as requiring a ContextNotActiveException to be thrown if the TransactionScoped object is used while the transaction with which it is associated is suspended from the thread on which the object is used. Is that correct?

But then the psuedocode example says:
Transaction transaction = transactionManager.suspend(); //tx1 suspended
//assert testTxAssociationChangeBean still associated with tx1 and
// that no transaction scope is active.
How? Shouldn't I get ContextNotActiveException if I try to use testTxAssociationChangeBean?

Regards...Ian

Comment by paul_parkinson [ 23/Aug/13 ]

speced in JTA 1.2 and implemented in RI

Generated at Tue Aug 30 18:45:27 UTC 2016 using JIRA 6.2.3#6260-sha1:63ef1d6dac3f4f4d7db4c1effd405ba38ccdc558.