org.springframework.transaction.jta
Class JtaTransactionManager

java.lang.Object
  extended by org.springframework.transaction.support.AbstractPlatformTransactionManager
      extended by org.springframework.transaction.jta.JtaTransactionManager
All Implemented Interfaces:
Serializable, InitializingBean, PlatformTransactionManager
Direct Known Subclasses:
WebLogicJtaTransactionManager

public class JtaTransactionManager
extends AbstractPlatformTransactionManager
implements InitializingBean, Serializable

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.

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 well-defined JTA object is not specified by J2EE; it is specific to each J2EE server, often kept in JNDI like the JTA UserTransaction. Some well-known JNDI locations are:

All of these cases are autodetected by JtaTransactionManager (since Spring 1.2), provided that the "autodetectTransactionManager" flag is set to "true" (which it is by default). Consequently, JtaTransactionManager will support transaction suspension out-of-the-box on many J2EE servers.

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.

It is also possible to specify a JTA TransactionManager only, either through the corresponding constructor or through the "transactionManager" property. In the latter case, the "userTransactionName" property needs to be set to null, to suppress the default "java:comp/UserTransaction" JNDI lookup and thus enforce use of the given JTA TransactionManager even for begin, commit and rollback.

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 strict JTA implementations such as 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).

This standard JtaTransactionManager supports timeouts but not per-transaction isolation levels. Custom subclasses can override doJtaBegin for specific JTA implementations to provide this functionality; Spring includes a corresponding WebLogicJtaTransactionManager class, for example. Such adapters for specific J2EE transaction coordinators can also expose transaction names for monitoring; with standard JTA, transaction names will be ignored.

Consider using WebLogicJtaTransactionManager on BEA WebLogic, which supports the full power of Spring's transaction definitions on WebLogic's transaction coordinator, beyond standard JTA: transaction names, per-transaction isolation levels, and proper resuming of transactions in all cases. WebLogicJtaTransactionManager automatically adapts to WebLogic 7.0 or 8.1+.

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

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), doJtaBegin(org.springframework.transaction.jta.JtaTransactionObject, org.springframework.transaction.TransactionDefinition), JotmFactoryBean, WebSphereTransactionManagerFactoryBean, WebLogicJtaTransactionManager, JndiObjectFactoryBean, LocalSessionFactoryBean.setJtaTransactionManager(javax.transaction.TransactionManager), Serialized Form

Field Summary
static String DEFAULT_USER_TRANSACTION_NAME
          Default JNDI location for the JTA UserTransaction.
static String[] FALLBACK_TRANSACTION_MANAGER_NAMES
          Fallback JNDI locations for the JTA TransactionManager.
 
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(TransactionManager transactionManager)
          Create a new JtaTransactionManager instance.
JtaTransactionManager(UserTransaction userTransaction)
          Create a new JtaTransactionManager instance.
