org.springframework.transaction.support
Class TransactionSynchronizationManager

java.lang.Object
  org.springframework.transaction.support.TransactionSynchronizationManager

public abstract class TransactionSynchronizationManager
extends Object

Central helper that manages resources and transaction synchronizations per thread. To be used by resource management code but not by typical application code.

Supports one resource per key without overwriting, that is, a resource needs to be removed before a new one can be set for the same key. Supports a list of transaction synchronizations if synchronization is active.

Resource management code should check for thread-bound resources, e.g. JDBC Connections or Hibernate Sessions, via getResource. Such code is normally not supposed to bind resources to threads, as this is the responsibility of transaction managers. A further option is to lazily bind on first use if transaction synchronization is active, for performing transactions that span an arbitrary number of resources.

Transaction synchronization must be activated and deactivated by a transaction manager via initSynchronization and clearSynchronization. This is automatically supported by AbstractPlatformTransactionManager, and thus by all standard Spring transaction managers, like DataSourceTransactionManager and JtaTransactionManager.

Resource management code should only register synchronizations when this manager is active, which can be checked via isSynchronizationActive; it should perform immediate resource cleanup else. If transaction synchronization isn't active, there is either no current transaction, or the transaction manager doesn't support transaction synchronizations.

Synchronization is for example used to always return the same resources like JDBC Connections or Hibernate Sessions within a JTA transaction, for any given DataSource or SessionFactory. In the Hibernate case, the afterCompletion Session close calls allow for proper transactional JVM-level caching even without a custom TransactionManagerLookup in Hibernate configuration.

Since:

02.06.2003

Author:

Juergen Hoeller

See Also:

isSynchronizationActive(), registerSynchronization(org.springframework.transaction.support.TransactionSynchronization), TransactionSynchronization, AbstractPlatformTransactionManager, DataSourceTransactionManager, JtaTransactionManager, DataSourceUtils.getConnection(javax.sql.DataSource), SessionFactoryUtils.getSession(net.sf.hibernate.SessionFactory, boolean), PersistenceManagerFactoryUtils.getPersistenceManager(javax.jdo.PersistenceManagerFactory, boolean)

Constructor Summary

TransactionSynchronizationManager()

Method Summary

static void	bindResource(Object key, Object value) Bind the given resource for the given key to the current thread.
static void	clearSynchronization() Deactivate transaction synchronization for the current thread.
static String	getCurrentTransactionName() Return the name of the current transaction, or null if none set.
static Object	getResource(Object key) Retrieve a resource for the given key that is bound to the current thread.
static Map	getResourceMap() Return all resources that are bound to the current thread.
static List	getSynchronizations() Return an unmodifiable snapshot list of all registered synchronizations for the current thread.
static boolean	hasResource(Object key) Check if there is a resource for the given key bound to the current thread.
static void	initSynchronization() Activate transaction synchronization for the current thread.
static boolean	isActualTransactionActive() Return whether there currently is an actual transaction active.
static boolean	isCurrentTransactionReadOnly() Return whether the current transaction is marked as read-only.
static boolean	isSynchronizationActive() Return if transaction synchronization is active for the current thread.
static void	registerSynchronization(TransactionSynchronization synchronization) Register a new transaction synchronization for the current thread.
static void	setActualTransactionActive(boolean active) Expose whether there currently is an actual transaction active.
static void	setCurrentTransactionName(String name) Expose the name of the current transaction, if any.
static void	setCurrentTransactionReadOnly(boolean readOnly) Expose a read-only flag for the current transaction.
static Object	unbindResource(Object key) Unbind a resource for the given key from the current thread.

Methods inherited from class java.lang.Object

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

Constructor Detail

TransactionSynchronizationManager

public TransactionSynchronizationManager()

Method Detail

getResourceMap

public static Map getResourceMap()

Return all resources that are bound to the current thread.

Mainly for debugging purposes. Resource managers should always invoke hasResource for a specific resource key that they are interested in.

Returns:

Map with resource keys and resource objects, or empty Map if currently none bound

See Also:

hasResource(java.lang.Object)

hasResource

public static boolean hasResource(Object key)

Check if there is a resource for the given key bound to the current thread.

Parameters:

key - key to check

Returns:

if there is a value bound to the current thread

