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:

TestExecutionListener

public class TransactionalTestExecutionListener
extends AbstractTestExecutionListener

TestExecutionListener which provides support for executing tests within transactions by using @Transactional and @NotTransactional annotations.

Changes to the database during a test run with @Transactional will be run within a transaction that will, by default, be automatically rolled back after completion of the test; whereas, changes to the database during a test run with @NotTransactional will not be run within a transaction. Similarly, test methods that are not annotated with either @Transactional (at the class or method level) or @NotTransactional will not be run within a transaction.

Transactional commit and rollback behavior can be configured via the class-level @TransactionConfiguration and method-level @Rollback annotations. @TransactionConfiguration also provides configuration of the bean name of the PlatformTransactionManager that is to be used to drive transactions.

When executing transactional tests, it is sometimes useful to be able execute certain set up or tear down code outside of a transaction. TransactionalTestExecutionListener provides such support for methods annotated with @BeforeTransaction and @AfterTransaction.

Since:

2.5

Author:

Sam Brannen, Juergen Hoeller

See Also:

TransactionConfiguration, Transactional, NotTransactional, Rollback, BeforeTransaction, AfterTransaction

Field Summary

protected TransactionAttributeSource	transactionAttributeSource TransactionAttributeSource for the current test.
protected TransactionDefinition	transactionDefinition Transaction definition used by this TransactionalTestExecutionListener.
protected TransactionStatus	transactionStatus TransactionStatus for the current test.

Constructor Summary

TransactionalTestExecutionListener()

Method Summary

void	afterTestMethod(TestContext testContext) If a transaction is currently active for the test method of 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.
protected void	endTransaction(TestContext testContext) Immediately force a commit or rollback of the transaction for the supplied test context, according to the commit and rollback flags.
protected void	flagTransactionForCommit(TestContext testContext) Flag the current transaction for commit, thus causing the transaction to be committed for the current test method, even if the rollback flag is true.
protected PlatformTransactionManager	getTransactionManager(TestContext testContext) Gets the transaction manager to use for the supplied test context.
protected boolean	isDefaultRollback(TestContext testContext) Determines whether or not to rollback transactions by default for the supplied test context.
protected boolean	isRollback(TestContext testContext) Determines 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 boolean	isTransactionFlaggedForCommit(TestContext testContext) Has the current transaction for the supplied test context been flagged for commit?
protected void	runAfterTransactionMethods(TestContext testContext) Runs all @AfterTransaction methods for the specified test context.
protected void	runBeforeTransactionMethods(TestContext testContext) Runs all @BeforeTransaction methods for the specified test context.
protected void	startNewTransaction(TestContext testContext) Start a new transaction for the supplied test context.

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

prepareTestInstance

Methods inherited from class java.lang.Object

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

Field Detail

transactionAttributeSource

protected final TransactionAttributeSource transactionAttributeSource

TransactionAttributeSource for the current test. Typical subclasses won't need to use it.

transactionDefinition

protected TransactionDefinition transactionDefinition

Transaction definition used by this TransactionalTestExecutionListener.

transactionStatus

protected TransactionStatus transactionStatus

TransactionStatus for the current test. Typical subclasses won't need to use it.

Constructor Detail

TransactionalTestExecutionListener

public TransactionalTestExecutionListener()

Method Detail

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, 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, not null

Throws:

Exception - allows any exception to propagate

See Also:

Transactional, NotTransactional

afterTestMethod

public void afterTestMethod(TestContext testContext)
                     throws Exception

If a transaction is currently active for the test method of 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, not null

Throws:

Exception - allows any exception to propagate

See Also:

TestExecutionListener.afterTestMethod(TestContext)

runBeforeTransactionMethods

protected void runBeforeTransactionMethods(TestContext testContext)
                                    throws Exception

Runs 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

Runs 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

startNewTransaction

protected void startNewTransaction(TestContext testContext)
                            throws TransactionException,
                                   Exception

Start a new transaction for the supplied test context.

Only call this method if endTransaction(org.springframework.test.context.TestContext) has been called or if no transaction has been previously started.

flagTransactionForCommit(TestContext) can be used in the new transaction. The fate of the new transaction will then, by default, be determined by the configured rollback flag.

Parameters:

testContext - the current test context.

Throws:

TransactionException - if starting the transaction fails.

Exception - if an error occurs while retrieving the transaction manager.

endTransaction

protected void endTransaction(TestContext testContext)
                       throws TransactionException,
                              Exception

Immediately force a commit or rollback of the transaction for the supplied test context, according to the commit and rollback flags.

Parameters:

testContext - the current test context.

Throws:

TransactionException - if ending the transaction fails.

Exception - if an error occurs while retrieving the transaction manager.

See Also:

isTransactionFlaggedForCommit(TestContext)

getTransactionManager

protected final PlatformTransactionManager getTransactionManager(TestContext testContext)
                                                          throws Exception

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

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:

Exception - if an error occurs while retrieving the transaction manager.

isDefaultRollback

protected final boolean isDefaultRollback(TestContext testContext)
                                   throws Exception

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

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

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

isTransactionFlaggedForCommit

protected final boolean isTransactionFlaggedForCommit(TestContext testContext)

Has the current transaction for the supplied test context been flagged for commit? In other words, should the current transaction be committed upon completion of the current test regardless of the value of the rollback flag?

Parameters:

testContext - the current test context.

Returns:

the transactionFlaggedForCommit flag.

See Also:

flagTransactionForCommit(TestContext), isRollback(TestContext)

flagTransactionForCommit

protected final void flagTransactionForCommit(TestContext testContext)
                                       throws IllegalStateException

Flag the current transaction for commit, thus causing the transaction to be committed for the current test method, even if the rollback flag is true.

Throws:

IllegalStateException - if the transaction cannot be flagged for commit because no transaction manager was provided.

See Also:

isRollback(TestContext)