JtaTransactionManager(UserTransaction userTransaction, 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(JtaTransactionObject txObject, int isolationLevel)
          Apply the given transaction isolation level.
protected  void applyTimeout(JtaTransactionObject txObject, int timeout)
          Apply the given transaction timeout.
protected  void doBegin(Object transaction, TransactionDefinition definition)
          Begin a new transaction with semantics according to the given transaction definition.
protected  void doCommit(DefaultTransactionStatus status)
          Perform an actual commit of the given transaction.
protected  JtaTransactionObject doGetJtaTransaction(UserTransaction ut)
          Get a JTA transaction object for the given current UserTransaction.
protected  Object doGetTransaction()
          This implementation returns a JtaTransactionObject instance for the JTA UserTransaction.
protected  void doJtaBegin(JtaTransactionObject txObject, TransactionDefinition definition)
          Perform a JTA begin on the JTA UserTransaction or TransactionManager.
protected  void doJtaResume(JtaTransactionObject txObject, Object suspendedTransaction)
          Perform a JTA resume on the JTA TransactionManager.
protected  Object doJtaSuspend(JtaTransactionObject txObject)
          Perform a JTA suspend on the JTA TransactionManager.
protected  void doRegisterAfterCompletionWithJtaTransaction(JtaTransactionObject txObject, List synchronizations)
          Register a JTA synchronization on the JTA TransactionManager, for calling afterCompletion on the given Spring TransactionSynchronizations.
protected  void doResume(Object transaction, Object suspendedResources)
          Resume the resources of the current transaction.
protected  void doRollback(DefaultTransactionStatus status)
          Perform an actual rollback of the given transaction.
protected  void doSetRollbackOnly(DefaultTransactionStatus status)
          Set the given transaction rollback-only.
protected  Object doSuspend(Object transaction)
          Suspend the resources of the current transaction.
protected  TransactionManager findTransactionManager(UserTransaction ut)
          Find the JTA TransactionManager through autodetection: checking whether the UserTransaction object implements the TransactionManager, and checking the fallback JNDI locations.
 Properties getJndiEnvironment()
          Return the JNDI environment to use for JNDI lookups.
 JndiTemplate getJndiTemplate()
          Return the JndiTemplate used for JNDI lookups.
 TransactionManager getTransactionManager()
          Return the JTA TransactionManager that this transaction manager uses.
 UserTransaction getUserTransaction()
          Return the JTA UserTransaction that this transaction manager uses.
protected  boolean isExistingTransaction(Object transaction)
          Check if the given transaction object indicates an existing transaction (that is, a transaction which has already started).
protected  TransactionManager lookupTransactionManager(String transactionManagerName)
          Look up the JTA TransactionManager in JNDI via the configured name.
protected  UserTransaction lookupUserTransaction(String userTransactionName)
          Look up the JTA UserTransaction in JNDI via the configured name.
protected  void registerAfterCompletionWithExistingTransaction(Object transaction, List synchronizations)
          Register the given list of transaction synchronizations with the existing transaction.
protected  TransactionManager retrieveTransactionManager()
          Allows subclasses to retrieve the JTA TransactionManager in a vendor-specific manner.
protected  UserTransaction retrieveUserTransaction()
          Allows subclasses to retrieve the JTA UserTransaction in a vendor-specific manner.
 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).
 void setCacheUserTransaction(boolean cacheUserTransaction)
          Set whether to cache the JTA UserTransaction object fetched from JNDI.
 void setJndiEnvironment(Properties jndiEnvironment)
          Set the JNDI environment to use for JNDI lookups.
 void setJndiTemplate(JndiTemplate jndiTemplate)
          Set the JndiTemplate to use for JNDI lookups.
 void setTransactionManager(TransactionManager transactionManager)
          Set the JTA TransactionManager to use as direct reference.
 void setTransactionManagerName(String transactionManagerName)
          Set the JNDI name of the JTA TransactionManager.
 void setUserTransaction(UserTransaction userTransaction)
          Set the JTA UserTransaction to use as direct reference.
 void setUserTransactionName(String userTransactionName)
          Set the JNDI name of the JTA UserTransaction.
protected  boolean shouldCommitOnGlobalRollbackOnly()
          This implementation returns "true": a JTA commit will properly handle transactions that have been marked rollback-only at a global level.
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, invokeAfterCompletion, isGlobalRollbackOnParticipationFailure, isNestedTransactionAllowed, isRollbackOnCommitFailure, rollback, setGlobalRollbackOnParticipationFailure, 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 String DEFAULT_USER_TRANSACTION_NAME
Default JNDI location for the JTA UserTransaction. Many J2EE servers also provide support for the JTA TransactionManager interface there.

See Also:
setUserTransactionName(java.lang.String), setAutodetectTransactionManager(boolean), Constant Field Values

FALLBACK_TRANSACTION_MANAGER_NAMES

public static final String[] 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".

See Also:
setTransactionManagerName(java.lang.String), setAutodetectTransactionManager(boolean)
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(UserTransaction userTransaction)
Create a new JtaTransactionManager instance.

Parameters:
userTransaction - the JTA UserTransaction to use as direct reference

JtaTransactionManager

