java.lang.Object | |
↳ | org.springframework.transaction.support.AbstractPlatformTransactionManager |
Known Direct Subclasses |
Known Indirect Subclasses |
Abstract base class that implements Spring's standard transaction workflow,
serving as basis for concrete platform transaction managers like
JtaTransactionManager
.
This base class provides the following workflow handling:
Subclasses have to implement specific template methods for specific states of a transaction, e.g.: begin, suspend, resume, commit, rollback. The most important of them are abstract and must be provided by a concrete implementation; for the rest, defaults are provided, so overriding is optional.
Transaction synchronization is a generic mechanism for registering callbacks that get invoked at transaction completion time. This is mainly used internally by the data access support classes for JDBC, Hibernate, JPA, etc when running within a JTA transaction: They register resources that are opened within the transaction for closing at transaction completion time, allowing e.g. for reuse of the same Hibernate Session within the transaction. The same mechanism can also be leveraged for custom synchronization needs in an application.
The state of this class is serializable, to allow for serializing the
transaction strategy along with proxies that carry a transaction interceptor.
It is up to subclasses if they wish to make their state to be serializable too.
They should implement the java.io.Serializable
marker interface in
that case, and potentially a private readObject()
method (according
to Java serialization rules) if they need to restore any transient state.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
AbstractPlatformTransactionManager.SuspendedResourcesHolder | Holder for suspended resources. |
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | SYNCHRONIZATION_ALWAYS | Always activate transaction synchronization, even for "empty" transactions that result from PROPAGATION_SUPPORTS with no existing backend transaction. | |||||||||
int | SYNCHRONIZATION_NEVER | Never active transaction synchronization, not even for actual transactions. | |||||||||
int | SYNCHRONIZATION_ON_ACTUAL_TRANSACTION | Activate transaction synchronization only for actual transactions, that is, not for empty ones that result from PROPAGATION_SUPPORTS with no existing backend transaction. |
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
logger |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
This implementation of commit handles participating in existing
transactions and programmatic rollback requests.
| |||||||||||
Return the default timeout that this transaction manager should apply
if there is no timeout specified at the transaction level, in seconds.
| |||||||||||
This implementation handles propagation behavior.
| |||||||||||
Return if this transaction manager should activate the thread-bound
transaction synchronization support.
| |||||||||||
Return whether to fail early in case of the transaction being globally marked
as rollback-only.
| |||||||||||
Return whether to globally mark an existing transaction as rollback-only
after a participating transaction failed.
| |||||||||||
Return whether nested transactions are allowed.
| |||||||||||
Return whether
doRollback should be performed on failure of the
doCommit call. | |||||||||||
Return whether existing transactions should be validated before participating
in them.
| |||||||||||
This implementation of rollback handles participating in existing
transactions.
| |||||||||||
Specify the default timeout that this transaction manager should apply
if there is no timeout specified at the transaction level, in seconds.
| |||||||||||
Set whether to fail early in case of the transaction being globally marked
as rollback-only.
| |||||||||||
Set whether to globally mark an existing transaction as rollback-only
after a participating transaction failed.
| |||||||||||
Set whether nested transactions are allowed.
| |||||||||||
Set whether
doRollback should be performed on failure of the
doCommit call. | |||||||||||
Set when this transaction manager should activate the thread-bound
transaction synchronization support.
| |||||||||||
Set the transaction synchronization by the name of the corresponding constant
in this class, e.g.
| |||||||||||
Set whether existing transactions should be validated before participating
in them.
|
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Determine the actual timeout to use for the given definition.
| |||||||||||
Begin a new transaction with semantics according to the given transaction
definition.
| |||||||||||
Cleanup resources after transaction completion.
| |||||||||||
Perform an actual commit of the given transaction.
| |||||||||||
Return a transaction object for the current transaction state.
| |||||||||||
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.
| |||||||||||
Actually invoke the
afterCompletion methods of the
given Spring TransactionSynchronization objects. | |||||||||||
Check if the given transaction object indicates an existing transaction
(that is, a transaction which has already started).
| |||||||||||
Create a rae TransactionStatus instance for the given arguments.
| |||||||||||
Make preparations for commit, to be performed before the
beforeCommit synchronization callbacks occur. | |||||||||||
Initialize transaction synchronization as appropriate.
| |||||||||||
Create a new TransactionStatus for the given arguments,
also initializing transaction synchronization as appropriate.
| |||||||||||
Register the given list of transaction synchronizations with the existing transaction.
| |||||||||||
Resume the given transaction.
| |||||||||||
Return whether to call
doCommit on a transaction that has been
marked as rollback-only in a global fashion. | |||||||||||
Suspend the given transaction.
| |||||||||||
Trigger
beforeCommit callbacks. | |||||||||||
Trigger
beforeCompletion callbacks. | |||||||||||
Return whether to use a savepoint for a nested transaction.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
From interface
org.springframework.transaction.PlatformTransactionManager
|
Always activate transaction synchronization, even for "empty" transactions that result from PROPAGATION_SUPPORTS with no existing backend transaction.
Never active transaction synchronization, not even for actual transactions.
Activate transaction synchronization only for actual transactions, that is, not for empty ones that result from PROPAGATION_SUPPORTS with no existing backend transaction.
This implementation of commit handles participating in existing
transactions and programmatic rollback requests.
Delegates to isRollbackOnly
, doCommit
and rollback
.
status | object returned by the getTransaction method |
---|
TransactionException |
---|
Return the default timeout that this transaction manager should apply if there is no timeout specified at the transaction level, in seconds.
Returns TransactionDefinition.TIMEOUT_DEFAULT
to indicate
the underlying transaction infrastructure's default timeout.
This implementation handles propagation behavior. Delegates to
doGetTransaction
, isExistingTransaction
and doBegin
.
definition | TransactionDefinition instance (can be null for defaults),
describing propagation behavior, isolation level, timeout etc. |
---|
TransactionException |
---|
Return if this transaction manager should activate the thread-bound transaction synchronization support.
Return whether to fail early in case of the transaction being globally marked as rollback-only.
Return whether to globally mark an existing transaction as rollback-only after a participating transaction failed.
Return whether nested transactions are allowed.
Return whether doRollback
should be performed on failure of the
doCommit
call.
Return whether existing transactions should be validated before participating in them.
This implementation of rollback handles participating in existing
transactions. Delegates to doRollback
and
doSetRollbackOnly
.
status | object returned by the getTransaction method |
---|
TransactionException |
---|
Specify the default timeout that this transaction manager should apply if there is no timeout specified at the transaction level, in seconds.
Default is the underlying transaction infrastructure's default timeout,
e.g. typically 30 seconds in case of a JTA provider, indicated by the
TransactionDefinition.TIMEOUT_DEFAULT
value.
Set whether to fail early in case of the transaction being globally marked as rollback-only.
Default is "false", only causing an UnexpectedRollbackException at the outermost transaction boundary. Switch this flag on to cause an UnexpectedRollbackException as early as the global rollback-only marker has been first detected, even from within an inner transaction boundary.
Note that, as of Spring 2.0, the fail-early behavior for global rollback-only markers has been unified: All transaction managers will by default only cause UnexpectedRollbackException at the outermost transaction boundary. This allows, for example, to continue unit tests even after an operation failed and the transaction will never be completed. All transaction managers will only fail earlier if this flag has explicitly been set to "true".
Set whether to globally mark an existing transaction as rollback-only after a participating transaction failed.
Default is "true": If a participating transaction (e.g. with PROPAGATION_REQUIRES or PROPAGATION_SUPPORTS encountering an existing transaction) fails, the transaction will be globally marked as rollback-only. The only possible outcome of such a transaction is a rollback: The transaction originator cannot make the transaction commit anymore.
Switch this to "false" to let the transaction originator make the rollback decision. If a participating transaction fails with an exception, the caller can still decide to continue with a different path within the transaction. However, note that this will only work as long as all participating resources are capable of continuing towards a transaction commit even after a data access failure: This is generally not the case for a Hibernate Session, for example; neither is it for a sequence of JDBC insert/update/delete operations.
Note:This flag only applies to an explicit rollback attempt for a
subtransaction, typically caused by an exception thrown by a data access operation
(where TransactionInterceptor will trigger a PlatformTransactionManager.rollback()
call according to a rollback rule). If the flag is off, the caller can handle the exception
and decide on a rollback, independent of the rollback rules of the subtransaction.
This flag does, however, not apply to explicit setRollbackOnly
calls on a TransactionStatus
, which will always cause an eventual
global rollback (as it might not throw an exception after the rollback-only call).
The recommended solution for handling failure of a subtransaction is a "nested transaction", where the global transaction can be rolled back to a savepoint taken at the beginning of the subtransaction. PROPAGATION_NESTED provides exactly those semantics; however, it will only work when nested transaction support is available. This is the case with DataSourceTransactionManager, but not with JtaTransactionManager.
Set whether nested transactions are allowed. Default is "false".
Typically initialized with an appropriate default by the concrete transaction manager subclass.
Set whether doRollback
should be performed on failure of the
doCommit
call. Typically not necessary and thus to be avoided,
as it can potentially override the commit exception with a subsequent
rollback exception.
Default is "false".
Set when this transaction manager should activate the thread-bound transaction synchronization support. Default is "always".
Note that transaction synchronization isn't supported for multiple concurrent transactions by different transaction managers. Only one transaction manager is allowed to activate it at any time.
Set the transaction synchronization by the name of the corresponding constant in this class, e.g. "SYNCHRONIZATION_ALWAYS".
constantName | name of the constant |
---|
Set whether existing transactions should be validated before participating in them.
When participating in an existing transaction (e.g. with PROPAGATION_REQUIRES or PROPAGATION_SUPPORTS encountering an existing transaction), this outer transaction's characteristics will apply even to the inner transaction scope. Validation will detect incompatible isolation level and read-only settings on the inner transaction definition and reject participation accordingly through throwing a corresponding exception.
Default is "false", leniently ignoring inner transaction settings, simply overriding them with the outer transaction's characteristics. Switch this flag to "true" in order to enforce strict validation.
Determine the actual timeout to use for the given definition. Will fall back to this manager's default timeout if the transaction definition doesn't specify a non-default value.
definition | the transaction definition |
---|
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 |
TransactionException | in case of creation or system errors |
---|
Cleanup resources after transaction completion.
Called after doCommit
and doRollback
execution,
on any outcome. The default implementation does nothing.
Should not throw any exceptions but just issue warnings on errors.
transaction | transaction object returned by doGetTransaction
|
---|
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 |
---|
TransactionException | in case of commit or system errors |
---|
Return a transaction object for the current transaction state.
The returned object will usually be specific to the concrete transaction manager implementation, carrying corresponding transaction state in a modifiable fashion. This object will be passed into the other template methods (e.g. doBegin and doCommit), either directly or as part of a DefaultTransactionStatus instance.
The returned object should contain information about any existing
transaction, that is, a transaction that has already started before the
current getTransaction
call on the transaction manager.
Consequently, a doGetTransaction
implementation will usually
look for an existing transaction and store corresponding state in the
returned transaction object.
CannotCreateTransactionException | if transaction support is not available |
---|---|
TransactionException | in case of lookup or system errors |
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 |
TransactionSuspensionNotSupportedException | if resuming is not supported by the transaction manager implementation |
---|---|
TransactionException | in case of system errors |
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 |
---|
TransactionException | in case of system errors |
---|
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 |
---|
TransactionException | in case of system errors |
---|
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 |
---|
TransactionSuspensionNotSupportedException | if suspending is not supported by the transaction manager implementation |
---|---|
TransactionException | in case of system errors |
Actually invoke the afterCompletion
methods of the
given Spring TransactionSynchronization objects.
To be called by this abstract manager itself, or by special implementations
of the registerAfterCompletionWithExistingTransaction
callback.
synchronizations | List of TransactionSynchronization objects |
---|---|
completionStatus | the completion status according to the constants in the TransactionSynchronization interface |
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 |
---|
TransactionException | in case of system errors |
---|
Create a rae TransactionStatus instance for the given arguments.
Make preparations for commit, to be performed before the
beforeCommit
synchronization callbacks occur.
Note that exceptions will get propagated to the commit caller and cause a rollback of the transaction.
status | the status representation of the transaction |
---|
RuntimeException | in case of errors; will be propagated to the caller (note: do not throw TransactionException subclasses here!) |
---|
Initialize transaction synchronization as appropriate.
Create a new TransactionStatus for the given arguments, also initializing transaction synchronization as appropriate.
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 |
TransactionException | in case of system errors |
---|
Resume the given transaction. Delegates to the doResume
template method first, then resuming transaction synchronization.
transaction | the current transaction object |
---|---|
resourcesHolder | the object that holds suspended resources,
as returned by suspend (or null to just
resume synchronizations, if any) |
TransactionException |
---|
Return whether to call doCommit
on a transaction that has been
marked as rollback-only in a global fashion.
Does not apply if an application locally sets the transaction to rollback-only via the TransactionStatus, but only to the transaction itself being marked as rollback-only by the transaction coordinator.
Default is "false": Local transaction strategies usually don't hold the rollback-only marker in the transaction itself, therefore they can't handle rollback-only transactions as part of transaction commit. Hence, AbstractPlatformTransactionManager will trigger a rollback in that case, throwing an UnexpectedRollbackException afterwards.
Override this to return "true" if the concrete transaction manager expects a
doCommit
call even for a rollback-only transaction, allowing for
special handling there. This will, for example, be the case for JTA, where
UserTransaction.commit
will check the read-only flag itself and
throw a corresponding RollbackException, which might include the specific reason
(such as a transaction timeout).
If this method returns "true" but the doCommit
implementation does not
throw an exception, this transaction manager will throw an UnexpectedRollbackException
itself. This should not be the typical case; it is mainly checked to cover misbehaving
JTA providers that silently roll back even when the rollback has not been requested
by the calling code.
doCommit(DefaultTransactionStatus)
isGlobalRollbackOnly()
isLocalRollbackOnly()
setRollbackOnly()
UnexpectedRollbackException
commit()
Suspend the given transaction. Suspends transaction synchronization first,
then delegates to the doSuspend
template method.
transaction | the current transaction object
(or null to just suspend active synchronizations, if any) |
---|
null
if neither transaction nor synchronization active)TransactionException |
---|
Trigger beforeCommit
callbacks.
status | object representing the transaction |
---|
Trigger beforeCompletion
callbacks.
status | object representing the transaction |
---|
Return whether to use a savepoint for a nested transaction.
Default is true
, which causes delegation to DefaultTransactionStatus
for creating and holding a savepoint. If the transaction object does not implement
the SavepointManager interface, a NestedTransactionNotSupportedException will be
thrown. Else, the SavepointManager will be asked to create a new savepoint to
demarcate the start of the nested transaction.
Subclasses can override this to return false
, causing a further
call to doBegin
- within the context of an already existing transaction.
The doBegin
implementation needs to handle this accordingly in such
a scenario. This is appropriate for JTA, for example.