PlatformTransactionManager implementation
for JTA, delegating to a backend JTA provider. This is typically used to delegate
to a Java EE server's transaction coordinator, but may also be configured with a
local JTA provider which is embedded within the application.

This transaction manager is appropriate for handling distributed transactions,
i.e. transactions that span multiple resources, and for controlling transactions on
application server resources (e.g. JDBC DataSources available in JNDI) in general.
For a single JDBC DataSource, DataSourceTransactionManager is perfectly sufficient,
and for accessing a single resource with Hibernate (including transactional cache),
HibernateTransactionManager is appropriate, for example.

For typical JTA transactions (REQUIRED, SUPPORTS, MANDATORY, NEVER), a plain
JtaTransactionManager definition is all you need, portable across all Java EE servers.
This corresponds to the functionality of the JTA UserTransaction, for which Java EE
specifies a standard JNDI name ("java:comp/UserTransaction"). There is no need to
configure a server-specific TransactionManager lookup for this kind of JTA usage.

Transaction suspension (REQUIRES_NEW, NOT_SUPPORTED) is just available with a
JTA TransactionManager being registered. Common TransactionManager locations are
autodetected by JtaTransactionManager, provided that the "autodetectTransactionManager"
flag is set to "true" (which it is by default).

Note: Support for the JTA TransactionManager interface is not required by Java EE.
Almost all Java EE servers expose it, but do so as extension to EE. There might be some
issues with compatibility, despite the TransactionManager interface being part of JTA.
As a consequence, Spring provides various vendor-specific PlatformTransactionManagers,
which are recommended to be used if appropriate: WebLogicJtaTransactionManager,
WebSphereUowTransactionManager and OC4JJtaTransactionManager.
For all other Java EE servers, the standard JtaTransactionManager is sufficient.

