org.springframework.transaction.support
Class AbstractPlatformTransactionManager

java.lang.Object
  extended byorg.springframework.transaction.support.AbstractPlatformTransactionManager
All Implemented Interfaces:
PlatformTransactionManager
Direct Known Subclasses:
DataSourceTransactionManager, HibernateTransactionManager, JdoTransactionManager, JmsTransactionManager, JtaTransactionManager, PersistenceBrokerTransactionManager

public abstract class AbstractPlatformTransactionManager
extends Object
implements PlatformTransactionManager

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

This base class provides the following workflow handling:

Subclasses have to implement specific template methods for specific states of a transaction, for example 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, and JDO 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, JdoTransactionManager

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 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 of getTransaction handles propagation behavior.
 int getTransactionSynchronization()
          Return if this transaction manager should activate the thread-bound transaction synchronization support.
protected  boolean isExistingTransaction(Object transaction)
          Check if the given transaction object indicates an existing transaction (that is, a transaction which has already started).
 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 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).

Default implementation returns false, assuming that detection of or 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 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 Object doSuspend(Object transaction)
                    throws TransactionException
Suspend the resources of the current transaction. Transaction synchronization will already have been suspended.

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.

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)

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.

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

doCleanupAfterCompletion

protected void doCleanupAfterCompletion(Object transaction)
Cleanup resources after transaction completion. Called after doCommit and doRollback execution, on any outcome. Default implementation does nothing.

Should not throw any exceptions but just issue warnings on errors.

Parameters:
transaction - transaction object returned by doGetTransaction


Copyright (C) 2003-2004 The Spring Framework Project.