Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.springframework.transaction.jta
Class JtaTransactionManager

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

All Implemented Interfaces:
  Serializable, InitializingBean, TransactionFactory, PlatformTransactionManager

Direct Known Subclasses:
  OC4JJtaTransactionManager, WebLogicJtaTransactionManager, WebSphereUowTransactionManager

    public class JtaTransactionManager

extends AbstractPlatformTransactionManager
implements TransactionFactory, InitializingBean, Serializable

`PlatformTransactionManager` implementation for JTA, delegating to a backend JTA provider. This is typically used to delegate to a J2EE server's transaction coordinator, but may also be configured with a local JTA provider which is embedded within the application.

This transaction manager is appropriate for handling distributed transactions, i.e. transactions that span multiple resources, and for controlling transactions on application server resources (e.g. JDBC DataSources available in JNDI) in general. For a single JDBC DataSource, DataSourceTransactionManager is perfectly sufficient, and for accessing a single resource with Hibernate (including transactional cache), HibernateTransactionManager is appropriate, for example.

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, JDO etc 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.

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:

- "java:comp/UserTransaction" for Resin 2.x, Oracle OC4J (Orion), JOnAS (JOTM), BEA WebLogic
- "java:comp/TransactionManager" for Resin 3.x
- "java:appserver/TransactionManager" for GlassFish
- "java:pm/TransactionManager" for Borland Enterprise Server and Sun Application Server (Sun ONE 7 and later)
- "java:/TransactionManager" for JBoss Application Server

All of these cases are autodetected by JtaTransactionManager, provided that the "autodetectTransactionManager" flag is set to "true" (which it is by default).

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. As a consequence, Spring provides various vendor-specific PlatformTransactionManagers, which are recommended to be used if appropriate: `WebLogicJtaTransactionManager`, `WebSphereUowTransactionManager` and `OC4JJtaTransactionManager`. For all other J2EE servers, the standard JtaTransactionManager is sufficient.

Consider using Spring 2.5's `tx:jta-transaction-manager` configuration element for automatically picking the appropriate JTA platform transaction manager (automatically detecting WebLogic, WebSphere and OC4J).

This pure JtaTransactionManager supports timeouts but not per-transaction isolation levels. Custom subclasses may override `doJtaBegin(org.springframework.transaction.jta.JtaTransactionObject, org.springframework.transaction.TransactionDefinition)` for specific JTA extensions in order to provide this functionality; Spring includes corresponding `WebLogicJtaTransactionManager` and `OC4JJtaTransactionManager` classes, for BEA's WebLogic Server and Oracle's OC4J, respectively. Such adapters for specific J2EE transaction coordinators may also expose transaction names for monitoring; with standard JTA, transaction names will simply be ignored.

