org.springframework.test.context.transaction

Class TransactionalTestExecutionListener

java.lang.Object

org.springframework.test.context.support.AbstractTestExecutionListener

org.springframework.test.context.transaction.TransactionalTestExecutionListener

All Implemented Interfaces:

Ordered, TestExecutionListener

public class TransactionalTestExecutionListener
extends AbstractTestExecutionListener

TestExecutionListener that provides support for executing tests within test-managed transactions by honoring Spring's @Transactional annotation.

Test-managed Transactions

Test-managed transactions are transactions that are managed declaratively via this listener or programmatically via TestTransaction. Such transactions should not be confused with Spring-managed transactions (i.e., those managed directly by Spring within the ApplicationContext loaded for tests) or application-managed transactions (i.e., those managed programmatically within application code that is invoked via tests). Spring-managed and application-managed transactions will typically participate in test-managed transactions; however, caution should be taken if Spring-managed or application-managed transactions are configured with any propagation type other than REQUIRED or SUPPORTS.

Enabling and Disabling Transactions

Annotating a test method with @Transactional causes the test to be run within a transaction that will, by default, be automatically rolled back after completion of the test. If a test class is annotated with @Transactional, each test method within that class hierarchy will be run within a transaction. Test methods that are not annotated with @Transactional (at the class or method level) will not be run within a transaction. Furthermore, tests that are annotated with @Transactional but have the propagation type set to NOT_SUPPORTED will not be run within a transaction.

Declarative Rollback and Commit Behavior

By default, test transactions will be automatically rolled back after completion of the test; however, transactional commit and rollback behavior can be configured declaratively via the @Commit and @Rollback annotations at the class level and at the method level.

Programmatic Transaction Management

As of Spring Framework 4.1, it is possible to interact with test-managed transactions programmatically via the static methods in TestTransaction. TestTransaction may be used within test methods, before methods, and after methods.

Executing Code outside of a Transaction

When executing transactional tests, it is sometimes useful to be able to execute certain set up or tear down code outside of a transaction. TransactionalTestExecutionListener provides such support for methods annotated with @BeforeTransaction or @AfterTransaction. As of Spring Framework 4.3, @BeforeTransaction and @AfterTransaction may also be declared on Java 8 based interface default methods.

Configuring a Transaction Manager

TransactionalTestExecutionListener expects a PlatformTransactionManager bean to be defined in the Spring ApplicationContext for the test. In case there are multiple instances of PlatformTransactionManager within the test's ApplicationContext, a qualifier may be declared via @Transactional (e.g., @Transactional("myTxMgr") or @Transactional(transactionManger = "myTxMgr"), or TransactionManagementConfigurer can be implemented by an @Configuration class. See TestContextTransactionUtils.retrieveTransactionManager(org.springframework.test.context.TestContext, java.lang.String) for details on the algorithm used to look up a transaction manager in the test's ApplicationContext.

Since:

2.5

Author:

Sam Brannen, Juergen Hoeller

See Also:

TransactionManagementConfigurer, Transactional, Commit, Rollback, BeforeTransaction, AfterTransaction, TestTransaction

Field Summary

Fields

Modifier and Type	Field and Description
protected TransactionAttributeSource	attributeSource

Fields inherited from interface org.springframework.core.Ordered

HIGHEST_PRECEDENCE, LOWEST_PRECEDENCE

Constructor Summary

Constructors

Constructor and Description
TransactionalTestExecutionListener()

Method Summary

Modifier and Type	Method and Description
void	afterTestMethod(TestContext testContext) If a transaction is currently active for the supplied test context, this method will end the transaction and run @AfterTransaction methods.
void	beforeTestMethod(TestContext testContext) If the test method of the supplied test context is configured to run within a transaction, this method will run @BeforeTransaction methods and start a new transaction.
int	getOrder() Returns 4000.
protected PlatformTransactionManager	getTransactionManager(TestContext testContext) Get the transaction manager to use for the supplied test context.
protected PlatformTransactionManager	getTransactionManager(TestContext testContext, String qualifier) Get the transaction manager to use for the supplied test context and qualifier.
protected boolean	isDefaultRollback(TestContext testContext) Determine whether or not to rollback transactions by default for the supplied test context.
protected boolean	isRollback(TestContext testContext) Determine whether or not to rollback transactions for the supplied test context by taking into consideration the default rollback flag and a possible method-level override via the @Rollback annotation.
protected void	runAfterTransactionMethods(TestContext testContext) Run all @AfterTransaction methods for the specified test context.
protected void	runBeforeTransactionMethods(TestContext testContext) Run all @BeforeTransaction methods for the specified test context.

