| java.lang.Object
 org.springframework.transaction.support.AbstractPlatformTransactionManager
All known Subclasses: org.springframework.jdbc.datasource.DataSourceTransactionManager, org.springframework.transaction.jta.JtaTransactionManager, org.springframework.orm.jpa.JpaTransactionManager, org.springframework.orm.hibernate3.HibernateTransactionManager, org.springframework.jca.cci.connection.CciLocalTransactionManager, org.springframework.jms.connection.JmsTransactionManager, org.springframework.orm.jdo.JdoTransactionManager, org.springframework.orm.toplink.TopLinkTransactionManager,
| AbstractPlatformTransactionManager | | abstract public class AbstractPlatformTransactionManager implements PlatformTransactionManager,Serializable(Code) | | Abstract base class that implements Spring's standard transaction workflow,
serving as basis for concrete platform transaction managers like
org.springframework.transaction.jta.JtaTransactionManager and
org.springframework.jdbc.datasource.DataSourceTransactionManager .
This base class provides the following workflow handling:
- determines if there is an existing transaction;
- applies the appropriate propagation behavior;
- suspends and resumes transactions if necessary;
- checks the rollback-only flag on commit;
- applies the appropriate modification on rollback
(actual rollback or setting rollback-only);
- triggers registered synchronization callbacks
(if transaction synchronization is active).
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, JDO, 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.
author:
Juergen Hoeller
since:
28.03.2003
See Also: AbstractPlatformTransactionManager.setTransactionSynchronization
See Also: TransactionSynchronizationManager
See Also: org.springframework.transaction.jta.JtaTransactionManager
See Also: org.springframework.jdbc.datasource.DataSourceTransactionManager
See Also: org.springframework.orm.hibernate3.HibernateTransactionManager |
| Inner Class :protected static class SuspendedResourcesHolder | |
| Field Summary | |
| final public static int | SYNCHRONIZATION_ALWAYS
Always activate transaction synchronization, even for "empty" transactions
that result from PROPAGATION_SUPPORTS with no existing backend transaction. | | final public static int | SYNCHRONIZATION_NEVER
Never active transaction synchronization, not even for actual transactions. | | final public static 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. | | protected transient Log | logger
|
| Method Summary | |
| final public void | commit(TransactionStatus status)
This implementation of commit handles participating in existing
transactions and programmatic rollback requests. | | protected int | determineTimeout(TransactionDefinition definition)
Determine the actual timeout to use for the given definition. | | abstract protected void | doBegin(Object transaction, TransactionDefinition definition)
Begin a new transaction with semantics according to the given transaction
definition. | | protected void | doCleanupAfterCompletion(Object transaction)
Cleanup resources after transaction completion.
Called after doCommit and doRollback execution,
on any outcome. | | abstract protected void | doCommit(DefaultTransactionStatus status)
Perform an actual commit of the given transaction. | | abstract protected Object | doGetTransaction()
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. | | protected void | doResume(Object transaction, Object suspendedResources)
Resume the resources of the current transaction. | | abstract protected void | doRollback(DefaultTransactionStatus status)
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. | | protected void | doSetRollbackOnly(DefaultTransactionStatus status)
Set the given transaction rollback-only. | | protected Object | doSuspend(Object transaction)
Suspend the resources of the current transaction. | | final public int | getDefaultTimeout()
Return the default timeout that this transaction manager should apply
if there is no timeout specified at the transaction level, in seconds. | | final public TransactionStatus | getTransaction(TransactionDefinition definition)
This implementation handles propagation behavior. | | final public int | getTransactionSynchronization()
Return if this transaction manager should activate the thread-bound
transaction synchronization support. | | final protected void | invokeAfterCompletion(List synchronizations, int completionStatus)
Actually invoke the afterCompletion methods of the
given Spring TransactionSynchronization objects. | | protected boolean | isExistingTransaction(Object transaction)
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. | | final public boolean | isFailEarlyOnGlobalRollbackOnly()
Return whether to fail early in case of the transaction being globally marked
as rollback-only. | | final public boolean | isGlobalRollbackOnParticipationFailure()
Return whether to globally mark an existing transaction as rollback-only
after a participating transaction failed. | | final public boolean | isNestedTransactionAllowed()
Return whether nested transactions are allowed. | | final public boolean | isRollbackOnCommitFailure()
Return whether doRollback should be performed on failure of the
doCommit call. | | protected DefaultTransactionStatus | newTransactionStatus(TransactionDefinition definition, Object transaction, boolean newTransaction, boolean newSynchronization, boolean debug, Object suspendedResources)
Create a new TransactionStatus for the given arguments,
initializing transaction synchronization as appropriate. | | protected void | registerAfterCompletionWithExistingTransaction(Object transaction, List synchronizations)
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. | | final protected void | resume(Object transaction, SuspendedResourcesHolder resourcesHolder)
Resume the given transaction. | | final public void | rollback(TransactionStatus status)
This implementation of rollback handles participating in existing
transactions. | | final public void | setDefaultTimeout(int defaultTimeout)
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. | | final public void | setFailEarlyOnGlobalRollbackOnly(boolean failEarlyOnGlobalRollbackOnly)
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. | | final public void | setGlobalRollbackOnParticipationFailure(boolean globalRollbackOnParticipationFailure)
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. | | final public void | setNestedTransactionAllowed(boolean nestedTransactionAllowed)
Set whether nested transactions are allowed. | | final public void | setRollbackOnCommitFailure(boolean rollbackOnCommitFailure)
Set whether doRollback should be performed on failure of the
doCommit call. | | final public void | setTransactionSynchronization(int transactionSynchronization)
Set when this transaction manager should activate the thread-bound
transaction synchronization support. | | final public void | setTransactionSynchronizationName(String constantName)
Set the transaction synchronization by the name of the corresponding constant
in this class, e.g. | | protected boolean | shouldCommitOnGlobalRollbackOnly()
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. | | final protected SuspendedResourcesHolder | suspend(Object transaction)
Suspend the given transaction. | | final protected void | triggerBeforeCommit(DefaultTransactionStatus status)
Trigger beforeCommit callbacks. | | final protected void | triggerBeforeCompletion(DefaultTransactionStatus status)
Trigger beforeCompletion callbacks. | | protected boolean | useSavepointForNestedTransaction()
Return whether to use a savepoint for a nested transaction.
Default is true, which causes delegation to DefaultTransactionStatus
for creating and holding a savepoint. |
| SYNCHRONIZATION_NEVER | | final public static int SYNCHRONIZATION_NEVER(Code) | | Never active transaction synchronization, not even for actual transactions.
|
| logger | | protected transient Log logger(Code) | | Transient to optimize serialization
|
| doBegin | | abstract protected void doBegin(Object transaction, TransactionDefinition definition) throws TransactionException(Code) | | 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.
Parameters:
transaction - transaction object returned by doGetTransaction
Parameters:
definition - TransactionDefinition instance, describing propagationbehavior, isolation level, read-only flag, timeout, and transaction name
throws:
TransactionException - in case of creation or system errors |
| doCleanupAfterCompletion | | protected void doCleanupAfterCompletion(Object transaction)(Code) | | 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.
Parameters:
transaction - transaction object returned by doGetTransaction |
| doCommit | | abstract protected void doCommit(DefaultTransactionStatus status) throws TransactionException(Code) | | 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.
Parameters:
status - the status representation of the transaction
throws:
TransactionException - in case of commit or system errors
See Also: DefaultTransactionStatus.getTransaction |
| doRollback | | abstract protected void doRollback(DefaultTransactionStatus status) throws TransactionException(Code) | | 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.
Parameters:
status - the status representation of the transaction
throws:
TransactionException - in case of system errors
See Also: DefaultTransactionStatus.getTransaction |
| doSetRollbackOnly | | protected void doSetRollbackOnly(DefaultTransactionStatus status) throws TransactionException(Code) | | 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.
Parameters:
status - the status representation of the transaction
throws:
TransactionException - in case of system errors |
| getDefaultTimeout | | final public int getDefaultTimeout()(Code) | | 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.
|
| getTransactionSynchronization | | final public int getTransactionSynchronization()(Code) | | Return if this transaction manager should activate the thread-bound
transaction synchronization support.
|
| isExistingTransaction | | protected boolean isExistingTransaction(Object transaction) throws TransactionException(Code) | | 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.
Parameters:
transaction - transaction object returned by doGetTransaction if there is an existing transaction
throws:
TransactionException - in case of system errors
See Also: AbstractPlatformTransactionManager.doGetTransaction |
| isFailEarlyOnGlobalRollbackOnly | | final public boolean isFailEarlyOnGlobalRollbackOnly()(Code) | | Return whether to fail early in case of the transaction being globally marked
as rollback-only.
|
| isGlobalRollbackOnParticipationFailure | | final public boolean isGlobalRollbackOnParticipationFailure()(Code) | | Return whether to globally mark an existing transaction as rollback-only
after a participating transaction failed.
|
| isNestedTransactionAllowed | | final public boolean isNestedTransactionAllowed()(Code) | | Return whether nested transactions are allowed.
|
| isRollbackOnCommitFailure | | final public boolean isRollbackOnCommitFailure()(Code) | | Return whether doRollback should be performed on failure of the
doCommit call.
|
| newTransactionStatus | | protected DefaultTransactionStatus newTransactionStatus(TransactionDefinition definition, Object transaction, boolean newTransaction, boolean newSynchronization, boolean debug, Object suspendedResources)(Code) | | Create a new TransactionStatus for the given arguments,
initializing transaction synchronization as appropriate.
|
| registerAfterCompletionWithExistingTransaction | | protected void registerAfterCompletionWithExistingTransaction(Object transaction, List synchronizations) throws TransactionException(Code) | | 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.
Parameters:
transaction - transaction object returned by doGetTransaction
Parameters:
synchronizations - List of TransactionSynchronization objects
throws:
TransactionException - in case of system errors
See Also: AbstractPlatformTransactionManager.invokeAfterCompletion(java.util.List,int)
See Also: TransactionSynchronization.afterCompletion(int)
See Also: TransactionSynchronization.STATUS_UNKNOWN |
| setDefaultTimeout | | final public void setDefaultTimeout(int defaultTimeout)(Code) | | 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.
See Also: org.springframework.transaction.TransactionDefinition.TIMEOUT_DEFAULT |
| setFailEarlyOnGlobalRollbackOnly | | final public void setFailEarlyOnGlobalRollbackOnly(boolean failEarlyOnGlobalRollbackOnly)(Code) | | 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".
See Also: org.springframework.transaction.UnexpectedRollbackException |
| setGlobalRollbackOnParticipationFailure | | final public void setGlobalRollbackOnParticipationFailure(boolean globalRollbackOnParticipationFailure)(Code) | | 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.
See Also: AbstractPlatformTransactionManager.setNestedTransactionAllowed
See Also: org.springframework.jdbc.datasource.DataSourceTransactionManager
See Also: org.springframework.transaction.jta.JtaTransactionManager |
| setNestedTransactionAllowed | | final public void setNestedTransactionAllowed(boolean nestedTransactionAllowed)(Code) | | Set whether nested transactions are allowed. Default is "false".
Typically initialized with an appropriate default by the
concrete transaction manager subclass.
|
| setTransactionSynchronizationName | | final public void setTransactionSynchronizationName(String constantName)(Code) | | Set the transaction synchronization by the name of the corresponding constant
in this class, e.g. "SYNCHRONIZATION_ALWAYS".
Parameters:
constantName - name of the constant
See Also: AbstractPlatformTransactionManager.SYNCHRONIZATION_ALWAYS |
| shouldCommitOnGlobalRollbackOnly | | protected boolean shouldCommitOnGlobalRollbackOnly()(Code) | | 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.
See Also: AbstractPlatformTransactionManager.doCommit
See Also: DefaultTransactionStatus.isGlobalRollbackOnly
See Also: DefaultTransactionStatus.isLocalRollbackOnly
See Also: org.springframework.transaction.TransactionStatus.setRollbackOnly
See Also: org.springframework.transaction.UnexpectedRollbackException
See Also: javax.transaction.UserTransaction.commit
See Also: javax.transaction.RollbackException |
| triggerBeforeCommit | | final protected void triggerBeforeCommit(DefaultTransactionStatus status)(Code) | | Trigger beforeCommit callbacks.
Parameters:
status - object representing the transaction |
| triggerBeforeCompletion | | final protected void triggerBeforeCompletion(DefaultTransactionStatus status)(Code) | | Trigger beforeCompletion callbacks.
Parameters:
status - object representing the transaction |
| useSavepointForNestedTransaction | | protected boolean useSavepointForNestedTransaction()(Code) | | 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.
See Also: DefaultTransactionStatus.createAndHoldSavepoint
See Also: DefaultTransactionStatus.rollbackToHeldSavepoint
See Also: DefaultTransactionStatus.releaseHeldSavepoint
See Also: AbstractPlatformTransactionManager.doBegin |
|
|