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` that provides support for executing tests within transactions by honoring the `@Transactional` and `@NotTransactional` annotations. Expects a `PlatformTransactionManager` bean to be defined in the Spring `ApplicationContext` for the test.

Changes to the database during a test that is 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 that is run with `@NotTransactional` will not 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.

Transactional commit and rollback behavior can be configured via the class-level `@TransactionConfiguration` and method-level `@Rollback` annotations.

In case there are multiple instances of `PlatformTransactionManager` within the test's `ApplicationContext`, `@TransactionConfiguration` supports configuring the bean name of the `PlatformTransactionManager` that should be used to drive transactions. Alternatively, `TransactionManagementConfigurer` can be implemented in an `@Configuration` class.

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` and `@AfterTransaction`.

Since:
  2.5
Author:
  Sam Brannen, Juergen Hoeller
See Also:
  `TransactionConfiguration`, `TransactionManagementConfigurer`, `Transactional`, `NotTransactional`, `Rollback`, `BeforeTransaction`, `AfterTransaction`

### Field Summary

Fields
`protected TransactionAttributeSource` `attributeSource`

### Constructor Summary

Constructors
Constructor and Description
`TransactionalTestExecutionListener()`

### Method Summary

Methods
`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 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

#### 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`, `NotTransactional`, `getTransactionManager(TestContext, String)`

#### 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; 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 final 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 final PlatformTransactionManager getTransactionManager(TestContext testContext)

Get 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:
  `BeansException` - if an error occurs while retrieving the transaction manager
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`.

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