org.springframework.transaction.jta
Class JtaTransactionManager

java.lang.Object
  org.springframework.transaction.support.AbstractPlatformTransactionManager
      org.springframework.transaction.jta.JtaTransactionManager

All Implemented Interfaces:

InitializingBean, PlatformTransactionManager, java.io.Serializable

Direct Known Subclasses:

WebLogicJtaTransactionManager

public class JtaTransactionManager

extends AbstractPlatformTransactionManager

implements InitializingBean

PlatformTransactionManager implementation for JTA, i.e. J2EE container transactions. Can also work with a locally configured JTA implementation.

This transaction manager is appropriate for handling distributed transactions, i.e. transactions that span multiple resources, and for managing transactions on a J2EE Connector (e.g. a persistence toolkit registered as JCA Connector). For a single JDBC DataSource, DataSourceTransactionManager is perfectly sufficient, and for accessing a single resource with Hibernate (including transactional cache), HibernateTransactionManager is appropriate.

Transaction synchronization is active by default, to allow data access support classes to register resources that are opened within the transaction for closing at transaction completion time. Spring's support classes for JDBC, Hibernate and JDO all perform such registration, allowing for reuse of the same Hibernate Session etc within the transaction. Standard JTA does not even guarantee that for Connections from a transactional JDBC DataSource: Spring's synchronization solves those issues.

Synchronization is also leveraged for transactional cache handling with Hibernate. Therefore, as long as JtaTransactionManager drives the JTA transactions, there is no need to configure Hibernate's JTATransaction strategy or a container-specific Hibernate TransactionManagerLookup. However, certain JTA implementations are restrictive in terms of what JDBC calls they allow after transaction completion, complaining even on close calls: In that case, it is indeed necessary to configure a Hibernate TransactionManagerLookup, potentially via Spring's LocalSessionFactoryBean.

If JtaTransactionManager participates in an existing JTA transaction, e.g. from EJB CMT, synchronization will be triggered on finishing the nested transaction, before passing transaction control back to the J2EE container. In this case, a container-specific Hibernate TransactionManagerLookup is the only way to achieve exact afterCompletion callbacks for transactional cache handling with Hibernate. In such a scenario, use Hibernate >=2.1 which features automatic JTA detection.

For typical JTA transactions (REQUIRED, SUPPORTS, MANDATORY, NEVER), a plain JtaTransactionManager definition is all you need, completely portable across all J2EE servers. This corresponds to the functionality of the JTA UserTransaction, for which J2EE 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.

Note: Advanced JTA usage below. Dealing with these mechanisms is not necessary for typical usage scenarios.

Transaction suspension (REQUIRES_NEW, NOT_SUPPORTED) is just available with a JTA TransactionManager being registered, via the "transactionManagerName" or "transactionManager" property. The location of this internal JTA object is not specified by J2EE; it is individual for each J2EE server, often kept in JNDI like the UserTransaction. Some well-known JNDI locations are:

• "java:comp/UserTransaction" for Resin, Orion (Oracle OC4J), JOnAS (JOTM), BEA WebLogic (unofficial)
• "javax.transaction.TransactionManager" for BEA WebLogic (official)
• "java:/TransactionManager" for JBoss, JRun4

"java:comp/UserTransaction" as JNDI name for the TransactionManager means that the same JTA object implements both the UserTransaction and the TransactionManager interface. As this is easy to test when looking up the UserTransaction, this will be autodetected on initialization of JtaTransactionManager. In this case, there's no need to specify the "transactionManagerName" (for Resin, Orion, JOnAS, WebLogic).

A JNDI lookup can also be factored out into a corresponding JndiObjectFactoryBean, passed into JtaTransactionManager's "transactionManager" property. Such a bean definition can then be reused by other objects, for example Spring's LocalSessionFactoryBean for Hibernate (see below).

For IBM WebSphere and standalone JOTM, static accessor methods are required to obtain the JTA TransactionManager: Therefore, WebSphere and JOTM have their own FactoryBean implementations, to be wired with the "transactionManager" property. In case of JotmFactoryBean, the same JTA object implements UserTransaction too: Therefore, passing the object to the "userTransaction" property is sufficient.

Note: Support for the JTA TransactionManager interface is not required by J2EE. Almost all J2EE servers expose it, but do so as extension to J2EE. There might be some issues with compatibility, despite the TransactionManager interface being part of JTA. The only currently known problem is resuming a transaction on WebLogic, which by default fails if the suspended transaction was marked rollback-only; for other usages, it works properly. Use Spring's WebLogicJtaTransactionManager to enforce a resume in any case.

The JTA TransactionManager can also be used to register custom synchronizations with the JTA transaction itself instead of Spring's transaction manager. This is particularly useful for closing resources with rigid JTA implementations like Weblogic's or WebSphere's that do not allow any access to resources after transaction completion, not even for cleanup. For example, Hibernate access is affected by this issue, as outlined above in the discussion of transaction synchronization.

Spring's LocalSessionFactoryBean for Hibernate supports plugging a given JTA TransactionManager into Hibernate's TransactionManagerLookup mechanism, for Hibernate-driven cache synchronization and proper cleanup without warnings. The same JTA TransactionManager configuration as above can be used in this case (with a JndiObjectFactoryBean for a JNDI lookup, or one of the FactoryBeans), avoiding double configuration. Alternatively, specify corresponding Hibernate properties (see Hibernate docs for details).

JtaTransactionManager supports timeouts but not custom isolation levels. Custom subclasses can override applyIsolationLevel for specific JTA implementations. Note that some resource-specific transaction managers like DataSourceTransactionManager and HibernateTransactionManager do support timeouts, custom isolation levels, and transaction suspension without JTA's restrictions.

This class is serializable. Active synchronizations do not survive serialization.

Since:

24.03.2003

Author:

Juergen Hoeller

See Also:

setUserTransactionName(java.lang.String), setUserTransaction(javax.transaction.UserTransaction), setTransactionManagerName(java.lang.String), setTransactionManager(javax.transaction.TransactionManager), applyIsolationLevel(int), JotmFactoryBean, WebSphereTransactionManagerFactoryBean, WebLogicJtaTransactionManager, JndiObjectFactoryBean, LocalSessionFactoryBean.setJtaTransactionManager(javax.transaction.TransactionManager), HibernateTransactionManager, DataSourceTransactionManager, Serialized Form

Field Summary

static java.lang.String

DEFAULT_USER_TRANSACTION_NAME

Fields inherited from class org.springframework.transaction.support.AbstractPlatformTransactionManager

logger, SYNCHRONIZATION_ALWAYS, SYNCHRONIZATION_NEVER, SYNCHRONIZATION_ON_ACTUAL_TRANSACTION

Constructor Summary

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

JtaTransactionManager(javax.transaction.UserTransaction userTransaction)
Create a new JtaTransactionManager instance.

JtaTransactionManager(javax.transaction.UserTransaction userTransaction, javax.transaction.TransactionManager transactionManager)
Create a new JtaTransactionManager instance.

Method Summary

