org.springframework.transaction.support
Class AbstractPlatformTransactionManager

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

All Implemented Interfaces:

Serializable, PlatformTransactionManager

Direct Known Subclasses:

CciLocalTransactionManager, DataSourceTransactionManager, HibernateTransactionManager, HibernateTransactionManager, JdoTransactionManager, JmsTransactionManager, JtaTransactionManager, PersistenceBrokerTransactionManager, TopLinkTransactionManager

public abstract class AbstractPlatformTransactionManager
extends Object
implements PlatformTransactionManager, Serializable

Abstract base class that implements Spring's standard transaction workflow, serving as basis for concrete platform transaction managers like JtaTransactionManager and 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.

Since:

28.03.2003

Author:

Juergen Hoeller

See Also:

setTransactionSynchronization(int), TransactionSynchronizationManager, JtaTransactionManager, DataSourceTransactionManager, HibernateTransactionManager, Serialized Form

Field Summary

protected Log	logger Transient to optimize serialization
static int	SYNCHRONIZATION_ALWAYS Always activate transaction synchronization, even for "empty" transactions that result from PROPAGATION_SUPPORTS with no existing backend transaction.
static int	SYNCHRONIZATION_NEVER Never active transaction synchronization, not even for actual transactions.
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.

Constructor Summary

AbstractPlatformTransactionManager()

Method Summary

void	commit(TransactionStatus status) This implementation of commit handles participating in existing transactions and programmatic rollback requests.
protected abstract 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.
protected abstract void	doCommit(DefaultTransactionStatus status) Perform an actual commit of the given transaction.
protected abstract Object	doGetTransaction() Return a transaction object for the current transaction state.
protected void	doResume(Object transaction, Object suspendedResources) Resume the resources of the current transaction.
protected abstract 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.
TransactionStatus	getTransaction(TransactionDefinition definition) This implementation handles propagation behavior.
int	getTransactionSynchronization() Return if this transaction manager should activate the thread-bound transaction synchronization support.
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).
boolean	isGlobalRollbackOnParticipationFailure() Return whether to globally mark an existing transaction as rollback-only after a participating transaction failed.
boolean	isNestedTransactionAllowed() Return whether nested transactions are allowed.
boolean	isRollbackOnCommitFailure() Return whether doRollback should be performed on failure of the doCommit call.
protected void	registerAfterCompletionWithExistingTransaction(Object transaction, List synchronizations) Register the given list of transaction synchronizations with the existing transaction.
void	rollback(TransactionStatus status) This implementation of rollback handles participating in existing transactions.
void	setGlobalRollbackOnParticipationFailure(boolean globalRollbackOnParticipationFailure) Set whether to globally mark an existing transaction as rollback-only after a participating transaction failed.
void	setNestedTransactionAllowed(boolean nestedTransactionAllowed) Set whether nested transactions are allowed.
void	setRollbackOnCommitFailure(boolean rollbackOnCommitFailure) Set whether doRollback should be performed on failure of the doCommit call.
void	setTransactionSynchronization(int transactionSynchronization) Set when this transaction manager should activate the thread-bound transaction synchronization support.
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.
protected boolean	useSavepointForNestedTransaction() Return whether to use a savepoint for a nested transaction.

Methods inherited from class java.lang.Object

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

Field Detail

SYNCHRONIZATION_ALWAYS

public static final int SYNCHRONIZATION_ALWAYS

Always activate transaction synchronization, even for "empty" transactions that result from PROPAGATION_SUPPORTS with no existing backend transaction.

See Also:

TransactionDefinition.PROPAGATION_SUPPORTS, TransactionDefinition.PROPAGATION_NOT_SUPPORTED, TransactionDefinition.PROPAGATION_NEVER, Constant Field Values

SYNCHRONIZATION_ON_ACTUAL_TRANSACTION

public static final 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.

See Also:

TransactionDefinition.PROPAGATION_REQUIRED, TransactionDefinition.PROPAGATION_MANDATORY, TransactionDefinition.PROPAGATION_REQUIRES_NEW, Constant Field Values