Methods inherited from class org.springframework.test.context.support.AbstractTestExecutionListener

afterTestClass, beforeTestClass, prepareTestInstance

Methods inherited from class java.lang.Object

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

Field Detail

attributeSource

protected final TransactionAttributeSource attributeSource

Constructor Detail

TransactionalTestExecutionListener

public TransactionalTestExecutionListener()

Method Detail

getOrder

public final int getOrder()

Returns 4000.

Specified by:

getOrder in interface Ordered

Overrides:

getOrder in class AbstractTestExecutionListener

Returns:

the order value

See Also:

Ordered.HIGHEST_PRECEDENCE, Ordered.LOWEST_PRECEDENCE

beforeTestMethod

public void beforeTestMethod(TestContext testContext)
                      throws Exception

If the test method of the supplied test context is configured to run within a transaction, this method will run @BeforeTransaction methods and start a new transaction.

Note that if a @BeforeTransaction method fails, any remaining @BeforeTransaction methods will not be invoked, and a transaction will not be started.

Specified by:

beforeTestMethod in interface TestExecutionListener

Overrides:

beforeTestMethod in class AbstractTestExecutionListener

Parameters:

testContext - the test context in which the test method will be executed; never null

Throws:

Exception - allows any exception to propagate

See Also:

Transactional, getTransactionManager(TestContext, String)

afterTestMethod

public void afterTestMethod(TestContext testContext)
                     throws Exception

If a transaction is currently active for the supplied test context, this method will end the transaction and run @AfterTransaction methods.

@AfterTransaction methods are guaranteed to be invoked even if an error occurs while ending the transaction.

Specified by:

afterTestMethod in interface TestExecutionListener

Overrides:

afterTestMethod in class AbstractTestExecutionListener

Parameters:

testContext - the test context in which the test method was executed; never null

Throws:

Exception - allows any exception to propagate

runBeforeTransactionMethods

protected void runBeforeTransactionMethods(TestContext testContext)
                                    throws Exception

Run all @BeforeTransaction methods for the specified test context. If one of the methods fails, however, the caught exception will be rethrown in a wrapped RuntimeException, and the remaining methods will not be given a chance to execute.

Parameters:

testContext - the current test context

Throws:

Exception

runAfterTransactionMethods

protected void runAfterTransactionMethods(TestContext testContext)
                                   throws Exception

Run all @AfterTransaction methods for the specified test context. If one of the methods fails, the caught exception will be logged as an error, and the remaining methods will be given a chance to execute. After all methods have executed, the first caught exception, if any, will be rethrown.

Parameters:

testContext - the current test context

Throws:

Exception

getTransactionManager

protected PlatformTransactionManager getTransactionManager(TestContext testContext,
                                                           String qualifier)

Get the transaction manager to use for the supplied test context and qualifier.

Delegates to getTransactionManager(TestContext) if the supplied qualifier is null or empty.

Parameters:

testContext - the test context for which the transaction manager should be retrieved

qualifier - the qualifier for selecting between multiple bean matches; may be null or empty

Returns:

the transaction manager to use, or null if not found

Throws:

BeansException - if an error occurs while retrieving the transaction manager

See Also:

getTransactionManager(TestContext)

getTransactionManager

protected PlatformTransactionManager getTransactionManager(TestContext testContext)

Get the transaction manager to use for the supplied test context.

The default implementation simply delegates to TestContextTransactionUtils.retrieveTransactionManager(org.springframework.test.context.TestContext, java.lang.String).

Parameters:

testContext - the test context for which the transaction manager should be retrieved

Returns:

the transaction manager to use, or null if not found

Throws:

BeansException - if an error occurs while retrieving an explicitly named transaction manager

IllegalStateException - if more than one TransactionManagementConfigurer exists in the ApplicationContext

See Also:

getTransactionManager(TestContext, String)

isDefaultRollback

protected final boolean isDefaultRollback(TestContext testContext)
                                   throws Exception

Determine whether or not to rollback transactions by default for the supplied test context.

Supports @Rollback, @Commit, or @TransactionConfiguration at the class-level.

Parameters:

testContext - the test context for which the default rollback flag should be retrieved

Returns:

the default rollback flag for the supplied test context

Throws:

Exception - if an error occurs while determining the default rollback flag

isRollback

protected final boolean isRollback(TestContext testContext)
                            throws Exception

Determine whether or not to rollback transactions for the supplied test context by taking into consideration the default rollback flag and a possible method-level override via the @Rollback annotation.

Parameters:

testContext - the test context for which the rollback flag should be retrieved

Returns:

the rollback flag for the supplied test context

Throws:

Exception - if an error occurs while determining the rollback flag