void	afterPropertiesSet() Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).
protected void	applyIsolationLevel(int isolationLevel) Apply the given transaction isolation level.
protected void	doBegin(java.lang.Object transaction, TransactionDefinition definition) Begin a new transaction with the given transaction definition.
protected void	doCommit(DefaultTransactionStatus status) Perform an actual commit on the given transaction.
protected java.lang.Object	doGetTransaction() This implementation returns a JtaTransactionObject instance for the JTA UserTransaction.
protected void	doJtaResume(javax.transaction.Transaction suspendedTransaction) Perform a JTA resume on the JTA TransactionManager.
protected javax.transaction.Transaction	doJtaSuspend() Perform a JTA suspend on the JTA TransactionManager.
protected void	doResume(java.lang.Object transaction, java.lang.Object suspendedResources) Resume the resources of the current transaction.
protected void	doRollback(DefaultTransactionStatus status) Perform an actual rollback on the given transaction.
protected void	doSetRollbackOnly(DefaultTransactionStatus status) Set the given transaction rollback-only.
protected java.lang.Object	doSuspend(java.lang.Object transaction) Suspend the resources of the current transaction.
JndiTemplate	getJndiTemplate() Return the JndiTemplate used for JNDI lookups.
javax.transaction.TransactionManager	getTransactionManager() Return the JTA TransactionManager that this transaction manager uses.
javax.transaction.UserTransaction	getUserTransaction() Return the JTA UserTransaction that this transaction manager uses.
protected boolean	isExistingTransaction(java.lang.Object transaction) Check if the given transaction object indicates an existing, i.e. already begun, transaction.
protected javax.transaction.TransactionManager	lookupTransactionManager(java.lang.String transactionManagerName) Look up the JTA TransactionManager in JNDI via the configured name.
protected javax.transaction.UserTransaction	lookupUserTransaction(java.lang.String userTransactionName) Look up the JTA UserTransaction in JNDI via the configured name.
void	setAutodetectTransactionManager(boolean autodetectTransactionManager) Set whether to autodetect a JTA UserTransaction object that implements the JTA TransactionManager interface too.
void	setJndiTemplate(JndiTemplate jndiTemplate) Set the JndiTemplate to use for JNDI lookups.
void	setTransactionManager(javax.transaction.TransactionManager transactionManager) Set the JTA TransactionManager to use as direct reference.
void	setTransactionManagerName(java.lang.String transactionManagerName) Set the JNDI name of the JTA TransactionManager.
void	setUserTransaction(javax.transaction.UserTransaction userTransaction) Set the JTA UserTransaction to use as direct reference.
void	setUserTransactionName(java.lang.String userTransactionName) Set the JNDI name of the JTA UserTransaction.
protected boolean	useSavepointForNestedTransaction() This implementation returns false to cause a further invocation of doBegin despite an already existing transaction.

Methods inherited from class org.springframework.transaction.support.AbstractPlatformTransactionManager

commit, doCleanupAfterCompletion, getTransaction, getTransactionSynchronization, isNestedTransactionAllowed, isRollbackOnCommitFailure, rollback, setNestedTransactionAllowed, setRollbackOnCommitFailure, setTransactionSynchronization, setTransactionSynchronizationName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_USER_TRANSACTION_NAME

public static final java.lang.String DEFAULT_USER_TRANSACTION_NAME

See Also:

Constant Field Values

Constructor Detail

JtaTransactionManager

public JtaTransactionManager()

Create a new JtaTransactionManager instance, to be configured as bean. Invoke afterPropertiesSet to activate the configuration.

See Also:

setUserTransactionName(java.lang.String), setUserTransaction(javax.transaction.UserTransaction), setTransactionManagerName(java.lang.String), setTransactionManager(javax.transaction.TransactionManager), afterPropertiesSet()

JtaTransactionManager

public JtaTransactionManager(javax.transaction.UserTransaction userTransaction)

Create a new JtaTransactionManager instance.

Parameters:

userTransaction - the JTA UserTransaction to use as direct reference

JtaTransactionManager

public JtaTransactionManager(javax.transaction.UserTransaction userTransaction,
                             javax.transaction.TransactionManager transactionManager)

Create a new JtaTransactionManager instance.

Parameters:

userTransaction - the JTA UserTransaction to use as direct reference

transactionManager - the JTA TransactionManager to use as direct reference

Method Detail

setJndiTemplate

public void setJndiTemplate(JndiTemplate jndiTemplate)

Set the JndiTemplate to use for JNDI lookups. A default one is used if not set.

getJndiTemplate

public JndiTemplate getJndiTemplate()

Return the JndiTemplate used for JNDI lookups.

setUserTransactionName

public void setUserTransactionName(java.lang.String userTransactionName)

Set the JNDI name of the JTA UserTransaction. The J2EE default "java:comp/UserTransaction" is used if not set.

See Also:

DEFAULT_USER_TRANSACTION_NAME, setUserTransaction(javax.transaction.UserTransaction)

setUserTransaction

