javaee / jta-spec

Preliminary and non-final documentation for JTA Specification (JSR 907)

JTA specification source repository

This repository contains the source of the JTA specification.

The JTA specification website is at https://javaee.github.io/jta-spec/

jta-spec's Issues

support for container-managed transactions independent of (decoupled from) EJB

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.

new api for setRollbackOnly so that it can take a nested exception

Add a new setRollbackOnly(Exception exception) API method to Transaction, TransactionManager, and UserTransaction where the resultant RollbackException later thrown has the exception parameter as a nested exception that can be inspected by the application.

Contradiction in the javadoc of UserTransaction and @Transactional

There is a contradiction in the JTA spec:

1. On one hand, the UserTransaction javadoc [1] states that if the thread is already associated with a transaction and the Transaction Manager implementation does not support nested transactions, a NotSupportedException will be thrown.

2. On the other hand, the javadoc of the Transactional annotation [2] states that if an attempt is made to call any method of the UserTransaction interface from within the scope of a bean or method annotated with @transactional and a Transactional.TxType other than NOT_SUPPORTED or NEVER, an IllegalStateException must be thrown

So if I have a method annotated with @transactional(TxType.REQUIRED) and within it I call userTransaction.begin(), then what should be the expected exception - IllegalStateException or NotSupportedException ?

[1] http://docs.oracle.com/javaee/7/api/javax/transaction/UserTransaction.html#begin--

[2] http://docs.oracle.com/javaee/7/api/javax/transaction/Transactional.html

Add timeout attribute to the javax.transaction.Transactional annotation

Add additional method to the @transactional annotation to set the TX timeout:

public @interface Transactional

{ (...) long timeout(); TimeUnit unit() default TimeUnit.MILLISECONDS; }

portable way to restore XAResources

