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

org.springframework.transaction.jta

## Class WebSphereUowTransactionManager

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

- All Implemented Interfaces:
    Serializable, InitializingBean, TransactionFactory, PlatformTransactionManager, CallbackPreferringPlatformTransactionManager

      public class WebSphereUowTransactionManager
      extends JtaTransactionManager
      implements CallbackPreferringPlatformTransactionManager

  WebSphere-specific PlatformTransactionManager implementation that delegates to a `UOWManager` instance, obtained from WebSphere's JNDI environment. This allows Spring to leverage the full power of the WebSphere transaction coordinator, including transaction suspension, in a manner that is perfectly compliant with officially supported WebSphere API.

  The `CallbackPreferringPlatformTransactionManager` interface implemented by this class indicates that callers should preferably pass in a `TransactionCallback` through the `execute(org.springframework.transaction.TransactionDefinition, org.springframework.transaction.support.TransactionCallback<T>)` method, which will be handled through the callback-based WebSphere UOWManager API instead of through standard JTA API (UserTransaction / TransactionManager). This avoids the use of the non-public `javax.transaction.TransactionManager` API on WebSphere, staying within supported WebSphere API boundaries.

  This transaction manager implementation derives from Spring's standard `JtaTransactionManager`, inheriting the capability to support programmatic transaction demarcation via `getTransaction` / `commit` / `rollback` calls through a JTA UserTransaction handle, for callers that do not use the TransactionCallback-based `execute(org.springframework.transaction.TransactionDefinition, org.springframework.transaction.support.TransactionCallback<T>)` method. However, transaction suspension is not supported in this `getTransaction` style (unless you explicitly specify a `JtaTransactionManager.setTransactionManager(javax.transaction.TransactionManager)` reference, despite the official WebSphere recommendations). Use the `execute(org.springframework.transaction.TransactionDefinition, org.springframework.transaction.support.TransactionCallback<T>)` style for any code that might require transaction suspension.

  This transaction manager is compatible with WebSphere 6.1.0.9 and above. The default JNDI location for the UOWManager is "java:comp/websphere/UOWManager". If the location happens to differ according to your WebSphere documentation, simply specify the actual location through this transaction manager's "uowManagerName" bean property.

  Since:
    2.5
  Author:
    Juergen Hoeller
  See Also:
    `setUowManager(com.ibm.wsspi.uow.UOWManager)`, `setUowManagerName(java.lang.String)`, `UOWManager`, Serialized Form

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.springframework.transaction.support.AbstractPlatformTransactionManager

      `AbstractPlatformTransactionManager.SuspendedResourcesHolder`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `DEFAULT_UOW_MANAGER_NAME` Default JNDI location for the WebSphere UOWManager.

    - ### Fields inherited from class org.springframework.transaction.jta.JtaTransactionManager

      `DEFAULT_TRANSACTION_SYNCHRONIZATION_REGISTRY_NAME, DEFAULT_USER_TRANSACTION_NAME, FALLBACK_TRANSACTION_MANAGER_NAMES`

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

      `logger, SYNCHRONIZATION_ALWAYS, SYNCHRONIZATION_NEVER, SYNCHRONIZATION_ON_ACTUAL_TRANSACTION`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `WebSphereUowTransactionManager()` Create a new WebSphereUowTransactionManager.
    `WebSphereUowTransactionManager(com.ibm.wsspi.uow.UOWManager uowManager)` Create a new WebSphereUowTransactionManager for the given UOWManager.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `afterPropertiesSet()` Initialize the UserTransaction as well as the TransactionManager handle.
    `protected void` | `doRegisterAfterCompletionWithJtaTransaction(JtaTransactionObject txObject, List<TransactionSynchronization> synchronizations)` Registers the synchronizations as interposed JTA Synchronization on the UOWManager.
    `<T> T` | `execute(TransactionDefinition definition, TransactionCallback<T> callback)` Execute the action specified by the given callback object within a transaction.
    `protected com.ibm.wsspi.uow.UOWManager` | `lookupDefaultUowManager()` Obtain the WebSphere UOWManager from the default JNDI location "java:comp/websphere/UOWManager".
    `protected com.ibm.wsspi.uow.UOWManager` | `lookupUowManager(String uowManagerName)` Look up the WebSphere UOWManager in JNDI via the configured name.
    `void` | `setUowManager(com.ibm.wsspi.uow.UOWManager uowManager)` Set the WebSphere UOWManager to use as direct reference.
    `void` | `setUowManagerName(String uowManagerName)` Set the JNDI name of the WebSphere UOWManager.
    `boolean` | `supportsResourceAdapterManagedTransactions()` Returns `true` since WebSphere ResourceAdapters (as exposed in JNDI) implicitly perform transaction enlistment if the MessageEndpointFactory's `isDeliveryTransacted` method returns `true`.

    - ### Methods inherited from class org.springframework.transaction.jta.JtaTransactionManager

      `applyIsolationLevel, applyTimeout, buildUserTransaction, checkUserTransactionAndTransactionManager, createTransaction, doBegin, doCommit, doGetJtaTransaction, doGetTransaction, doJtaBegin, doJtaResume, doJtaSuspend, doResume, doRollback, doSetRollbackOnly, doSuspend, findTransactionManager, findTransactionSynchronizationRegistry, findUserTransaction, getJndiEnvironment, getJndiTemplate, getTransactionManager, getUserTransaction, initTransactionSynchronizationRegistry, initUserTransactionAndTransactionManager, isExistingTransaction, lookupTransactionManager, lookupTransactionSynchronizationRegistry, lookupUserTransaction, registerAfterCompletionWithExistingTransaction, retrieveTransactionManager, retrieveTransactionSynchronizationRegistry, retrieveUserTransaction, setAllowCustomIsolationLevels, setAutodetectTransactionManager, setAutodetectUserTransaction, setCacheUserTransaction, setJndiEnvironment, setJndiTemplate, setTransactionManager, setTransactionManagerName, setTransactionSynchronizationRegistryName, setUserTransaction, setUserTransactionName, shouldCommitOnGlobalRollbackOnly, useSavepointForNestedTransaction`

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

      `commit, determineTimeout, doCleanupAfterCompletion, getDefaultTimeout, getTransaction, getTransactionSynchronization, invokeAfterCompletion, isFailEarlyOnGlobalRollbackOnly, isGlobalRollbackOnParticipationFailure, isNestedTransactionAllowed, isRollbackOnCommitFailure, isValidateExistingTransaction, newTransactionStatus, prepareForCommit, prepareSynchronization, prepareTransactionStatus, resume, rollback, setDefaultTimeout, setFailEarlyOnGlobalRollbackOnly, setGlobalRollbackOnParticipationFailure, setNestedTransactionAllowed, setRollbackOnCommitFailure, setTransactionSynchronization, setTransactionSynchronizationName, setValidateExistingTransaction, suspend, triggerBeforeCommit, triggerBeforeCompletion`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface org.springframework.transaction.PlatformTransactionManager

      `commit, getTransaction, rollback`