SYNCHRONIZATION_NEVER

public static final int SYNCHRONIZATION_NEVER

Never active transaction synchronization, not even for actual transactions.

See Also:

Constant Field Values

logger

protected transient Log logger

Transient to optimize serialization

Constructor Detail

AbstractPlatformTransactionManager

public AbstractPlatformTransactionManager()

Method Detail

setTransactionSynchronizationName

public void setTransactionSynchronizationName(String constantName)

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:

SYNCHRONIZATION_ALWAYS

setTransactionSynchronization

public void setTransactionSynchronization(int transactionSynchronization)

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.

See Also:

SYNCHRONIZATION_ALWAYS, SYNCHRONIZATION_ON_ACTUAL_TRANSACTION, SYNCHRONIZATION_NEVER, TransactionSynchronizationManager, TransactionSynchronization

getTransactionSynchronization

public int getTransactionSynchronization()

Return if this transaction manager should activate the thread-bound transaction synchronization support.

setNestedTransactionAllowed

public void setNestedTransactionAllowed(boolean nestedTransactionAllowed)

Set whether nested transactions are allowed. Default is "false".

Typically initialized with an appropriate default by the concrete transaction manager subclass.

isNestedTransactionAllowed

public boolean isNestedTransactionAllowed()

Return whether nested transactions are allowed.

setGlobalRollbackOnParticipationFailure

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

setNestedTransactionAllowed(boolean), DataSourceTransactionManager, JtaTransactionManager

isGlobalRollbackOnParticipationFailure

public boolean isGlobalRollbackOnParticipationFailure()

Return whether to globally mark an existing transaction as rollback-only after a participating transaction failed.

setRollbackOnCommitFailure

public void setRollbackOnCommitFailure(boolean rollbackOnCommitFailure)

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

See Also:

doCommit(org.springframework.transaction.support.DefaultTransactionStatus), doRollback(org.springframework.transaction.support.DefaultTransactionStatus)

isRollbackOnCommitFailure

public boolean isRollbackOnCommitFailure()

Return whether doRollback should be performed on failure of the doCommit call.

getTransaction

public final TransactionStatus getTransaction(TransactionDefinition definition)
                                       throws TransactionException

This implementation handles propagation behavior. Delegates to doGetTransaction, isExistingTransaction and doBegin.

Specified by:

getTransaction in interface PlatformTransactionManager

Parameters:

definition - TransactionDefinition instance (can be null for defaults), describing propagation behavior, isolation level, timeout etc.

Returns:

transaction status object representing the new or current transaction

Throws:

TransactionException - in case of lookup, creation, or system errors

IllegalTransactionStateException - if the given transaction definition cannot be executed (for example, if a currently active transaction is in conflict with the specified propagation behavior)

See Also:

doGetTransaction(), isExistingTransaction(java.lang.Object), doBegin(java.lang.Object, org.springframework.transaction.TransactionDefinition)

commit

public final void commit(TransactionStatus status)
                  throws TransactionException

This implementation of commit handles participating in existing transactions and programmatic rollback requests. Delegates to isRollbackOnly, doCommit and rollback.

Specified by:

commit in interface PlatformTransactionManager

Parameters:

status - object returned by the getTransaction method

Throws:

TransactionException - in case of commit or system errors

IllegalTransactionStateException - if the given transaction is already completed (that is, committed or rolled back)

See Also:

TransactionStatus.isRollbackOnly(), doCommit(org.springframework.transaction.support.DefaultTransactionStatus), rollback(org.springframework.transaction.TransactionStatus)

rollback

public final void rollback(TransactionStatus status)
                    throws TransactionException

This implementation of rollback handles participating in existing transactions. Delegates to doRollback and doSetRollbackOnly.

Specified by:

rollback in interface PlatformTransactionManager

Parameters:

status - object returned by the getTransaction method

Throws:

TransactionException - in case of system errors

IllegalTransactionStateException - if the given transaction is already completed (that is, committed or rolled back)

See Also:

