|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.springframework.transaction.support.AbstractPlatformTransactionManager
public abstract class AbstractPlatformTransactionManager
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.
setTransactionSynchronization(int)
,
TransactionSynchronizationManager
,
JtaTransactionManager
,
DataSourceTransactionManager
,
HibernateTransactionManager
,
JdoTransactionManager
,
Serialized FormField Summary | |
---|---|
protected org.apache.commons.logging.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 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 if a rollback should be performed on failure of the commit 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 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 |
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 |
---|
public static final int SYNCHRONIZATION_ALWAYS
public static final int SYNCHRONIZATION_ON_ACTUAL_TRANSACTION
public static final int SYNCHRONIZATION_NEVER
protected transient org.apache.commons.logging.Log logger
Constructor Detail |
---|
public AbstractPlatformTransactionManager()
Method Detail |
---|
public void setTransactionSynchronizationName(String constantName)
constantName
- name of the constantSYNCHRONIZATION_ALWAYS
public void setTransactionSynchronization(int transactionSynchronization)
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.
SYNCHRONIZATION_ALWAYS
,
SYNCHRONIZATION_ON_ACTUAL_TRANSACTION
,
SYNCHRONIZATION_NEVER
,
TransactionSynchronizationManager
,
TransactionSynchronization
public int getTransactionSynchronization()
public void setNestedTransactionAllowed(boolean nestedTransactionAllowed)
Typically initialized with an appropriate default by the concrete transaction manager subclass.
public boolean isNestedTransactionAllowed()
public void setGlobalRollbackOnParticipationFailure(boolean globalRollbackOnParticipationFailure)
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 contiuing 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.
setNestedTransactionAllowed(boolean)
,
DataSourceTransactionManager
,
JtaTransactionManager
public boolean isGlobalRollbackOnParticipationFailure()
public void setRollbackOnCommitFailure(boolean rollbackOnCommitFailure)
doCommit(org.springframework.transaction.support.DefaultTransactionStatus)
,
doRollback(org.springframework.transaction.support.DefaultTransactionStatus)
public boolean isRollbackOnCommitFailure()
public final TransactionStatus getTransaction(TransactionDefinition definition) throws TransactionException
doGetTransaction
, isExistingTransaction
and doBegin
.
getTransaction
in interface PlatformTransactionManager
definition
- TransactionDefinition instance (can be null
for defaults),
describing propagation behavior, isolation level, timeout etc.
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)doGetTransaction()
,
isExistingTransaction(java.lang.Object)
,
doBegin(java.lang.Object, org.springframework.transaction.TransactionDefinition)
public final void commit(TransactionStatus status) throws TransactionException
isRollbackOnly
, doCommit
and rollback
.
commit
in interface PlatformTransactionManager
status
- object returned by the getTransaction
method
TransactionException
- in case of commit or system errors
IllegalTransactionStateException
- if the given transaction
is already completed (that is, committed or rolled back)TransactionStatus.isRollbackOnly()
,
doCommit(org.springframework.transaction.support.DefaultTransactionStatus)
,
rollback(org.springframework.transaction.TransactionStatus)
public final void rollback(TransactionStatus status) throws TransactionException
doRollback
and
doSetRollbackOnly
.
rollback
in interface PlatformTransactionManager
status
- object returned by the getTransaction
method
TransactionException
- in case of system errors
IllegalTransactionStateException
- if the given transaction
is already completed (that is, committed or rolled back)doRollback(org.springframework.transaction.support.DefaultTransactionStatus)
,
doSetRollbackOnly(org.springframework.transaction.support.DefaultTransactionStatus)
protected final void invokeAfterCompletion(List synchronizations, int completionStatus)
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 objectscompletionStatus
- the completion status according to the
constants in the TransactionSynchronization interfaceregisterAfterCompletionWithExistingTransaction(Object, java.util.List)
,
TransactionSynchronization.STATUS_COMMITTED
,
TransactionSynchronization.STATUS_ROLLED_BACK
,
TransactionSynchronization.STATUS_UNKNOWN
protected abstract Object doGetTransaction() throws TransactionException
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 errorsdoBegin(java.lang.Object, org.springframework.transaction.TransactionDefinition)
,
doCommit(org.springframework.transaction.support.DefaultTransactionStatus)
,
doRollback(org.springframework.transaction.support.DefaultTransactionStatus)
,
DefaultTransactionStatus.getTransaction()
protected boolean isExistingTransaction(Object transaction) throws TransactionException
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.
transaction
- transaction object returned by doGetTransaction
TransactionException
- in case of system errorsdoGetTransaction()
protected boolean useSavepointForNestedTransaction()
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.
AbstractTransactionStatus.createAndHoldSavepoint()
,
AbstractTransactionStatus.rollbackToHeldSavepoint()
,
AbstractTransactionStatus.releaseHeldSavepoint()
,
doBegin(java.lang.Object, org.springframework.transaction.TransactionDefinition)
protected abstract void doBegin(Object transaction, TransactionDefinition definition) throws TransactionException
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 errorsprotected Object doSuspend(Object transaction) throws TransactionException
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 errorsdoResume(java.lang.Object, java.lang.Object)
protected void doResume(Object transaction, Object suspendedResources) throws TransactionException
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 errorsdoSuspend(java.lang.Object)
protected boolean shouldCommitOnGlobalRollbackOnly()
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 in a special manner. 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 user.
doCommit(org.springframework.transaction.support.DefaultTransactionStatus)
,
DefaultTransactionStatus.isGlobalRollbackOnly()
,
AbstractTransactionStatus.isLocalRollbackOnly()
,
TransactionStatus.setRollbackOnly()
,
UnexpectedRollbackException
,
UserTransaction.commit()
,
RollbackException
protected abstract void doCommit(DefaultTransactionStatus status) throws TransactionException
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 errorsDefaultTransactionStatus.getTransaction()
protected abstract void doRollback(DefaultTransactionStatus status) throws TransactionException
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 errorsDefaultTransactionStatus.getTransaction()
protected void doSetRollbackOnly(DefaultTransactionStatus status) throws TransactionException
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 errorsprotected void registerAfterCompletionWithExistingTransaction(Object transaction, List synchronizations) throws TransactionException
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.
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 errorsinvokeAfterCompletion(java.util.List, int)
,
TransactionSynchronization.afterCompletion(int)
,
TransactionSynchronization.STATUS_UNKNOWN
protected void doCleanupAfterCompletion(Object transaction)
doCommit
and doRollback
execution,
on any outcome. Default implementation does nothing.
Should not throw any exceptions but just issue warnings on errors.
transaction
- transaction object returned by doGetTransaction
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |