The Spring Framework

org.springframework.transaction
Interface PlatformTransactionManager

All Known Subinterfaces:
CallbackPreferringPlatformTransactionManager
All Known Implementing Classes:
AbstractPlatformTransactionManager, CciLocalTransactionManager, DataSourceTransactionManager, HibernateTransactionManager, HibernateTransactionManager, JdoTransactionManager, JmsTransactionManager, JmsTransactionManager102, JpaTransactionManager, JtaTransactionManager, TopLinkTransactionManager, WebLogicJtaTransactionManager

public interface PlatformTransactionManager

This is the central interface in Spring's transaction infrastructure. Applications can use this directly, but it is not primarily meant as API: Typically, applications will work with either TransactionTemplate or declarative transaction demarcation through AOP.

For implementors, it is recommended to derive from the provided AbstractPlatformTransactionManager class, which pre-implements the defined propagation behavior and completely handles transaction synchronization. Subclasses have to implement template methods for specific states of the underlying transaction, for example: begin, suspend, resume, commit.

The default implementations of this strategy interface are JtaTransactionManager and DataSourceTransactionManager, which can serve as implementation guide for other transaction strategies.

Since:
16.05.2003
Author:
Rod Johnson, Juergen Hoeller
See Also:
TransactionTemplate, TransactionInterceptor, TransactionProxyFactoryBean, AbstractPlatformTransactionManager, JtaTransactionManager, DataSourceTransactionManager

Method Summary
 void commit(TransactionStatus status)
          Commit the given transaction, with regard to its status.
 TransactionStatus getTransaction(TransactionDefinition definition)
          Return a currently active transaction or create a new one, according to the specified propagation behavior.
 void rollback(TransactionStatus status)
          Perform a rollback of the given transaction.
 

Method Detail

getTransaction

TransactionStatus getTransaction(TransactionDefinition definition)
                                 throws TransactionException
Return a currently active transaction or create a new one, according to the specified propagation behavior.

Note that parameters like isolation level or timeout will only be applied to new transactions, and thus be ignored when participating in active ones.

Furthermore, not all transaction definition settings will be supported by every transaction manager: A proper transaction manager implementation should thrown an exception when unsupported settings are encountered.

An exception to the above rule is the read-only flag, which should be ignored if no explicit read-only mode is supported. Essentially, the read-only flag is just a hint for potential optimization.

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:
TransactionDefinition.getPropagationBehavior(), TransactionDefinition.getIsolationLevel(), TransactionDefinition.getTimeout(), TransactionDefinition.isReadOnly()

commit

void commit(TransactionStatus status)
            throws TransactionException
Commit the given transaction, with regard to its status. If the transaction has been marked rollback-only programmatically, perform a rollback.

If the transaction wasn't a new one, omit the commit for proper participation in the surrounding transaction. If a previous transaction has been suspended to be able to create a new one, resume the previous transaction after committing the new one.

Note that when the commit call completes, no matter if normally or throwing an exception, the transaction must be fully completed and cleaned up. No rollback call should be expected in such a case.

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

rollback

void rollback(TransactionStatus status)
              throws TransactionException
Perform a rollback of the given transaction.

If the transaction wasn't a new one, just set it rollback-only for proper participation in the surrounding transaction. If a previous transaction has been suspended to be able to create a new one, resume the previous transaction after rolling back the new one.

Do not call rollback on a transaction if commit threw an exception. The transaction will already have been completed and cleaned up when commit returns, even in case of a commit exception. Consequently, a rollback call after commit failure will lead to an IllegalTransactionStateException.

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)

The Spring Framework

Copyright © 2002-2007 The Spring Framework.