JTA 1.1 adds the TransactionSynchronizationRegistry facility, as public Java EE 5 API in addition to the standard JTA UserTransaction handle. As of Spring 2.5, this JtaTransactionManager autodetects the TransactionSynchronizationRegistry and uses it for registering Spring-managed synchronizations when participating in an existing JTA transaction (e.g. controlled by EJB CMT). If no TransactionSynchronizationRegistry is available (or the JTA 1.1 API isn't available), then such synchronizations will be registered via the (non-J2EE) JTA TransactionManager handle.

This class is serializable. However, active synchronizations do not survive serialization.

Since:
  24.03.2003
Author:
  Juergen Hoeller
See Also:
  `UserTransaction`, `TransactionManager`, `TransactionSynchronizationRegistry`, `setUserTransactionName(java.lang.String)`, `setUserTransaction(javax.transaction.UserTransaction)`, `setTransactionManagerName(java.lang.String)`, `setTransactionManager(javax.transaction.TransactionManager)`, `JotmFactoryBean`, `WebSphereTransactionManagerFactoryBean`, `WebLogicJtaTransactionManager`, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.springframework.transaction.support.AbstractPlatformTransactionManager
`AbstractPlatformTransactionManager.SuspendedResourcesHolder`

Field Summary
`static String` | `DEFAULT_TRANSACTION_SYNCHRONIZATION_REGISTRY_NAME` Standard Java EE 5 JNDI location for the JTA TransactionSynchronizationRegistry.
`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()` Initialize the UserTransaction as well as the TransactionManager handle.
`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 UserTransaction` | `buildUserTransaction(TransactionManager transactionManager)` Build a UserTransaction handle based on the given TransactionManager.
`protected void` | `checkUserTransactionAndTransactionManager()` Check the UserTransaction as well as the TransactionManager handle, assuming standard JTA requirements.
`Transaction` | `createTransaction(String name, int timeout)` Create an active Transaction object based on the given name and 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.
`protected Object` | `findTransactionSynchronizationRegistry(UserTransaction ut, TransactionManager tm)` Find the JTA 1.1 TransactionSynchronizationRegistry through autodetection: checking whether the UserTransaction object or TransactionManager object implements it, and checking Java EE 5's standard JNDI location.
`protected UserTransaction` | `findUserTransaction()` Find the JTA UserTransaction through a default JNDI lookup: "java:comp/UserTransaction".
`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 void` | `initTransactionSynchronizationRegistry()` Initialize the JTA 1.1 TransactionSynchronizationRegistry, if available.
`protected void` | `initUserTransactionAndTransactionManager()` Initialize the UserTransaction as well as the TransactionManager handle.
`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 Object` | `lookupTransactionSynchronizationRegistry(String registryName)` Look up the JTA 1.1 TransactionSynchronizationRegistry 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 Object` | `retrieveTransactionSynchronizationRegistry()` Allows subclasses to retrieve the JTA 1.1 TransactionSynchronizationRegistry in a vendor-specific manner.
`protected UserTransaction` | `retrieveUserTransaction()` Allows subclasses to retrieve the JTA UserTransaction in a vendor-specific manner.
`void` | `setAllowCustomIsolationLevels(boolean allowCustomIsolationLevels)` Set whether to allow custom isolation levels to be specified.
`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` | `setAutodetectUserTransaction(boolean autodetectUserTransaction)` Set whether to autodetect the JTA UserTransaction at its default JNDI location "java:comp/UserTransaction", as specified by J2EE.
`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` | `setTransactionSynchronizationRegistryName(String transactionSynchronizationRegistryName)` Set the JNDI name of the JTA 1.1 TransactionSynchronizationRegistry.
`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, determineTimeout, doCleanupAfterCompletion, getDefaultTimeout, getTransaction, getTransactionSynchronization, invokeAfterCompletion, isFailEarlyOnGlobalRollbackOnly, isGlobalRollbackOnParticipationFailure, isNestedTransactionAllowed, isRollbackOnCommitFailure, isValidateExistingTransaction, newTransactionStatus, prepareForCommit, 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`

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)`

### DEFAULT_TRANSACTION_SYNCHRONIZATION_REGISTRY_NAME

    public static final String DEFAULT_TRANSACTION_SYNCHRONIZATION_REGISTRY_NAME

  Standard Java EE 5 JNDI location for the JTA TransactionSynchronizationRegistry. Autodetected when available.

  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(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)`, `setAutodetectUserTransaction(boolean)`

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

  Note that the UserTransaction will be autodetected at the J2EE default location "java:comp/UserTransaction" if not specified explicitly.

  See Also:
    `DEFAULT_USER_TRANSACTION_NAME`, `setUserTransaction(javax.transaction.UserTransaction)`, `setAutodetectUserTransaction(boolean)`

### setAutodetectUserTransaction

    public void setAutodetectUserTransaction(boolean autodetectUserTransaction)

  Set whether to autodetect the JTA UserTransaction at its default JNDI location "java:comp/UserTransaction", as specified by J2EE. Will proceed without UserTransaction if none found.

  Default is "true", autodetecting the UserTransaction unless it has been specified explicitly. Turn this flag off to allow for JtaTransactionManager operating against the TransactionManager only, despite a default UserTransaction being available.

  See Also:
    `DEFAULT_USER_TRANSACTION_NAME`

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

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

### 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, as well as autodetected at various well-known fallback JNDI locations.

  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, as well as autodetected at various well-known fallback JNDI locations.

  See Also:
    `setTransactionManager(javax.transaction.TransactionManager)`, `setAutodetectTransactionManager(boolean)`

### 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", autodetecting the TransactionManager unless it has been specified explicitly. 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`

### setTransactionSynchronizationRegistryName

    public void setTransactionSynchronizationRegistryName(String transactionSynchronizationRegistryName)

  Set the JNDI name of the JTA 1.1 TransactionSynchronizationRegistry.

  Note that the TransactionSynchronizationRegistry will be autodetected at the Java EE 5 default location "java:comp/TransactionSynchronizationRegistry" if not specified explicitly.

  See Also:
    `DEFAULT_TRANSACTION_SYNCHRONIZATION_REGISTRY_NAME`

### setAllowCustomIsolationLevels

    public void setAllowCustomIsolationLevels(boolean allowCustomIsolationLevels)

  Set whether to allow custom isolation levels to be specified.

  Default is "false", throwing an exception if a non-default isolation level is specified for a transaction. Turn this flag on if affected resource adapters check the thread-bound transaction context and apply the specified isolation levels individually (e.g. through a IsolationLevelDataSourceRouter).

  See Also:
    `IsolationLevelDataSourceRouter`

### afterPropertiesSet

    public void afterPropertiesSet()
                            throws TransactionSystemException

  Initialize the UserTransaction as well as the TransactionManager handle.

  Specified by:
    `afterPropertiesSet` in interface `InitializingBean`
  Throws:
    `TransactionSystemException`
  See Also:
    `initUserTransactionAndTransactionManager()`

### initUserTransactionAndTransactionManager

    protected void initUserTransactionAndTransactionManager()
                                                     throws TransactionSystemException

  Initialize the UserTransaction as well as the TransactionManager handle.

  Throws:
    `TransactionSystemException` - if initialization failed

### checkUserTransactionAndTransactionManager

    protected void checkUserTransactionAndTransactionManager()
                                                      throws IllegalStateException

  Check the UserTransaction as well as the TransactionManager handle, assuming standard JTA requirements.

  Throws:
    `IllegalStateException` - if no sufficient handles are available

### initTransactionSynchronizationRegistry

    protected void initTransactionSynchronizationRegistry()

  Initialize the JTA 1.1 TransactionSynchronizationRegistry, if available.

  To be called after `initUserTransactionAndTransactionManager()`, since it may check the UserTransaction and TransactionManager handles.

  Throws:
    `TransactionSystemException` - if initialization failed

### buildUserTransaction

    protected UserTransaction buildUserTransaction(TransactionManager transactionManager)

  Build a UserTransaction handle based on the given TransactionManager.

  Parameters:
    `transactionManager` - the TransactionManager
  Returns:
    a corresponding UserTransaction handle

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

### lookupTransactionSynchronizationRegistry

    protected Object lookupTransactionSynchronizationRegistry(String registryName)
                                                       throws TransactionSystemException

  Look up the JTA 1.1 TransactionSynchronizationRegistry in JNDI via the configured name.

  Can be overridden in subclasses to provide a different TransactionManager object.

  Parameters:
    `registryName` - the JNDI name of the TransactionSynchronizationRegistry
  Returns:
    the TransactionSynchronizationRegistry object
  Throws:
    `TransactionSystemException` - if the JNDI lookup failed
  See Also:
    `setJndiTemplate(org.springframework.jndi.JndiTemplate)`, `setTransactionSynchronizationRegistryName(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.

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

  The 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)`

### retrieveTransactionSynchronizationRegistry

    protected Object retrieveTransactionSynchronizationRegistry()
                                                         throws TransactionSystemException

  Allows subclasses to retrieve the JTA 1.1 TransactionSynchronizationRegistry in a vendor-specific manner.

  The default implementation simply returns `null`.

  Returns:
    the JTA TransactionSynchronizationRegistry handle to use, or `null` if none found
  Throws:
    `TransactionSystemException` - in case of errors

### findUserTransaction

    protected UserTransaction findUserTransaction()

  Find the JTA UserTransaction through a default JNDI lookup: "java:comp/UserTransaction".

  Returns:
    the JTA UserTransaction reference, or `null` if not found
  See Also:
    `DEFAULT_USER_TRANSACTION_NAME`

### 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`

### findTransactionSynchronizationRegistry

    protected Object findTransactionSynchronizationRegistry(UserTransaction ut,
                                                            TransactionManager tm)
                                                     throws TransactionSystemException

  Find the JTA 1.1 TransactionSynchronizationRegistry through autodetection: checking whether the UserTransaction object or TransactionManager object implements it, and checking Java EE 5's standard JNDI location.

  The default implementation simply returns `null`.

  Parameters:
    `ut` - the JTA UserTransaction object
    `tm` - the JTA TransactionManager object
  Returns:
    the JTA TransactionSynchronizationRegistry handle to use, or `null` if none found
  Throws:
    `TransactionSystemException` - in case of errors

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

  The default implementation returns `false`, assuming that 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. The 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(org.springframework.transaction.jta.JtaTransactionObject, org.springframework.transaction.TransactionDefinition)` 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. The default implementation will call `UserTransaction.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.

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

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

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

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

  The default implementation registers the synchronizations on the JTA 1.1 TransactionSynchronizationRegistry, if available, or on the JTA TransactionManager's current Transaction - again, if available. If none of the two is available, a warning will be logged.

  Can be overridden in subclasses, for specific JTA implementations.

  Parameters:
    `txObject` - the current transaction object
    `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)`, `TransactionSynchronizationRegistry.registerInterposedSynchronization(javax.transaction.Synchronization)`

### createTransaction

    public Transaction createTransaction(String name,
                                         int timeout)
                                  throws NotSupportedException,
                                         SystemException

  Description copied from interface: `TransactionFactory`
  Create an active Transaction object based on the given name and timeout.

  Specified by:
    `createTransaction` in interface `TransactionFactory`
  Parameters:
    `name` - the transaction name (may be `null`)
    `timeout` - the transaction timeout (may be -1 for the default timeout)
  Returns:
    the active Transaction object (never `null`)
  Throws:
    `NotSupportedException` - if the transaction manager does not support a transaction of the specified type
    `SystemException` - if the transaction managed failed to create the transaction

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2008 The Spring Framework.