Top Description Fields Constructors Methods
org.springframework.transaction.jta

public Class JtaTransactionManager

extends AbstractPlatformTransactionManager
implements TransactionFactory, InitializingBean, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, org.springframework.beans.factory.InitializingBean, org.springframework.transaction.jta.TransactionFactory
Annotations
@SuppressWarnings:serial
Imports
java.io.IOException, .ObjectInputStream, .Serializable, java.util.List, .Properties, javax.naming.NamingException, jakarta.transaction.HeuristicMixedException, .HeuristicRollbackException, .InvalidTransactionException, .NotSupportedException, .RollbackException, .Status, .SystemException, .Transaction, .TransactionManager, .TransactionSynchronizationRegistry, .UserTransaction, org.springframework.beans.factory.InitializingBean, org.springframework.jndi.JndiTemplate, org.springframework.lang.Nullable, org.springframework.transaction.CannotCreateTransactionException, .HeuristicCompletionException, .IllegalTransactionStateException, .InvalidIsolationLevelException, .NestedTransactionNotSupportedException, .TransactionDefinition, .TransactionSuspensionNotSupportedException, .TransactionSystemException, .UnexpectedRollbackException, org.springframework.transaction.support.AbstractPlatformTransactionManager, .DefaultTransactionStatus, .TransactionSynchronization, org.springframework.util.Assert, .StringUtils
org.springframework.transaction.PlatformTransactionManager implementation for JTA, delegating to a backend JTA provider. This is typically used to delegate to a Jakarta 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 Jakarta EE servers. This corresponds to the functionality of the JTA UserTransaction, for which Jakarta 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 Jakarta EE. Almost all Jakarta 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.

This pure JtaTransactionManager class supports timeouts but not per-transaction isolation levels. Custom subclasses may override the doJtaBegin method for specific JTA extensions in order to provide this functionality. Such adapters for specific Jakarta EE transaction coordinators may also expose transaction names for monitoring; with standard JTA, transaction names will simply be ignored.

JTA 1.1 adds the TransactionSynchronizationRegistry facility, as public Jakarta EE 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, then such synchronizations will be registered via the (non-EE) JTA TransactionManager handle.

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

Author
Juergen Hoeller
Since
24.03.2003
See Also
jakarta.transaction.UserTransaction, jakarta.transaction.TransactionManager, jakarta.transaction.TransactionSynchronizationRegistry, setUserTransactionName, setUserTransaction, setTransactionManagerName, setTransactionManager

Field Summary

Modifier and TypeField and Description
private boolean
allowCustomIsolationLevels

private boolean
autodetectTransactionManager

private boolean
autodetectTransactionSynchronizationRegistry

private boolean
autodetectUserTransaction

private boolean
cacheUserTransaction

public static final String
DEFAULT_TRANSACTION_SYNCHRONIZATION_REGISTRY_NAME

Standard Jakarta EE JNDI location for the JTA TransactionSynchronizationRegistry.

public static final String
DEFAULT_USER_TRANSACTION_NAME

Default JNDI location for the JTA UserTransaction.

public static final String[]
FALLBACK_TRANSACTION_MANAGER_NAMES

Fallback JNDI locations for the JTA TransactionManager.

private transient JndiTemplate
jndiTemplate

private transient TransactionManager
transactionManager

private String
transactionManagerName

private transient TransactionSynchronizationRegistry
transactionSynchronizationRegistry

private String
transactionSynchronizationRegistryName

private transient UserTransaction
userTransaction

private String
userTransactionName

private boolean
userTransactionObtainedFromJndi

Inherited from org.springframework.transaction.support.AbstractPlatformTransactionManager:
loggerSYNCHRONIZATION_ALWAYSSYNCHRONIZATION_NEVERSYNCHRONIZATION_ON_ACTUAL_TRANSACTION

Constructor Summary

AccessConstructor and Description
public
JtaTransactionManager()

Create a new JtaTransactionManager instance, to be configured as bean.

public
JtaTransactionManager(UserTransaction
the JTA UserTransaction to use as direct reference
userTransaction)

Create a new JtaTransactionManager instance.

