java.lang.Object | ||
↳ | org.springframework.transaction.support.AbstractPlatformTransactionManager | |
↳ | org.springframework.transaction.jta.JtaTransactionManager |
Known Direct Subclasses |
PlatformTransactionManager
implementation
for JTA, delegating to a backend JTA provider. This is typically used to delegate
to a Java EE 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.
For typical JTA transactions (REQUIRED, SUPPORTS, MANDATORY, NEVER), a plain JtaTransactionManager definition is all you need, portable across all Java EE servers. This corresponds to the functionality of the JTA UserTransaction, for which Java EE 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.
Transaction suspension (REQUIRES_NEW, NOT_SUPPORTED) is just available with a JTA TransactionManager being registered. Common TransactionManager locations 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 Java EE.
Almost all Java EE servers expose it, but do so as extension to EE. 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 Java EE servers, the standard JtaTransactionManager is sufficient.
This pure JtaTransactionManager class supports timeouts but not per-transaction
isolation levels. Custom subclasses may override the doJtaBegin(JtaTransactionObject, TransactionDefinition)
method 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 Java EE transaction coordinators may also expose transaction names for
monitoring; with standard JTA, transaction names will simply be ignored.
Consider using Spring's tx:jta-transaction-manager
configuration
element for automatically picking the appropriate JTA platform transaction manager
(automatically detecting WebLogic, WebSphere and OC4J).
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-EE) JTA TransactionManager handle.
This class is serializable. However, active synchronizations do not survive serialization.
setUserTransactionName(String)
setUserTransaction(UserTransaction)
setTransactionManagerName(String)
setTransactionManager(TransactionManager)
WebLogicJtaTransactionManager
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
String | DEFAULT_TRANSACTION_SYNCHRONIZATION_REGISTRY_NAME | Standard Java EE 5 JNDI location for the JTA TransactionSynchronizationRegistry. | |||||||||
String | DEFAULT_USER_TRANSACTION_NAME | Default JNDI location for the JTA UserTransaction. |
[Expand]
Inherited Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
org.springframework.transaction.support.AbstractPlatformTransactionManager
|
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
FALLBACK_TRANSACTION_MANAGER_NAMES | Fallback JNDI locations for the JTA TransactionManager. |
[Expand]
Inherited Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
org.springframework.transaction.support.AbstractPlatformTransactionManager
|
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Create a new JtaTransactionManager instance, to be configured as bean.
| |||||||||||
Create a new JtaTransactionManager instance.
| |||||||||||
Create a new JtaTransactionManager instance.
| |||||||||||
Create a new JtaTransactionManager instance.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Initialize the UserTransaction as well as the TransactionManager handle.
| |||||||||||
Create an active Transaction object based on the given name and timeout.
| |||||||||||
Return the JNDI environment to use for JNDI lookups.
| |||||||||||
Return the JndiTemplate used for JNDI lookups.
| |||||||||||
Return the JTA TransactionManager that this transaction manager uses.
| |||||||||||
Return the JTA UserTransaction that this transaction manager uses.
| |||||||||||
Set whether to allow custom isolation levels to be specified.
| |||||||||||
Set whether to autodetect a JTA UserTransaction object that implements
the JTA TransactionManager interface too (i.e.
| |||||||||||
Set whether to autodetect the JTA UserTransaction at its default
JNDI location "java:comp/UserTransaction", as specified by Java EE.
| |||||||||||
Set whether to cache the JTA UserTransaction object fetched from JNDI.
| |||||||||||
Set the JNDI environment to use for JNDI lookups.
| |||||||||||
Set the JndiTemplate to use for JNDI lookups.
| |||||||||||
Set the JTA TransactionManager to use as direct reference.
| |||||||||||
Set the JNDI name of the JTA TransactionManager.
| |||||||||||
Set the JNDI name of the JTA 1.1 TransactionSynchronizationRegistry.
| |||||||||||
Set the JTA UserTransaction to use as direct reference.
| |||||||||||
Set the JNDI name of the JTA UserTransaction.
| |||||||||||
Determine whether the underlying transaction manager supports XA transactions
managed by a resource adapter (i.e.
|
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Apply the given transaction isolation level.
| |||||||||||
Apply the given transaction timeout.
| |||||||||||
Build a UserTransaction handle based on the given TransactionManager.
| |||||||||||
Check the UserTransaction as well as the TransactionManager handle,
assuming standard JTA requirements.
| |||||||||||
Begin a new transaction with semantics according to the given transaction
definition.
| |||||||||||
Perform an actual commit of the given transaction.
| |||||||||||
Get a JTA transaction object for the given current UserTransaction.
| |||||||||||
This implementation returns a JtaTransactionObject instance for the
JTA UserTransaction.
| |||||||||||
Perform a JTA begin on the JTA UserTransaction or TransactionManager.
| |||||||||||
Perform a JTA resume on the JTA TransactionManager.
| |||||||||||
Perform a JTA suspend on the JTA TransactionManager.
| |||||||||||
Register a JTA synchronization on the JTA TransactionManager, for calling
afterCompletion on the given Spring TransactionSynchronizations. | |||||||||||
Resume the resources of the current transaction.
| |||||||||||
Perform an actual rollback of the given transaction.
| |||||||||||
Set the given transaction rollback-only.
| |||||||||||
Suspend the resources of the current transaction.
| |||||||||||
Find the JTA TransactionManager through autodetection: checking whether the
UserTransaction object implements the TransactionManager, and checking the
fallback JNDI locations.
| |||||||||||
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.
| |||||||||||
Find the JTA UserTransaction through a default JNDI lookup:
"java:comp/UserTransaction".
| |||||||||||
Initialize the JTA 1.1 TransactionSynchronizationRegistry, if available.
| |||||||||||
Initialize the UserTransaction as well as the TransactionManager handle.
| |||||||||||
Check if the given transaction object indicates an existing transaction
(that is, a transaction which has already started).
| |||||||||||
Look up the JTA TransactionManager in JNDI via the configured name.
| |||||||||||
Look up the JTA 1.1 TransactionSynchronizationRegistry in JNDI via the configured name.
| |||||||||||
Look up the JTA UserTransaction in JNDI via the configured name.
| |||||||||||
Register the given list of transaction synchronizations with the existing transaction.
| |||||||||||
Allows subclasses to retrieve the JTA TransactionManager in a vendor-specific manner.
| |||||||||||
Allows subclasses to retrieve the JTA 1.1 TransactionSynchronizationRegistry
in a vendor-specific manner.
| |||||||||||
Allows subclasses to retrieve the JTA UserTransaction in a vendor-specific manner.
| |||||||||||
This implementation returns "true": a JTA commit will properly handle
transactions that have been marked rollback-only at a global level.
| |||||||||||
This implementation returns false to cause a further invocation
of doBegin despite an already existing transaction.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
org.springframework.transaction.support.AbstractPlatformTransactionManager
| |||||||||||
From class
java.lang.Object
| |||||||||||
From interface
org.springframework.beans.factory.InitializingBean
| |||||||||||
From interface
org.springframework.transaction.PlatformTransactionManager
| |||||||||||
From interface
org.springframework.transaction.jta.TransactionFactory
|
Standard Java EE 5 JNDI location for the JTA TransactionSynchronizationRegistry. Autodetected when available.
Default JNDI location for the JTA UserTransaction. Many Java EE servers also provide support for the JTA TransactionManager interface there.
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".
Create a new JtaTransactionManager instance, to be configured as bean.
Invoke afterPropertiesSet
to activate the configuration.
Create a new JtaTransactionManager instance.
userTransaction | the JTA UserTransaction to use as direct reference |
---|
Create a new JtaTransactionManager instance.
userTransaction | the JTA UserTransaction to use as direct reference |
---|---|
transactionManager | the JTA TransactionManager to use as direct reference |
Create a new JtaTransactionManager instance.
transactionManager | the JTA TransactionManager to use as direct reference |
---|
Initialize the UserTransaction as well as the TransactionManager handle.
TransactionSystemException |
---|
Create an active Transaction object based on the given name and timeout.
name | the transaction name (may be null ) |
---|---|
timeout | the transaction timeout (may be -1 for the default timeout) |
null
)NotSupportedException | |
---|---|
SystemException |
Return the JTA TransactionManager that this transaction manager uses.
Return the JTA UserTransaction that this transaction manager uses.
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).
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.
Set whether to autodetect the JTA UserTransaction at its default JNDI location "java:comp/UserTransaction", as specified by Java EE. 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.
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.
Set the JNDI environment to use for JNDI lookups. Creates a JndiTemplate with the given environment settings.
Set the JndiTemplate to use for JNDI lookups. A default one is used if not set.
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.
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.
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.
Set the JTA UserTransaction to use as direct reference.
Typically just used for local JTA setups; in a Java EE environment, the UserTransaction will always be fetched from JNDI.
Set the JNDI name of the JTA UserTransaction.
Note that the UserTransaction will be autodetected at the Java EE default location "java:comp/UserTransaction" if not specified explicitly.
Determine whether the underlying transaction manager supports XA transactions managed by a resource adapter (i.e. without explicit XA resource enlistment).
Typically false
. Checked by
AbstractMessageEndpointFactory
in order to differentiate between invalid configuration and valid
ResourceAdapter-managed transactions.
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(JtaTransactionObject, TransactionDefinition)
method.
txObject | the JtaTransactionObject containing the UserTransaction |
---|---|
isolationLevel | isolation level taken from transaction definition |
InvalidIsolationLevelException | if the given isolation level cannot be applied |
---|---|
SystemException | if thrown by the JTA implementation |
Apply the given transaction timeout. The default implementation will call
UserTransaction.setTransactionTimeout
for a non-default timeout value.
txObject | the JtaTransactionObject containing the UserTransaction |
---|---|
timeout | timeout value taken from transaction definition |
SystemException | if thrown by the JTA implementation |
---|
Build a UserTransaction handle based on the given TransactionManager.
transactionManager | the TransactionManager |
---|
Check the UserTransaction as well as the TransactionManager handle, assuming standard JTA requirements.
IllegalStateException | if no sufficient handles are available |
---|
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.
transaction | transaction object returned by doGetTransaction |
---|---|
definition | TransactionDefinition instance, describing propagation behavior, isolation level, read-only flag, timeout, and transaction name |
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.
status | the status representation of the transaction |
---|
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.
ut | the UserTransaction handle to use for the current transaction |
---|
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.
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.
txObject | the JtaTransactionObject containing the UserTransaction |
---|---|
definition | TransactionDefinition instance, describing propagation behavior, isolation level, read-only flag, timeout, and transaction name |
NotSupportedException | if thrown by JTA methods |
---|---|
SystemException | if thrown by JTA methods |
Perform a JTA resume on the JTA TransactionManager.
Can be overridden in subclasses, for specific JTA implementations.
txObject | the JtaTransactionObject containing the UserTransaction |
---|---|
suspendedTransaction | the suspended JTA Transaction object |
InvalidTransactionException | if thrown by JTA methods |
---|---|
SystemException | if thrown by JTA methods |
Perform a JTA suspend on the JTA TransactionManager.
Can be overridden in subclasses, for specific JTA implementations.
txObject | the JtaTransactionObject containing the UserTransaction |
---|
SystemException | if thrown by JTA methods |
---|
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.
txObject | the current transaction object |
---|---|
synchronizations | List of TransactionSynchronization objects |
RollbackException | if thrown by JTA methods |
---|---|
SystemException | if thrown by JTA methods |
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.
transaction | transaction object returned by doGetTransaction |
---|---|
suspendedResources | the object that holds suspended resources, as returned by doSuspend |
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.
status | the status representation of the transaction |
---|
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.
status | the status representation of the transaction |
---|
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.
transaction | transaction object returned by doGetTransaction |
---|
Find the JTA TransactionManager through autodetection: checking whether the UserTransaction object implements the TransactionManager, and checking the fallback JNDI locations.
ut | the JTA UserTransaction object |
---|
null
if not foundFind 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
.
ut | the JTA UserTransaction object |
---|---|
tm | the JTA TransactionManager object |
null
if none foundTransactionSystemException | in case of errors |
---|
Find the JTA UserTransaction through a default JNDI lookup: "java:comp/UserTransaction".
null
if not foundInitialize the JTA 1.1 TransactionSynchronizationRegistry, if available.
To be called after initUserTransactionAndTransactionManager()
,
since it may check the UserTransaction and TransactionManager handles.
TransactionSystemException | if initialization failed |
---|
Initialize the UserTransaction as well as the TransactionManager handle.
TransactionSystemException | if initialization failed |
---|
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.
transaction | transaction object returned by doGetTransaction |
---|
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.
transactionManagerName | the JNDI name of the TransactionManager |
---|
TransactionSystemException | if the JNDI lookup failed |
---|
Look up the JTA 1.1 TransactionSynchronizationRegistry in JNDI via the configured name.
Can be overridden in subclasses to provide a different TransactionManager object.
registryName | the JNDI name of the TransactionSynchronizationRegistry |
---|
TransactionSystemException | if the JNDI lookup failed |
---|
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.
userTransactionName | the JNDI name of the UserTransaction |
---|
TransactionSystemException | if the JNDI lookup failed |
---|
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.
transaction | transaction object returned by doGetTransaction |
---|---|
synchronizations | List of TransactionSynchronization objects |
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
.
null
if none foundTransactionSystemException | in case of errors |
---|
Allows subclasses to retrieve the JTA 1.1 TransactionSynchronizationRegistry in a vendor-specific manner.
The default implementation simply returns null
.
null
if none foundTransactionSystemException | in case of errors |
---|
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
.
null
if none foundTransactionSystemException | in case of errors |
---|
This implementation returns "true": a JTA commit will properly handle transactions that have been marked rollback-only at a global level.
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.