public JtaTransactionManager(UserTransaction userTransaction,
                             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

JtaTransactionManager

public JtaTransactionManager(TransactionManager transactionManager)
Create a new JtaTransactionManager instance.

Parameters:
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.


setJndiEnvironment

public void setJndiEnvironment(Properties jndiEnvironment)
Set the JNDI environment to use for JNDI lookups. Creates a JndiTemplate with the given environment settings.

See Also:
setJndiTemplate(org.springframework.jndi.JndiTemplate)

getJndiEnvironment

public Properties getJndiEnvironment()
Return the JNDI environment to use for JNDI lookups.


setUserTransaction

public void setUserTransaction(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 UserTransaction getUserTransaction()
Return the JTA UserTransaction that this transaction manager uses.


setUserTransactionName

public void setUserTransactionName(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)

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

public void setTransactionManager(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 TransactionManager getTransactionManager()
Return the JTA TransactionManager that this transaction manager uses.


setTransactionManagerName

public void setTransactionManagerName(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)

setAutodetectTransactionManager

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). Also checks the fallback JNDI locations "java:comp/TransactionManager" and "java:/TransactionManager". Will proceed without TransactionManager if none found.

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

See Also:
FALLBACK_TRANSACTION_MANAGER_NAMES

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 UserTransaction lookupUserTransaction(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 TransactionManager lookupTransactionManager(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)

retrieveUserTransaction

protected UserTransaction retrieveUserTransaction()
                                           throws TransactionSystemException
Allows subclasses to retrieve the JTA UserTransaction in a vendor-specific manner. Only called if no "userTransaction" or "userTransactionName" specified.

Default implementation simply returns null.

Returns:
the JTA UserTransaction handle to use, or null if none found
Throws:
TransactionSystemException - in case of errors
See Also:
setUserTransaction(javax.transaction.UserTransaction), setUserTransactionName(java.lang.String)

retrieveTransactionManager

protected TransactionManager retrieveTransactionManager()
                                                 throws TransactionSystemException
Allows subclasses to retrieve the JTA TransactionManager in a vendor-specific manner. Only called if no "transactionManager" or "transactionManagerName" specified.

Default implementation simply returns null.

Returns:
the JTA TransactionManager handle to use, or null if none found
Throws:
TransactionSystemException - in case of errors
See Also:
setTransactionManager(javax.transaction.TransactionManager), setTransactionManagerName(java.lang.String)

findTransactionManager

protected TransactionManager findTransactionManager(UserTransaction ut)
Find the JTA TransactionManager through autodetection: checking whether the UserTransaction object implements the TransactionManager, and checking the fallback JNDI locations.

Parameters:
ut - the JTA UserTransaction object
Returns:
the JTA TransactionManager reference, or null if not found
See Also:
FALLBACK_TRANSACTION_MANAGER_NAMES

doGetTransaction

protected Object 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.

Specified by:
doGetTransaction in class AbstractPlatformTransactionManager
Returns:
the current transaction object
See Also:
setCacheUserTransaction(boolean)

doGetJtaTransaction

protected JtaTransactionObject doGetJtaTransaction(UserTransaction ut)
Get a JTA transaction object for the given current UserTransaction.

Subclasses can override this to provide a JtaTransactionObject subclass, for example holding some additional JTA handle needed.

Parameters:
ut - the UserTransaction handle to use for the current transaction
Returns:
the JtaTransactionObject holding the UserTransaction

isExistingTransaction

protected boolean isExistingTransaction(Object transaction)
Description copied from class: AbstractPlatformTransactionManager
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).

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

Overrides:
isExistingTransaction in class AbstractPlatformTransactionManager
Parameters:
transaction - transaction object returned by doGetTransaction
Returns:
if there is an existing transaction
See Also:
AbstractPlatformTransactionManager.doGetTransaction()

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(Object transaction,
                       TransactionDefinition definition)
Description copied from class: AbstractPlatformTransactionManager
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.

Specified by:
doBegin in class AbstractPlatformTransactionManager
Parameters:
transaction - transaction object returned by doGetTransaction
definition - TransactionDefinition instance, describing propagation behavior, isolation level, read-only flag, timeout, and transaction name

doJtaBegin

protected void doJtaBegin(JtaTransactionObject txObject,
                          TransactionDefinition definition)
                   throws NotSupportedException,
                          SystemException
Perform a JTA begin on the JTA UserTransaction or TransactionManager.

This implementation only supports standard JTA functionality: that is, no per-transaction isolation levels and no transaction names. Can be overridden in subclasses, for specific JTA implementations.

Calls applyIsolationLevel and applyTimeout before invoking the UserTransaction's begin method.

Parameters:
txObject - the JtaTransactionObject containing the UserTransaction
definition - TransactionDefinition instance, describing propagation behavior, isolation level, read-only flag, timeout, and transaction name
Throws:
NotSupportedException - if thrown by JTA methods
SystemException - if thrown by JTA methods
See Also:
getUserTransaction(), getTransactionManager(), applyIsolationLevel(org.springframework.transaction.jta.JtaTransactionObject, int), applyTimeout(org.springframework.transaction.jta.JtaTransactionObject, int), JtaTransactionObject.getUserTransaction(), UserTransaction.setTransactionTimeout(int), UserTransaction.begin()

applyIsolationLevel

protected void applyIsolationLevel(JtaTransactionObject txObject,
                                   int isolationLevel)
                            throws InvalidIsolationLevelException,
                                   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, as alternative to overriding the full doJtaBegin method.

Parameters:
txObject - the JtaTransactionObject containing the UserTransaction
isolationLevel - isolation level taken from transaction definition
Throws:
InvalidIsolationLevelException - if the given isolation level cannot be applied
SystemException - if thrown by the JTA implementation
See Also:
doJtaBegin(org.springframework.transaction.jta.JtaTransactionObject, org.springframework.transaction.TransactionDefinition), JtaTransactionObject.getUserTransaction(), getTransactionManager()

applyTimeout

protected void applyTimeout(JtaTransactionObject txObject,
                            int timeout)
                     throws SystemException
Apply the given transaction timeout. Default implementation will call setTransactionTimeout for a non-default timeout value.

Parameters:
txObject - the JtaTransactionObject containing the UserTransaction
timeout - timeout value taken from transaction definition
Throws:
SystemException - if thrown by the JTA implementation
See Also:
doJtaBegin(org.springframework.transaction.jta.JtaTransactionObject, org.springframework.transaction.TransactionDefinition), JtaTransactionObject.getUserTransaction(), UserTransaction.setTransactionTimeout(int)

doSuspend

protected Object doSuspend(Object transaction)
Description copied from class: AbstractPlatformTransactionManager
Suspend the resources of the current transaction. Transaction synchronization will already have been suspended.

Default implementation throws a TransactionSuspensionNotSupportedException, assuming that transaction suspension is generally not supported.

Overrides:
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 Object doJtaSuspend(JtaTransactionObject txObject)
                       throws SystemException
Perform a JTA suspend on the JTA TransactionManager.

Can be overridden in subclasses, for specific JTA implementations.

Parameters:
txObject - the JtaTransactionObject containing the UserTransaction
Returns:
the suspended JTA Transaction object
Throws:
SystemException - if thrown by JTA methods
See Also:
getTransactionManager(), TransactionManager.suspend()

doResume

protected void doResume(Object transaction,
                        Object suspendedResources)
Description copied from class: AbstractPlatformTransactionManager
Resume the resources of the current transaction. Transaction synchronization will be resumed afterwards.

Default implementation throws a TransactionSuspensionNotSupportedException, assuming that transaction suspension is generally not supported.

Overrides:
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(JtaTransactionObject txObject,
                           Object suspendedTransaction)
                    throws InvalidTransactionException,
                           SystemException
Perform a JTA resume on the JTA TransactionManager.

Can be overridden in subclasses, for specific JTA implementations.

Parameters:
txObject - the JtaTransactionObject containing the UserTransaction
suspendedTransaction - the suspended JTA Transaction object
Throws:
InvalidTransactionException - if thrown by JTA methods
SystemException - if thrown by JTA methods
See Also:
getTransactionManager(), TransactionManager.resume(javax.transaction.Transaction)

shouldCommitOnGlobalRollbackOnly

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

Overrides:
shouldCommitOnGlobalRollbackOnly in class AbstractPlatformTransactionManager
See Also:
AbstractPlatformTransactionManager.doCommit(org.springframework.transaction.support.DefaultTransactionStatus), DefaultTransactionStatus.isGlobalRollbackOnly(), AbstractTransactionStatus.isLocalRollbackOnly(), TransactionStatus.setRollbackOnly(), UnexpectedRollbackException, UserTransaction.commit(), RollbackException

doCommit

protected void doCommit(DefaultTransactionStatus status)
Description copied from class: AbstractPlatformTransactionManager
Perform an actual commit of the given transaction.

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.

Specified by:
doCommit in class AbstractPlatformTransactionManager
Parameters:
status - the status representation of the transaction
See Also:
DefaultTransactionStatus.getTransaction()

doRollback

protected void doRollback(DefaultTransactionStatus status)
Description copied from class: AbstractPlatformTransactionManager
Perform an actual rollback of the given transaction.

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.

Specified by:
doRollback in class AbstractPlatformTransactionManager
Parameters:
status - the status representation of the transaction
See Also:
DefaultTransactionStatus.getTransaction()

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 participates in an existing one.

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

Overrides:
doSetRollbackOnly in class AbstractPlatformTransactionManager
Parameters:
status - the status representation of the transaction

registerAfterCompletionWithExistingTransaction

protected void registerAfterCompletionWithExistingTransaction(Object transaction,
                                                              List synchronizations)
Description copied from class: AbstractPlatformTransactionManager
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.

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.

Overrides:
registerAfterCompletionWithExistingTransaction in class AbstractPlatformTransactionManager
Parameters:
transaction - transaction object returned by doGetTransaction
synchronizations - List of TransactionSynchronization objects
See Also:
AbstractPlatformTransactionManager.invokeAfterCompletion(java.util.List, int), TransactionSynchronization.afterCompletion(int), TransactionSynchronization.STATUS_UNKNOWN

doRegisterAfterCompletionWithJtaTransaction

protected void doRegisterAfterCompletionWithJtaTransaction(JtaTransactionObject txObject,
                                                           List synchronizations)
                                                    throws RollbackException,
                                                           SystemException
Register a JTA synchronization on the JTA TransactionManager, for calling afterCompletion on the given Spring TransactionSynchronizations.

Can be overridden in subclasses, for specific JTA implementations.

Parameters:
synchronizations - List of TransactionSynchronization objects
Throws:
RollbackException - if thrown by JTA methods
SystemException - if thrown by JTA methods
See Also:
getTransactionManager(), Transaction.registerSynchronization(javax.transaction.Synchronization), AbstractPlatformTransactionManager.invokeAfterCompletion(java.util.List, int)


Copyright (c) 2002-2006 The Spring Framework Project.