- - ### Field Detail

    - #### DEFAULT_UOW_MANAGER_NAME

          public static final String DEFAULT_UOW_MANAGER_NAME

      Default JNDI location for the WebSphere UOWManager.
      See Also:
        `setUowManagerName(java.lang.String)`, Constant Field Values

  - ### Constructor Detail

    - #### WebSphereUowTransactionManager

          public WebSphereUowTransactionManager()

      Create a new WebSphereUowTransactionManager.

    - #### WebSphereUowTransactionManager

          public WebSphereUowTransactionManager(com.ibm.wsspi.uow.UOWManager uowManager)

      Create a new WebSphereUowTransactionManager for the given UOWManager.
      Parameters:
        `uowManager` - the WebSphere UOWManager to use as direct reference

  - ### Method Detail

    - #### setUowManager

          public void setUowManager(com.ibm.wsspi.uow.UOWManager uowManager)

      Set the WebSphere UOWManager to use as direct reference.

      Typically just used for test setups; in a J2EE environment, the UOWManager will always be fetched from JNDI.

      See Also:
        `JtaTransactionManager.setUserTransactionName(java.lang.String)`

    - #### setUowManagerName

          public void setUowManagerName(String uowManagerName)

      Set the JNDI name of the WebSphere UOWManager. The default "java:comp/websphere/UOWManager" is used if not set.
      See Also:
        `JtaTransactionManager.DEFAULT_USER_TRANSACTION_NAME`, `setUowManager(com.ibm.wsspi.uow.UOWManager)`

    - #### afterPropertiesSet

          public void afterPropertiesSet()
                                  throws TransactionSystemException

      Description copied from class: `JtaTransactionManager`
      Initialize the UserTransaction as well as the TransactionManager handle.
      Specified by:
        `afterPropertiesSet` in interface `InitializingBean`
      Overrides:
        `afterPropertiesSet` in class `JtaTransactionManager`
      Throws:
        `TransactionSystemException`
      See Also:
        `JtaTransactionManager.initUserTransactionAndTransactionManager()`

    - #### lookupUowManager

          protected com.ibm.wsspi.uow.UOWManager lookupUowManager(String uowManagerName)
                                                           throws TransactionSystemException

      Look up the WebSphere UOWManager in JNDI via the configured name.
      Parameters:
        `uowManagerName` - the JNDI name of the UOWManager
      Returns:
        the UOWManager object
      Throws:
        `TransactionSystemException` - if the JNDI lookup failed
      See Also:
        `JtaTransactionManager.setJndiTemplate(org.springframework.jndi.JndiTemplate)`, `setUowManagerName(java.lang.String)`

    - #### lookupDefaultUowManager

          protected com.ibm.wsspi.uow.UOWManager lookupDefaultUowManager()
                                                                  throws TransactionSystemException

      Obtain the WebSphere UOWManager from the default JNDI location "java:comp/websphere/UOWManager".
      Returns:
        the UOWManager object
      Throws:
        `TransactionSystemException` - if the JNDI lookup failed
      See Also:
        `JtaTransactionManager.setJndiTemplate(org.springframework.jndi.JndiTemplate)`

    - #### doRegisterAfterCompletionWithJtaTransaction

          protected void doRegisterAfterCompletionWithJtaTransaction(JtaTransactionObject txObject,
                                                         List<TransactionSynchronization> synchronizations)

      Registers the synchronizations as interposed JTA Synchronization on the UOWManager.
      Overrides:
        `doRegisterAfterCompletionWithJtaTransaction` in class `JtaTransactionManager`
      Parameters:
        `txObject` - the current transaction object
        `synchronizations` - List of TransactionSynchronization objects
      See Also:
        `JtaTransactionManager.getTransactionManager()`, `Transaction.registerSynchronization(javax.transaction.Synchronization)`, `TransactionSynchronizationRegistry.registerInterposedSynchronization(javax.transaction.Synchronization)`

    - #### supportsResourceAdapterManagedTransactions

          public boolean supportsResourceAdapterManagedTransactions()

      Returns `true` since WebSphere ResourceAdapters (as exposed in JNDI) implicitly perform transaction enlistment if the MessageEndpointFactory's `isDeliveryTransacted` method returns `true`. In that case we'll simply skip the `JtaTransactionManager.createTransaction(java.lang.String, int)` call.
      Specified by:
        `supportsResourceAdapterManagedTransactions` in interface `TransactionFactory`
      Overrides:
        `supportsResourceAdapterManagedTransactions` in class `JtaTransactionManager`
      See Also:
        `MessageEndpointFactory.isDeliveryTransacted(java.lang.reflect.Method)`, `AbstractMessageEndpointFactory`, `TransactionFactory.createTransaction(java.lang.String, int)`

    - #### execute

          public <T> T execute(TransactionDefinition definition,
                      TransactionCallback<T> callback)
                    throws TransactionException

      Description copied from interface: `CallbackPreferringPlatformTransactionManager`
      Execute the action specified by the given callback object within a transaction.

      Allows for returning a result object created within the transaction, that is, a domain object or a collection of domain objects. A RuntimeException thrown by the callback is treated as a fatal exception that enforces a rollback. Such an exception gets propagated to the caller of the template.

      Specified by:
        `execute` in interface `CallbackPreferringPlatformTransactionManager`
      Parameters:
        `definition` - the definition for the transaction to wrap the callback in
        `callback` - the callback object that specifies the transactional action
      Returns:
        a result object returned by the callback, or `null` if none
      Throws:
        `TransactionException` - in case of initialization, rollback, or system errors