doRollback(org.springframework.transaction.support.DefaultTransactionStatus), doSetRollbackOnly(org.springframework.transaction.support.DefaultTransactionStatus)

invokeAfterCompletion

protected final void invokeAfterCompletion(List synchronizations,
                                           int completionStatus)

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.

Parameters:

synchronizations - List of TransactionSynchronization objects

completionStatus - the completion status according to the constants in the TransactionSynchronization interface

See Also:

registerAfterCompletionWithExistingTransaction(Object, java.util.List), TransactionSynchronization.STATUS_COMMITTED, TransactionSynchronization.STATUS_ROLLED_BACK, TransactionSynchronization.STATUS_UNKNOWN

doGetTransaction

protected abstract Object doGetTransaction()
                                    throws TransactionException

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.

Returns:

the current transaction object

Throws:

CannotCreateTransactionException - if transaction support is not available

TransactionException - in case of lookup or system errors

See Also:

doBegin(java.lang.Object, org.springframework.transaction.TransactionDefinition), doCommit(org.springframework.transaction.support.DefaultTransactionStatus), doRollback(org.springframework.transaction.support.DefaultTransactionStatus), DefaultTransactionStatus.getTransaction()

isExistingTransaction

protected boolean isExistingTransaction(Object transaction)
                                 throws TransactionException

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

Returns:

if there is an existing transaction

Throws:

TransactionException - in case of system errors

See Also:

doGetTransaction()

useSavepointForNestedTransaction

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

AbstractTransactionStatus.createAndHoldSavepoint(), AbstractTransactionStatus.rollbackToHeldSavepoint(), AbstractTransactionStatus.releaseHeldSavepoint(), doBegin(java.lang.Object, org.springframework.transaction.TransactionDefinition)

doBegin

protected abstract void doBegin(Object transaction,
                                TransactionDefinition definition)
                         throws TransactionException

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

definition - TransactionDefinition instance, describing propagation behavior, isolation level, read-only flag, timeout, and transaction name

Throws:

TransactionException - in case of creation or system errors

doSuspend

protected Object doSuspend(Object transaction)
                    throws TransactionException

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.

Parameters:

transaction - transaction object returned by doGetTransaction

Returns:

an object that holds suspended resources (will be kept unexamined for passing it into doResume)

Throws:

TransactionSuspensionNotSupportedException - if suspending is not supported by the transaction manager implementation

TransactionException - in case of system errors

See Also:

doResume(java.lang.Object, java.lang.Object)

doResume

protected void doResume(Object transaction,
                        Object suspendedResources)
                 throws TransactionException

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.

Parameters:

transaction - transaction object returned by doGetTransaction

suspendedResources - the object that holds suspended resources, as returned by doSuspend

Throws:

TransactionSuspensionNotSupportedException - if resuming is not supported by the transaction manager implementation

TransactionException - in case of system errors

See Also:

doSuspend(java.lang.Object)

shouldCommitOnGlobalRollbackOnly

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

doCommit(org.springframework.transaction.support.DefaultTransactionStatus), DefaultTransactionStatus.isGlobalRollbackOnly(), AbstractTransactionStatus.isLocalRollbackOnly(), TransactionStatus.setRollbackOnly(), UnexpectedRollbackException, UserTransaction.commit(), RollbackException

doCommit

protected abstract void doCommit(DefaultTransactionStatus status)
                          throws TransactionException

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

protected abstract void doRollback(DefaultTransactionStatus status)
                            throws TransactionException

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

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

registerAfterCompletionWithExistingTransaction

protected void registerAfterCompletionWithExistingTransaction(Object transaction,
                                                              List synchronizations)
                                                       throws TransactionException

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

synchronizations - List of TransactionSynchronization objects

Throws:

TransactionException - in case of system errors

See Also:

invokeAfterCompletion(java.util.List, int), TransactionSynchronization.afterCompletion(int), TransactionSynchronization.STATUS_UNKNOWN

doCleanupAfterCompletion

protected void doCleanupAfterCompletion(Object transaction)

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