org.springframework.transaction.support
Class AbstractPlatformTransactionManager

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

All Implemented Interfaces:

PlatformTransactionManager, Serializable

Direct Known Subclasses:

DataSourceTransactionManager, HibernateTransactionManager, JdoTransactionManager, JmsTransactionManager, JtaTransactionManager, PersistenceBrokerTransactionManager

public abstract class AbstractPlatformTransactionManager

extends Object

implements PlatformTransactionManager, Serializable

Abstract base class that allows for easy implementation of concrete platform transaction managers like JtaTransactionManager and HibernateTransactionManager.

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

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, and JDO: 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 used for custom synchronization efforts.

The state of this class is serializable. It's up to subclasses if they wish to make their state to be serializable. They should implement readObject() methods if they need to restore any transient state.

Since:

28.03.2003

Author:

Juergen Hoeller

See Also:

setTransactionSynchronization(int), TransactionSynchronizationManager, JtaTransactionManager, 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.
static int	SYNCHRONIZATION_ON_ACTUAL_TRANSACTION Activate transaction synchronization only for actual transactions, i.e. 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 the given transaction definition.
protected void	doCleanupAfterCompletion(Object transaction) Cleanup resources after transaction completion.
protected abstract void	doCommit(DefaultTransactionStatus status) Perform an actual commit on the given transaction.
protected abstract Object	doGetTransaction() Return a current transaction object, i.e. a JTA UserTransaction.
protected abstract void	doResume(Object transaction, Object suspendedResources) Resume the resources of the current transaction.
protected abstract void	doRollback(DefaultTransactionStatus status) Perform an actual rollback on the given transaction.
protected abstract void	doSetRollbackOnly(DefaultTransactionStatus status) Set the given transaction rollback-only.
protected abstract Object	doSuspend(Object transaction) Suspend the resources of the current transaction.
TransactionStatus	getTransaction(TransactionDefinition definition) This implementation of getTransaction handles propagation behavior.
int	getTransactionSynchronization() Return if this transaction manager should activate the thread-bound transaction synchronization support.
protected abstract boolean	isExistingTransaction(Object transaction) Check if the given transaction object indicates an existing, i.e. already begun, transaction.
boolean	isNestedTransactionAllowed() Return whether nested transactions are allowed.
boolean	isRollbackOnCommitFailure() Return if a rollback should be performed on failure of the commit call.
void	rollback(TransactionStatus status) This implementation of rollback handles participating in existing transactions.
void	setNestedTransactionAllowed(boolean nestedTransactionAllowed) Set whether nested transactions are allowed.
void	setRollbackOnCommitFailure(boolean rollbackOnCommitFailure) Set if 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	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:

Constant Field Values

SYNCHRONIZATION_ON_ACTUAL_TRANSACTION

public static final int SYNCHRONIZATION_ON_ACTUAL_TRANSACTION

Activate transaction synchronization only for actual transactions, i.e. not for empty ones that result from PROPAGATION_SUPPORTS with no existing backend transaction.

See Also:

Constant Field Values

SYNCHRONIZATION_NEVER

public static final int SYNCHRONIZATION_NEVER

Never active transaction synchronization.

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.

setRollbackOnCommitFailure

public void setRollbackOnCommitFailure(boolean rollbackOnCommitFailure)

Set if doRollback should be performed on failure of the doCommit call. Typically not necessary and thus to be avoided as it can 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 if a rollback should be performed on failure of the commit call.

getTransaction

public final TransactionStatus getTransaction(TransactionDefinition definition)
                                       throws TransactionException

This implementation of getTransaction handles propagation behavior. Delegates to doGetTransaction, isExistingTransaction, 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

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

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

See Also:

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

doGetTransaction

protected abstract Object doGetTransaction()
                                    throws TransactionException

Return a current transaction object, i.e. a JTA UserTransaction.

Returns:

the current transaction object

Throws:

CannotCreateTransactionException - if transaction support is not available (e.g. no JTA UserTransaction retrievable from JNDI)

TransactionException - in case of lookup or system errors

isExistingTransaction

protected abstract boolean isExistingTransaction(Object transaction)
                                          throws TransactionException

Check if the given transaction object indicates an existing, i.e. already begun, transaction.

Parameters:

transaction - transaction object returned by doGetTransaction

Returns:

if there is an existing transaction

Throws:

TransactionException - in case of system errors

useSavepointForNestedTransaction

protected boolean useSavepointForNestedTransaction()

Return whether to use a savepoint for a nested transaction. Default is true, which causes delegation to DefaultTransactionStatus for holding a savepoint.

Subclasses can override this to return false, causing a further invocation of doBegin despite an already existing transaction.

See Also:

DefaultTransactionStatus.createAndHoldSavepoint(), DefaultTransactionStatus.rollbackToHeldSavepoint(), DefaultTransactionStatus.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 the given transaction definition. Does not have to care about applying the propagation behavior, as this has already been handled by this abstract manager.

Parameters:

transaction - transaction object returned by doGetTransaction

definition - TransactionDefinition instance, describing propagation behavior, isolation level, timeout etc.

Throws:

TransactionException - in case of creation or system errors

doSuspend

protected abstract Object doSuspend(Object transaction)
                             throws TransactionException

Suspend the resources of the current transaction. Transaction synchronization will already have been suspended.

Parameters:

transaction - transaction object returned by doGetTransaction

Returns:

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

Throws:

IllegalTransactionStateException - 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 abstract void doResume(Object transaction,
                                 Object suspendedResources)
                          throws TransactionException

Resume the resources of the current transaction. Transaction synchronization will be resumed afterwards.

Parameters:

transaction - transaction object returned by doGetTransaction

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

Throws:

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

TransactionException - in case of system errors

See Also:

doSuspend(java.lang.Object)

doCommit

protected abstract void doCommit(DefaultTransactionStatus status)
                          throws TransactionException

Perform an actual commit on the given transaction. An implementation does not need to check the rollback-only flag.

Parameters:

status - status representation of the transaction

Throws:

TransactionException - in case of commit or system errors

doRollback

protected abstract void doRollback(DefaultTransactionStatus status)
                            throws TransactionException

Perform an actual rollback on the given transaction. An implementation does not need to check the new transaction flag.

Parameters:

status - status representation of the transaction

Throws:

TransactionException - in case of system errors

doSetRollbackOnly

protected abstract void doSetRollbackOnly(DefaultTransactionStatus status)
                                   throws TransactionException

Set the given transaction rollback-only. Only called on rollback if the current transaction takes part in an existing one.

Parameters:

status - status representation of the transaction

Throws:

TransactionException - in case of system errors

doCleanupAfterCompletion

protected void doCleanupAfterCompletion(Object transaction)

Cleanup resources after transaction completion. Called after doCommit and doRollback execution on any outcome. Should not throw any exceptions but just issue warnings on errors.

Default implementation does nothing.

Parameters:

transaction - transaction object returned by doGetTransaction