public
JtaTransactionManager(UserTransaction
the JTA UserTransaction to use as direct reference
userTransaction, TransactionManager
the JTA TransactionManager to use as direct reference
transactionManager)

Create a new JtaTransactionManager instance.

public
JtaTransactionManager(TransactionManager
the JTA TransactionManager to use as direct reference
transactionManager)

Create a new JtaTransactionManager instance.

Method Summary

Modifier and TypeMethod and Description
public void
afterPropertiesSet()

Implements org.springframework.beans.factory.InitializingBean.afterPropertiesSet.

Initialize the UserTransaction as well as the TransactionManager handle.

protected void
applyIsolationLevel(JtaTransactionObject
the JtaTransactionObject containing the UserTransaction
txObject, int
isolation level taken from transaction definition
isolationLevel)

Apply the given transaction isolation level.

protected void
applyTimeout(JtaTransactionObject
the JtaTransactionObject containing the UserTransaction
txObject, int
the timeout value taken from transaction definition
timeout)

Apply the given transaction timeout.

protected UserTransaction

Returns:

a corresponding UserTransaction handle
buildUserTransaction(TransactionManager
the TransactionManager
transactionManager)

Build a UserTransaction handle based on the given TransactionManager.

protected void
checkUserTransactionAndTransactionManager()

Check the UserTransaction as well as the TransactionManager handle, assuming standard JTA requirements.

public Transaction
createTransaction(String
the transaction name (may be null)
name, int
the transaction timeout (may be -1 for the default timeout)
timeout)

Implements org.springframework.transaction.jta.TransactionFactory.createTransaction.

Create an active Transaction object based on the given name and timeout.

protected void
doBegin(Object
the transaction object returned by doGetTransaction
transaction, TransactionDefinition
a TransactionDefinition instance, describing propagation behavior, isolation level, read-only flag, timeout, and transaction name
definition)

Implements abstract org.springframework.transaction.support.AbstractPlatformTransactionManager.doBegin.

Begin a new transaction with semantics according to the given transaction definition.

protected void
doCleanupAfterCompletion(Object
the transaction object returned by doGetTransaction
transaction)

Overrides org.springframework.transaction.support.AbstractPlatformTransactionManager.doCleanupAfterCompletion.

Cleanup resources after transaction completion.

protected void
doCommit(DefaultTransactionStatus
the status representation of the transaction
status)

Implements abstract org.springframework.transaction.support.AbstractPlatformTransactionManager.doCommit.

Perform an actual commit of the given transaction.

protected JtaTransactionObject

Returns:

the JtaTransactionObject holding the UserTransaction
doGetJtaTransaction(UserTransaction
the UserTransaction handle to use for the current transaction
ut)

Get a JTA transaction object for the given current UserTransaction.

protected Object
doGetTransaction()

Implements abstract org.springframework.transaction.support.AbstractPlatformTransactionManager.doGetTransaction.

This implementation returns a JtaTransactionObject instance for the JTA UserTransaction.

protected void
doJtaBegin(JtaTransactionObject
the JtaTransactionObject containing the UserTransaction
txObject, TransactionDefinition
the TransactionDefinition instance, describing propagation behavior, isolation level, read-only flag, timeout, and transaction name
definition)

Perform a JTA begin on the JTA UserTransaction or TransactionManager.

protected void
doJtaResume(JtaTransactionObject
the JtaTransactionObject containing the UserTransaction
txObject, Object
the suspended JTA Transaction object
suspendedTransaction)

Perform a JTA resume on the JTA TransactionManager.

protected Object

Returns:

the suspended JTA Transaction object
doJtaSuspend(JtaTransactionObject
the JtaTransactionObject containing the UserTransaction
txObject)

Perform a JTA suspend on the JTA TransactionManager.

protected void
doRegisterAfterCompletionWithJtaTransaction(JtaTransactionObject
the current transaction object
txObject, List<TransactionSynchronization>
a List of TransactionSynchronization objects
synchronizations)

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

protected void
doResume(Object
the transaction object returned by doGetTransaction
transaction, Object
the object that holds suspended resources, as returned by doSuspend
suspendedResources)

Overrides org.springframework.transaction.support.AbstractPlatformTransactionManager.doResume.

Resume the resources of the current transaction.

