TransactionSynchronizationManager (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

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, such as `JtaTransactionManager` and `DataSourceTransactionManager`.

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

  Synchronization is for example used to always return the same resources within a JTA transaction, e.g. a JDBC Connection or a Hibernate Session for any given DataSource or SessionFactory, respectively.

  Since:
    02.06.2003
  Author:
    Juergen Hoeller
  See Also:
    `isSynchronizationActive()`, `registerSynchronization(org.springframework.transaction.support.TransactionSynchronization)`, `TransactionSynchronization`, `AbstractPlatformTransactionManager.setTransactionSynchronization(int)`, `JtaTransactionManager`, `DataSourceTransactionManager`, `DataSourceUtils.getConnection(javax.sql.DataSource)`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `TransactionSynchronizationManager()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `bindResource(Object key, Object value)` Bind the given resource for the given key to the current thread.
    `static void` | `clear()` Clear the entire transaction synchronization state for the current thread: registered synchronizations as well as the various transaction characteristics.
    `static void` | `clearSynchronization()` Deactivate transaction synchronization for the current thread.
    `static Integer` | `getCurrentTransactionIsolationLevel()` Return the isolation level for the current transaction, if any.
    `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<Object,Object>` | `getResourceMap()` Return all resources that are bound to the current thread.
    `static List<TransactionSynchronization>` | `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` | `setCurrentTransactionIsolationLevel(Integer isolationLevel)` Expose an isolation level for the current transaction.
    `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.
    `static Object` | `unbindResourceIfPossible(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<Object,Object> 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:
        a Map with resource keys (usually the resource factory) and resource values (usually the active resource object), or an empty Map if there are currently no resources 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` - the key to check (usually the resource factory)
      Returns:
        if there is a value bound to the current thread
      See Also:
        `ResourceTransactionManager.getResourceFactory()`

    - #### getResource

          public static Object getResource(Object key)

      Retrieve a resource for the given key that is bound to the current thread.
      Parameters:
        `key` - the key to check (usually the resource factory)
      Returns:
        a value bound to the current thread (usually the active resource object), or `null` if none
      See Also:
        `ResourceTransactionManager.getResourceFactory()`

    - #### 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` - the key to bind the value to (usually the resource factory)
        `value` - the value to bind (usually the active resource object)
      Throws:
        `IllegalStateException` - if there is already a value bound to the thread
      See Also:
        `ResourceTransactionManager.getResourceFactory()`

    - #### unbindResource

          public static Object unbindResource(Object key)
                                       throws IllegalStateException

      Unbind a resource for the given key from the current thread.
      Parameters:
        `key` - the key to unbind (usually the resource factory)
      Returns:
        the previously bound value (usually the active resource object)
      Throws:
        `IllegalStateException` - if there is no value bound to the thread
      See Also:
        `ResourceTransactionManager.getResourceFactory()`

    - #### unbindResourceIfPossible

          public static Object unbindResourceIfPossible(Object key)

      Unbind a resource for the given key from the current thread.
      Parameters:
        `key` - the key to unbind (usually the resource factory)
      Returns:
        the previously bound value, or `null` if none bound

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

      Parameters:
        `synchronization` - the synchronization object to register
      Throws:
        `IllegalStateException` - if transaction synchronization is not active
      See Also:
        `Ordered`

    - #### getSynchronizations

          public static List<TransactionSynchronization> 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 the 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 the transaction manager on transaction begin and on cleanup.
      Parameters:
        `name` - the name of the transaction, or `null` to reset it
      See Also:
        `TransactionDefinition.getName()`

    - #### 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.
      See Also:
        `TransactionDefinition.getName()`

    - #### setCurrentTransactionReadOnly

          public static void setCurrentTransactionReadOnly(boolean readOnly)

      Expose a read-only flag for the current transaction. Called by the 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:
        `TransactionDefinition.isReadOnly()`, `TransactionSynchronization.beforeCommit(boolean)`

    - #### setCurrentTransactionIsolationLevel

          public static void setCurrentTransactionIsolationLevel(Integer isolationLevel)

      Expose an isolation level for the current transaction. Called by the transaction manager on transaction begin and on cleanup.
      Parameters:
        `isolationLevel` - the isolation level to expose, according to the JDBC Connection constants (equivalent to the corresponding Spring TransactionDefinition constants), or `null` to reset it
      See Also:
        `Connection.TRANSACTION_READ_UNCOMMITTED`, `Connection.TRANSACTION_READ_COMMITTED`, `Connection.TRANSACTION_REPEATABLE_READ`, `Connection.TRANSACTION_SERIALIZABLE`, `TransactionDefinition.ISOLATION_READ_UNCOMMITTED`, `TransactionDefinition.ISOLATION_READ_COMMITTED`, `TransactionDefinition.ISOLATION_REPEATABLE_READ`, `TransactionDefinition.ISOLATION_SERIALIZABLE`, `TransactionDefinition.getIsolationLevel()`

    - #### getCurrentTransactionIsolationLevel

          public static Integer getCurrentTransactionIsolationLevel()

      Return the isolation level for the current transaction, if any. To be called by resource management code when preparing a newly created resource (for example, a JDBC Connection).
      Returns:
        the currently exposed isolation level, according to the JDBC Connection constants (equivalent to the corresponding Spring TransactionDefinition constants), or `null` if none
      See Also:
        `Connection.TRANSACTION_READ_UNCOMMITTED`, `Connection.TRANSACTION_READ_COMMITTED`, `Connection.TRANSACTION_REPEATABLE_READ`, `Connection.TRANSACTION_SERIALIZABLE`, `TransactionDefinition.ISOLATION_READ_UNCOMMITTED`, `TransactionDefinition.ISOLATION_READ_COMMITTED`, `TransactionDefinition.ISOLATION_REPEATABLE_READ`, `TransactionDefinition.ISOLATION_SERIALIZABLE`, `TransactionDefinition.getIsolationLevel()`

    - #### setActualTransactionActive

          public static void setActualTransactionActive(boolean active)

      Expose whether there currently is an actual transaction active. Called by the 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()`

    - #### clear

          public static void clear()

      Clear the entire transaction synchronization state for the current thread: registered synchronizations as well as the various transaction characteristics.
      See Also:
        `clearSynchronization()`, `setCurrentTransactionName(java.lang.String)`, `setCurrentTransactionReadOnly(boolean)`, `setCurrentTransactionIsolationLevel(java.lang.Integer)`, `setActualTransactionActive(boolean)`