getResource

public static Object getResource(Object key)

Retrieve a resource for the given key that is bound to the current thread.

Parameters:

key - key to check

Returns:

a value bound to the current thread, or null if none

bindResource

public static void bindResource(Object key,
                                Object value)
                         throws IllegalStateException

Bind the given resource for the given key to the current thread.

Parameters:

key - key to bind the value to

value - value to bind

Throws:

IllegalStateException - if there is already a value bound to the thread

unbindResource

public static Object unbindResource(Object key)
                             throws IllegalStateException

Unbind a resource for the given key from the current thread.

Parameters:

key - key to check

Returns:

the previously bound value

Throws:

IllegalStateException - if there is no value bound to the thread

isSynchronizationActive

public static boolean isSynchronizationActive()

Return if transaction synchronization is active for the current thread. Can be called before register to avoid unnecessary instance creation.

See Also:

registerSynchronization(org.springframework.transaction.support.TransactionSynchronization)

initSynchronization

public static void initSynchronization()
                                throws IllegalStateException

Activate transaction synchronization for the current thread. Called by a transaction manager on transaction begin.

Throws:

IllegalStateException - if synchronization is already active

registerSynchronization

public static void registerSynchronization(TransactionSynchronization synchronization)
                                    throws IllegalStateException

Register a new transaction synchronization for the current thread. Typically called by resource management code.

Note that synchronizations can implement the Ordered interface. They will be executed in an order according to their order value (if any).

Throws:

IllegalStateException - if synchronization is not active

See Also:

Ordered

getSynchronizations

public static List getSynchronizations()
                                throws IllegalStateException

Return an unmodifiable snapshot list of all registered synchronizations for the current thread.

Returns:

unmodifiable List of TransactionSynchronization instances

Throws:

IllegalStateException - if synchronization is not active

See Also:

TransactionSynchronization

clearSynchronization

public static void clearSynchronization()
                                 throws IllegalStateException

Deactivate transaction synchronization for the current thread. Called by transaction manager on transaction cleanup.

Throws:

IllegalStateException - if synchronization is not active

setCurrentTransactionName

public static void setCurrentTransactionName(String name)

Expose the name of the current transaction, if any. Called by transaction manager on transaction begin and on cleanup.

Parameters:

name - the name of the transaction, or null to reset it

getCurrentTransactionName

public static String getCurrentTransactionName()

Return the name of the current transaction, or null if none set. To be called by resource management code for optimizations per use case, for example to optimize fetch strategies for specific named transactions.

setCurrentTransactionReadOnly

public static void setCurrentTransactionReadOnly(boolean readOnly)

Expose a read-only flag for the current transaction. Called by transaction manager on transaction begin and on cleanup.

Parameters:

readOnly - true to mark the current transaction as read-only; false to reset such a read-only marker

See Also:

TransactionDefinition.isReadOnly()

isCurrentTransactionReadOnly

public static boolean isCurrentTransactionReadOnly()

Return whether the current transaction is marked as read-only. To be called by resource management code when preparing a newly created resource (for example, a Hibernate Session).

Note that transaction synchronizations receive the read-only flag as argument for the beforeCommit callback, to be able to suppress change detection on commit. The present method is meant to be used for earlier read-only checks, for example to set the flush mode of a Hibernate Session to FlushMode.NEVER upfront.

See Also:

TransactionSynchronization.beforeCommit(boolean), Session.flush(), Session.setFlushMode(org.hibernate.FlushMode), FlushMode.NEVER

setActualTransactionActive

public static void setActualTransactionActive(boolean active)

Expose whether there currently is an actual transaction active. Called by transaction manager on transaction begin and on cleanup.

Parameters:

active - true to mark the current thread as being associated with an actual transaction; false to reset that marker

isActualTransactionActive

public static boolean isActualTransactionActive()

Return whether there currently is an actual transaction active. This indicates whether the current thread is associated with an actual transaction rather than just with active transaction synchronization.

To be called by resource management code that wants to discriminate between active transaction synchronization (with or without backing resource transaction; also on PROPAGATION_SUPPORTS) and an actual transaction being active (with backing resource transaction; on PROPAGATION_REQUIRES, PROPAGATION_REQUIRES_NEW, etc).

See Also:

isSynchronizationActive()