protected void
doRollback(DefaultTransactionStatus
the status representation of the transaction
status)

Implements abstract org.springframework.transaction.support.AbstractPlatformTransactionManager.doRollback.

Perform an actual rollback of the given transaction.

protected void
doSetRollbackOnly(DefaultTransactionStatus
the status representation of the transaction
status)

Overrides org.springframework.transaction.support.AbstractPlatformTransactionManager.doSetRollbackOnly.

Set the given transaction rollback-only.

protected Object
doSuspend(Object
the transaction object returned by doGetTransaction
transaction)

Overrides org.springframework.transaction.support.AbstractPlatformTransactionManager.doSuspend.

Suspend the resources of the current transaction.

protected TransactionManager

Returns:

the JTA TransactionManager reference, or null if not found
findTransactionManager(UserTransaction
the JTA UserTransaction object
ut)

Find the JTA TransactionManager through autodetection: checking whether the UserTransaction object implements the TransactionManager, and checking the fallback JNDI locations.

protected TransactionSynchronizationRegistry

Returns:

the JTA TransactionSynchronizationRegistry handle to use, or null if none found
findTransactionSynchronizationRegistry(UserTransaction
the JTA UserTransaction object
ut, TransactionManager
the JTA TransactionManager object
tm)

Find the JTA 1.1 TransactionSynchronizationRegistry through autodetection: checking whether the UserTransaction object or TransactionManager object implements it, and checking Jakarta EE's standard JNDI location.

protected UserTransaction

Returns:

the JTA UserTransaction reference, or null if not found
findUserTransaction()

Find the JTA UserTransaction through a default JNDI lookup: "java:comp/UserTransaction".

public Properties
getJndiEnvironment()

Return the JNDI environment to use for JNDI lookups.

public JndiTemplate
getJndiTemplate()

Return the JndiTemplate used for JNDI lookups.

public TransactionManager
getTransactionManager()

Return the JTA TransactionManager that this transaction manager uses, if any.

public TransactionSynchronizationRegistry
getTransactionSynchronizationRegistry()

Return the JTA 1.1 TransactionSynchronizationRegistry that this transaction manager uses, if any.

public UserTransaction
getUserTransaction()

Return the JTA UserTransaction that this transaction manager uses.

protected void
initTransactionSynchronizationRegistry()

Initialize the JTA 1.1 TransactionSynchronizationRegistry, if available.

protected void
initUserTransactionAndTransactionManager()

Initialize the UserTransaction as well as the TransactionManager handle.

protected boolean
isExistingTransaction(Object
the transaction object returned by doGetTransaction
transaction)

Overrides org.springframework.transaction.support.AbstractPlatformTransactionManager.isExistingTransaction.

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

protected TransactionManager

Returns:

the UserTransaction object
lookupTransactionManager(String
the JNDI name of the TransactionManager
transactionManagerName)

Look up the JTA TransactionManager in JNDI via the configured name.

protected TransactionSynchronizationRegistry

Returns:

the TransactionSynchronizationRegistry object
lookupTransactionSynchronizationRegistry(String
the JNDI name of the TransactionSynchronizationRegistry
registryName)

Look up the JTA 1.1 TransactionSynchronizationRegistry in JNDI via the configured name.

protected UserTransaction

Returns:

the UserTransaction object
lookupUserTransaction(String
the JNDI name of the UserTransaction
userTransactionName)

Look up the JTA UserTransaction in JNDI via the configured name.

private void
readObject(ObjectInputStream ois)

Hides org.springframework.transaction.support.AbstractPlatformTransactionManager.readObject.

protected void
registerAfterCompletionWithExistingTransaction(Object
the transaction object returned by doGetTransaction
transaction, List<TransactionSynchronization>
a List of TransactionSynchronization objects
synchronizations)

Overrides org.springframework.transaction.support.AbstractPlatformTransactionManager.registerAfterCompletionWithExistingTransaction.

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

protected TransactionManager

Returns:

the JTA TransactionManager handle to use, or null if none found
retrieveTransactionManager()

Allows subclasses to retrieve the JTA TransactionManager in a vendor-specific manner.

protected TransactionSynchronizationRegistry

Returns:

the JTA TransactionSynchronizationRegistry handle to use, or null if none found
retrieveTransactionSynchronizationRegistry()

Allows subclasses to retrieve the JTA 1.1 TransactionSynchronizationRegistry in a vendor-specific manner.

protected UserTransaction

Returns:

the JTA UserTransaction handle to use, or null if none found
retrieveUserTransaction()

Allows subclasses to retrieve the JTA UserTransaction in a vendor-specific manner.

public void
setAllowCustomIsolationLevels(boolean allowCustomIsolationLevels)

Set whether to allow custom isolation levels to be specified.

public void
setAutodetectTransactionManager(boolean autodetectTransactionManager)

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

public void
setAutodetectTransactionSynchronizationRegistry(boolean autodetectTransactionSynchronizationRegistry)

Set whether to autodetect a JTA 1.1 TransactionSynchronizationRegistry object at its default JDNI location ("java:comp/TransactionSynchronizationRegistry") if the UserTransaction has also been obtained from JNDI, and also whether to fall back to checking whether the JTA UserTransaction/TransactionManager object implements the JTA TransactionSynchronizationRegistry interface too.

public void
setAutodetectUserTransaction(boolean autodetectUserTransaction)

Set whether to autodetect the JTA UserTransaction at its default JNDI location "java:comp/UserTransaction", as specified by Jakarta EE.

public void
setCacheUserTransaction(boolean cacheUserTransaction)

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

public void
setJndiEnvironment(Properties jndiEnvironment)

Set the JNDI environment to use for JNDI lookups.

public void
setJndiTemplate(JndiTemplate jndiTemplate)

Set the JndiTemplate to use for JNDI lookups.

public void
setTransactionManager(TransactionManager transactionManager)

Set the JTA TransactionManager to use as direct reference.

public void
setTransactionManagerName(String transactionManagerName)

Set the JNDI name of the JTA TransactionManager.

public void
setTransactionSynchronizationRegistry(TransactionSynchronizationRegistry transactionSynchronizationRegistry)

Set the JTA 1.1 TransactionSynchronizationRegistry to use as direct reference.

public void
setTransactionSynchronizationRegistryName(String transactionSynchronizationRegistryName)

Set the JNDI name of the JTA 1.1 TransactionSynchronizationRegistry.

public void
setUserTransaction(UserTransaction userTransaction)

Set the JTA UserTransaction to use as direct reference.

public void
setUserTransactionName(String userTransactionName)

Set the JNDI name of the JTA UserTransaction.

protected boolean
shouldCommitOnGlobalRollbackOnly()

Overrides org.springframework.transaction.support.AbstractPlatformTransactionManager.shouldCommitOnGlobalRollbackOnly.

This implementation returns "true": a JTA commit will properly handle transactions that have been marked rollback-only at a global level.

public boolean
supportsResourceAdapterManagedTransactions()

Implements org.springframework.transaction.jta.TransactionFactory.supportsResourceAdapterManagedTransactions.

Determine whether the underlying transaction manager supports XA transactions managed by a resource adapter (i.e. without explicit XA resource enlistment).

protected boolean
useSavepointForNestedTransaction()

Overrides org.springframework.transaction.support.AbstractPlatformTransactionManager.useSavepointForNestedTransaction.

This implementation returns false to cause a further invocation of doBegin despite an already existing transaction.

Inherited from org.springframework.transaction.support.AbstractPlatformTransactionManager:
commitdetermineTimeoutgetDefaultTimeoutgetTransactiongetTransactionExecutionListenersgetTransactionSynchronizationinvokeAfterCompletionisFailEarlyOnGlobalRollbackOnlyisGlobalRollbackOnParticipationFailureisNestedTransactionAllowedisRollbackOnCommitFailureisValidateExistingTransactionprepareForCommitprepareSynchronizationresumerollbacksetDefaultTimeoutsetFailEarlyOnGlobalRollbackOnlysetGlobalRollbackOnParticipationFailuresetNestedTransactionAllowedsetRollbackOnCommitFailuresetTransactionExecutionListenerssetTransactionSynchronizationsetTransactionSynchronizationNamesetValidateExistingTransactionsuspendtriggerBeforeCommittriggerBeforeCompletion