public void setUserTransaction(javax.transaction.UserTransaction userTransaction)

Set the JTA UserTransaction to use as direct reference. Typically just used for local JTA setups; in a J2EE environment, the UserTransaction will always be fetched from JNDI.

See Also:

setUserTransactionName(java.lang.String)

getUserTransaction

public javax.transaction.UserTransaction getUserTransaction()

Return the JTA UserTransaction that this transaction manager uses.

setTransactionManagerName

public void setTransactionManagerName(java.lang.String transactionManagerName)

Set the JNDI name of the JTA TransactionManager.

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.

See Also:

setTransactionManager(javax.transaction.TransactionManager)

setTransactionManager

public void setTransactionManager(javax.transaction.TransactionManager transactionManager)

Set the JTA TransactionManager to use as direct reference.

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.

See Also:

setTransactionManagerName(java.lang.String), setAutodetectTransactionManager(boolean)

getTransactionManager

public javax.transaction.TransactionManager getTransactionManager()

Return the JTA TransactionManager that this transaction manager uses.

setAutodetectTransactionManager

public void setAutodetectTransactionManager(boolean autodetectTransactionManager)

Set whether to autodetect a JTA UserTransaction object that implements the JTA TransactionManager interface too. Default is true.

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.

afterPropertiesSet

public void afterPropertiesSet()
                        throws TransactionSystemException

Description copied from interface: InitializingBean

Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).

This method allows the bean instance to perform initialization only possible when all bean properties have been set and to throw an exception in the event of misconfiguration.

Specified by:

afterPropertiesSet in interface InitializingBean

Throws:

TransactionSystemException

lookupUserTransaction

protected javax.transaction.UserTransaction lookupUserTransaction(java.lang.String userTransactionName)
                                                           throws TransactionSystemException

Look up the JTA UserTransaction in JNDI via the configured name. Called by afterPropertiesSet if no direct UserTransaction reference was set. Can be overridden in subclasses to provide a different UserTransaction object.

Parameters:

userTransactionName - the JNDI name of the UserTransaction

Returns:

the UserTransaction object

Throws:

TransactionSystemException - if the JNDI lookup failed

See Also:

setJndiTemplate(org.springframework.jndi.JndiTemplate), setUserTransactionName(java.lang.String)

lookupTransactionManager

protected javax.transaction.TransactionManager lookupTransactionManager(java.lang.String transactionManagerName)
                                                                 throws TransactionSystemException

Look up the JTA TransactionManager in JNDI via the configured name. Called by afterPropertiesSet if no direct TransactionManager reference was set. Can be overridden in subclasses to provide a different TransactionManager object.

Parameters:

transactionManagerName - the JNDI name of the TransactionManager

Returns:

the UserTransaction object

Throws:

TransactionSystemException - if the JNDI lookup failed

See Also:

setJndiTemplate(org.springframework.jndi.JndiTemplate), setTransactionManagerName(java.lang.String)

doGetTransaction

protected java.lang.Object doGetTransaction()

This implementation returns a JtaTransactionObject instance for the JTA UserTransaction.

Note that JtaTransactionManager doesn't need a transaction object, as it will access the JTA UserTransaction respectively TransactionManager singletons that it holds directly. Therefore, any transaction object that's useful for status and identification purposes will do.

Specified by:

doGetTransaction in class AbstractPlatformTransactionManager

Returns:

the current transaction object

isExistingTransaction

protected boolean isExistingTransaction(java.lang.Object transaction)

Description copied from class: AbstractPlatformTransactionManager

Check if the given transaction object indicates an existing, i.e. already begun, transaction.

Specified by:

isExistingTransaction in class AbstractPlatformTransactionManager

Parameters:

transaction - transaction object returned by doGetTransaction

Returns:

if there is an existing transaction

useSavepointForNestedTransaction

protected boolean useSavepointForNestedTransaction()

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

JTA implementations might support nested transactions via further UserTransaction.begin invocations, but never support savepoints.

Overrides:

useSavepointForNestedTransaction in class AbstractPlatformTransactionManager

See Also:

doBegin(java.lang.Object, org.springframework.transaction.TransactionDefinition), UserTransaction.begin()

doBegin

protected void doBegin(java.lang.Object transaction,
                       TransactionDefinition definition)

Description copied from class: AbstractPlatformTransactionManager

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

Specified by:

doBegin in class AbstractPlatformTransactionManager

Parameters:

transaction - transaction object returned by doGetTransaction

definition - TransactionDefinition instance, describing propagation behavior, isolation level, timeout etc.

applyIsolationLevel

protected void applyIsolationLevel(int isolationLevel)
                            throws InvalidIsolationLevelException,
                                   javax.transaction.SystemException

Apply the given transaction isolation level. Default implementation will throw an exception for any level other than ISOLATION_DEFAULT. To be overridden in subclasses for specific JTA implementations.

Parameters:

isolationLevel - isolation level taken from transaction definition

Throws:

InvalidIsolationLevelException - if the given isolation level cannot be applied

javax.transaction.SystemException - if thrown by the JTA implementation

See Also:

getUserTransaction(), getTransactionManager()

doSuspend

protected java.lang.Object doSuspend(java.lang.Object transaction)

Description copied from class: AbstractPlatformTransactionManager

Suspend the resources of the current transaction. Transaction synchronization will already have been suspended.

Specified by:

doSuspend in class AbstractPlatformTransactionManager

Parameters:

transaction - transaction object returned by doGetTransaction

Returns:

an object that holds suspended resources (will be kept unexamined for passing it into doResume)

See Also:

AbstractPlatformTransactionManager.doResume(java.lang.Object, java.lang.Object)

doJtaSuspend

protected javax.transaction.Transaction doJtaSuspend()
                                              throws javax.transaction.SystemException

Perform a JTA suspend on the JTA TransactionManager.

Can be overridden in subclasses, for specific JTA implementations.

Returns:

the suspended JTA Transaction object

Throws:

javax.transaction.SystemException - if thrown by JTA methods

See Also:

getTransactionManager()

doResume

protected void doResume(java.lang.Object transaction,
                        java.lang.Object suspendedResources)

Description copied from class: AbstractPlatformTransactionManager

Resume the resources of the current transaction. Transaction synchronization will be resumed afterwards.

Specified by:

doResume in class AbstractPlatformTransactionManager

Parameters:

transaction - transaction object returned by doGetTransaction

suspendedResources - the object that holds suspended resources, as returned by doSuspend

See Also:

AbstractPlatformTransactionManager.doSuspend(java.lang.Object)

doJtaResume

protected void doJtaResume(javax.transaction.Transaction suspendedTransaction)
                    throws javax.transaction.InvalidTransactionException,
                           javax.transaction.SystemException

Perform a JTA resume on the JTA TransactionManager.

Can be overridden in subclasses, for specific JTA implementations.

Parameters:

suspendedTransaction - the suspended JTA Transaction object

Throws:

javax.transaction.InvalidTransactionException - if thrown by JTA methods

javax.transaction.SystemException - if thrown by JTA methods

See Also:

getTransactionManager()

doCommit

protected void doCommit(DefaultTransactionStatus status)

Description copied from class: AbstractPlatformTransactionManager

Perform an actual commit on the given transaction. An implementation does not need to check the rollback-only flag.

Specified by:

doCommit in class AbstractPlatformTransactionManager

Parameters:

status - status representation of the transaction

doRollback

protected void doRollback(DefaultTransactionStatus status)

Description copied from class: AbstractPlatformTransactionManager

Perform an actual rollback on the given transaction. An implementation does not need to check the new transaction flag.

Specified by:

doRollback in class AbstractPlatformTransactionManager

Parameters:

status - status representation of the transaction

doSetRollbackOnly

protected void doSetRollbackOnly(DefaultTransactionStatus status)

Description copied from class: AbstractPlatformTransactionManager

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

Specified by:

doSetRollbackOnly in class AbstractPlatformTransactionManager

Parameters:

status - status representation of the transaction