JTA 1.1 adds the TransactionSynchronizationRegistry facility, as public Java EE 5
API in addition to the standard JTA UserTransaction handle. As of Spring 2.5, this
JtaTransactionManager autodetects the TransactionSynchronizationRegistry and uses
it for registering Spring-managed synchronizations when participating in an existing
JTA transaction (e.g. controlled by EJB CMT). If no TransactionSynchronizationRegistry
is available (or the JTA 1.1 API isn't available), then such synchronizations
will be registered via the (non-EE) JTA TransactionManager handle.

This class is serializable. However, active synchronizations do not survive serialization.

FALLBACK_TRANSACTION_MANAGER_NAMES

Fallback JNDI locations for the JTA TransactionManager. Applied if
the JTA UserTransaction does not implement the JTA TransactionManager
interface, provided that the "autodetectTransactionManager" flag is "true".

setAutodetectUserTransaction

Set whether to autodetect the JTA UserTransaction at its default
JNDI location "java:comp/UserTransaction", as specified by Java EE.
Will proceed without UserTransaction if none found.

Default is "true", autodetecting the UserTransaction unless
it has been specified explicitly. Turn this flag off to allow for
JtaTransactionManager operating against the TransactionManager only,
despite a default UserTransaction being available.

setCacheUserTransaction

public void setCacheUserTransaction(boolean cacheUserTransaction)

Set whether to cache the JTA UserTransaction object fetched from JNDI.

Default is "true": UserTransaction lookup will only happen at startup,
reusing the same UserTransaction handle for all transactions of all threads.
This is the most efficient choice for all application servers that provide
a shared UserTransaction object (the typical case).

Turn this flag off to enforce a fresh lookup of the UserTransaction
for every transaction. This is only necessary for application servers
that return a new UserTransaction for every transaction, keeping state
tied to the UserTransaction object itself rather than the current thread.

setTransactionManager

A TransactionManager is necessary for suspending and resuming transactions,
as this not supported by the UserTransaction interface.

Note that the TransactionManager will be autodetected if the JTA
UserTransaction object implements the JTA TransactionManager interface too,
as well as autodetected at various well-known fallback JNDI locations.

setTransactionManagerName

A TransactionManager is necessary for suspending and resuming transactions,
as this not supported by the UserTransaction interface.

Note that the TransactionManager will be autodetected if the JTA
UserTransaction object implements the JTA TransactionManager interface too,
as well as autodetected at various well-known fallback JNDI locations.

setAutodetectTransactionManager

Set whether to autodetect a JTA UserTransaction object that implements
the JTA TransactionManager interface too (i.e. the JNDI location for the
TransactionManager is "java:comp/UserTransaction", same as for the UserTransaction).
Also checks the fallback JNDI locations "java:comp/TransactionManager" and
"java:/TransactionManager". Will proceed without TransactionManager if none found.

Default is "true", autodetecting the TransactionManager unless it has been
specified explicitly. Can be turned off to deliberately ignore an available
TransactionManager, for example when there are known issues with suspend/resume
and any attempt to use REQUIRES_NEW or NOT_SUPPORTED should fail fast.

setAllowCustomIsolationLevels

Default is "false", throwing an exception if a non-default isolation level
is specified for a transaction. Turn this flag on if affected resource adapters
check the thread-bound transaction context and apply the specified isolation
levels individually (e.g. through a IsolationLevelDataSourceRouter).

doGetTransaction

This implementation returns a JtaTransactionObject instance for the
JTA UserTransaction.

The UserTransaction object will either be looked up freshly for the
current transaction, or the cached one looked up at startup will be used.
The latter is the default: Most application servers use a shared singleton
UserTransaction that can be cached. Turn off the "cacheUserTransaction"
flag to enforce a fresh lookup for every transaction.

isExistingTransaction

Check if the given transaction object indicates an existing transaction
(that is, a transaction which has already started).

The result will be evaluated according to the specified propagation
behavior for the new transaction. An existing transaction might get
suspended (in case of PROPAGATION_REQUIRES_NEW), or the new transaction
might participate in the existing one (in case of PROPAGATION_REQUIRED).

The default implementation returns false, assuming that
participating in existing transactions is generally not supported.
Subclasses are of course encouraged to provide such support.

doBegin

Begin a new transaction with semantics according to the given transaction
definition. Does not have to care about applying the propagation behavior,
as this has already been handled by this abstract manager.

This method gets called when the transaction manager has decided to actually
start a new transaction. Either there wasn't any transaction before, or the
previous transaction has been suspended.

A special scenario is a nested transaction without savepoint: If
useSavepointForNestedTransaction() returns "false", this method
will be called to start a nested transaction when necessary. In such a context,
there will be an active transaction: The implementation of this method has
to detect this and start an appropriate nested transaction.

doCommit

An implementation does not need to check the "new transaction" flag
or the rollback-only flag; this will already have been handled before.
Usually, a straight commit will be performed on the transaction object
contained in the passed-in status.

doRollback

An implementation does not need to check the "new transaction" flag;
this will already have been handled before. Usually, a straight rollback
will be performed on the transaction object contained in the passed-in status.

doSetRollbackOnly

Set the given transaction rollback-only. Only called on rollback
if the current transaction participates in an existing one.

The default implementation throws an IllegalTransactionStateException,
assuming that participating in existing transactions is generally not
supported. Subclasses are of course encouraged to provide such support.

registerAfterCompletionWithExistingTransaction

Register the given list of transaction synchronizations with the existing transaction.

Invoked when the control of the Spring transaction manager and thus all Spring
transaction synchronizations end, without the transaction being completed yet. This
is for example the case when participating in an existing JTA or EJB CMT transaction.

The default implementation simply invokes the afterCompletion methods
immediately, passing in "STATUS_UNKNOWN". This is the best we can do if there's no
chance to determine the actual outcome of the outer transaction.

doRegisterAfterCompletionWithJtaTransaction

Register a JTA synchronization on the JTA TransactionManager, for calling
afterCompletion on the given Spring TransactionSynchronizations.

The default implementation registers the synchronizations on the
JTA 1.1 TransactionSynchronizationRegistry, if available, or on the
JTA TransactionManager's current Transaction - again, if available.
If none of the two is available, a warning will be logged.