TransactionalTestExecutionListener (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

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
    Modifier and Type | Field and Description
    --- | ---
    `protected TransactionAttributeSource` | `attributeSource`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TransactionalTestExecutionListener()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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