[see http://java.net/projects/jta-spec/lists/users/archive/2012-06/message/1 thread for details]

Hi Paul, all,

JTA 1.1 does not mandate, how an XAResource is restored after a system failure for the purpose of
transaction recovery conducted by the transaction manager.

Common suggestions and implementations (e.g. JBoss) use the following strategies:

1. If the XAResource was acquired by a JNDI-named pool, the JNDI name can be stored in the
transaction log file of the transaction manager

2. If the XAResource is Serializable, then the XAResource can be serialized into the transaction log
file of the transaction manager.

Nothing of this is mandated by the JTA spec.

Any transaction manager implementation needs a portable way to restore XAResources.

If 1. alone would be mandatory, this would not work for us, because we don't use a JNDI-based pool
but register our XAResource instances directly with the Transaction.

I suggest to mandate the following behavior for the transaction manager when writing it's log file:

"If the XAResource was acquired via a JNDI named pool or the XAResource is serializable, the
transaction manager might store the JNDI name, or the serialized XAResource in it's transaction
log file. If the XAResource was not acquired via a JNDI named pool and is not serializable, an
exception will be thrown".

Thank you!

Regards,

Christian

Define timing of delist/end in relation to beforeCompletion

See http://java.net/projects/jpa-spec/lists/users/archive/2012-06/message/27 for original detail. In short, define
"
However so far I have been unsuccessful to find out, whether it is portable behavior, for the container to call Transaction.commit() while
there are any XAResource enlisted with this Transaction, where start() had been invoked, but end() has not.

Also I have not found out yet, whether there are scenarios, where the container must not delist the XAResource. (Although not
directly applicable, the control flow diagram p.28/29 in the JTA spec suggests otherwise.)

If both is defined, i.e. container does not delist XAResource it keeps in it's invocation context before calling Transaction.commit() and
Transaction.commit() handles still enlisted resources fine (by calling beforeCompletion() first, calling end() after that, and then prepare+commit)
then we (i.e. the JPA spec) would not have a problem.
"
or allow that the current specification of "beforeCompletion callback methods can access the resources, but that no transactional work can be performed on resources in afterCompletion" is sufficient.

Clarify transaction interactions/restrictions in TX Synchronization callbacks

CDI observers may be registered as JTA synchronization callbacks (same applies to Stateful Session Beans). Nevertheless it is currently not clearly specified which JTA interactions are legal within those callback methods. The current EJB spec contains a few hints, however I believe those clarifications should be part of the JTA spec.

In both cases - CDI observers and Stateful Session Beans - it is quite easy to execute transactional aware code within those callbacks. This includes interaction with an currently active transaction but also suspending/resuming a transaction in order to implement requires new semantics.

errata - incorrect @since tag value "JTA 1.3" rather than "JTA 1.2"

The new classes in JTA 1.2 have a typo in their @SInCE tag that reads "JTA 1.3" rather than "JTA 1.2". This has been fixed in svn but must be addressed in an MR.

How do I maintain Transaction log by Eclipse link 2.0

How do I maintain Transaction log by Eclipse link 2.0

support explicit ordering of commits for XAResources enlisted in a transaction

As reported here: http://java.net/jira/browse/JMS_SPEC-28 (and originally here: http://java.net/jira/browse/JAVAEE_SPEC-1) :

Currently there is no standard way how to enforce the ordering of the XAResource commits for the transaction. There are workarounds such as http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/5/html/Transactions_Development_Guide/chap-Transactions_JTA_Programmers_Guide-Test.html#form-Transactions_JTA_Programmers_Guide-The_XAResource_Interface-Extended_XAResource_control for example, but I think that a properly specified standard API would be much better.

specify whether XAResource.end call as a result of delistResource call must be conducted eagerly/immediately

While most vendors (MQSeries, Tibco, etc.) do not have this requirement, it appears that some (such as HornetQ) require that end be called eagerly as a result of delistResource being called. Whlle section 4.2 of the JTA spec sites this as an example case/implementation it also explains that “This session provides a brief walkthrough of how an application server may handle a connection request from the application. The figure that follows illustrates the usage of JTA. The steps shown are for illustrative purposes, they are not prescriptive:”

Further the JCA 1.7 section 7.6.5 states “
4. The application server dissociates the XAResource instance, corresponding to the ManagedConnection instance, from the transaction manager using the method Transaction.delistResource.
5. The transaction manager calls XAResource.end(Xid,flag) to inform the resource manager that any further operations on the ManagedConnection instance are no longer associated with the transaction, represented by the Xid passed in XAResource.end call. This method invocation dissociates the transaction from the resource manager instance.
6. After the JTA transaction completes, the application server initiates a cleanup of the physical connection instance by calling ManagedConnection.cleanup method. After calling the method cleanup on the ManagedConnection instance, the application server returns the ManagedConnection instance to the connection pool.
"
and/but the JTA spec states only that “A container only needs to call delistResource to explicitly disassociate a resource from a transaction and it is not a mandatory container requirement to do so as a precondition to transaction completion. A transaction manager is, however, required to implicitly ensure the association of any associated XAResource is ended, via the appropriate XAResource.end call, immediately prior to completion; that is before prepare (or commit/rollback in the onephase-optimized case). “

Therefore, it would be good to specification/clarify this in the JTA (and perhaps JCA as well) specification(s) on way or another. We could additionally perhaps come up with some option for the call to delistResource to eagerly result in the XAResource.end call by the TM for the TMSUCCESS and TMFAIL flag cases.

elaborate on ordering semantics for Synchronization calls in a distributed transaction

This is being opened to track the topic and whether it warrants elaborating in the spec.

Email exchange between Paul Parkinson and Ian Robinson...

Paul:

"
Something I've always thought of, especially since the TransactionSynchronizationRegistry was introduced, is whether we should mention anything in the spec about the ordering semantics for Synchronization calls in a transaction that is distributed across multiple transaction managers/processes.

As far as I can tell all transaction managers in existence issue Synchronization.beforeCompletion calls locally just before the prepare calls on each node of a transaction and there is no "0/beforeCompletion phase" whereby all Synchronization.beforeCompletion calls are made down the entire transaction/process tree before starting the prepare calls down the entire transaction/process tree.

This is no surprise as the performance cost would be significant, however, the spec states "The Synchronization.beforeCompletion method is called prior to the start of the two-phase transaction commit process" and the javadoc for registerInterposedSynchronization) states "beforeCompletion will be called after all SessionSynchronization beforeCompletion callbacks and callbacks registered directly with the Transaction, but before the 2-phase commit process starts"

So one might argue that it is a violation to call prepare from/on one node of a transaction when Synchronization.beforeCompletion calls have not been made on another node involved in the same transaction.

Any thoughts?
"

Ian:
"
This is right - as you say, the ordering of Synchronizations and XAResources are always localized within the scope of a JVM which may be one branch of a distributed transaction. In all the implementations I know, only the first and second phase are strictly distributed across the whole tree with the volatile (Synchronization) work always ordered wrt 2PC only within the local JVM. OTS itself supports distributing before/afterCompletion but I don't know anyone who pays the performance price to do that.
Its a similar consideration for JCA connection sharing - different components that access the same resource provider in the same global transaction should share a Connection but that is only true if the application components are deployed to the same AppServer (JVM).
The Synchronization ordering is safe so long as you DON'T share connections or join (tightly couple) transaction branches between servers (JVMs) in a global transaction. If you did that then you would need to worry about work-after-prepare in the downstream nodes.

So I don't think we have anything to worry about here unless you think this needs clarification. I certainly wouldn't want to require any change in behaviour.
"

specify XAResource(s) transaction timeout value be set to the value of the encompassing JTA transaction's timeout value by default for portability.

specify XAResource(s) transaction timeout value be set to the value of the encompassing JTA transaction's timeout value by default for portability.

TransactionScoped annotation for CDI bean scope/lifecycle

As taken from http://issues.jboss.org/browse/CDI-121 :

Add TransctionalScoped as a standard scope to define beans whose lifecycle is the same as a given transaction.
This scope should start automatically when a transaction starts (but lazily when actually needed).

More details forthcoming in the next couple days...