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

org.springframework.test

## Class AbstractTransactionalSpringContextTests

- java.lang.Object
- - junit.framework.Assert
  - - junit.framework.TestCase
    - - org.springframework.test.ConditionalTestCase
      - - org.springframework.test.AbstractSpringContextTests
        - - org.springframework.test.AbstractSingleSpringContextTests
          - - org.springframework.test.AbstractDependencyInjectionSpringContextTests
            - - org.springframework.test.AbstractTransactionalSpringContextTests

- All Implemented Interfaces:
    junit.framework.Test
  Direct Known Subclasses:
    AbstractTransactionalDataSourceSpringContextTests

  Deprecated.
  as of Spring 3.0, in favor of using the listener-based test context framework (`AbstractTransactionalJUnit4SpringContextTests`)

      @Deprecated
      public abstract class AbstractTransactionalSpringContextTests
      extends AbstractDependencyInjectionSpringContextTests

  Convenient base class for JUnit 3.8 based tests that should occur in a transaction, but normally will roll the transaction back on the completion of each test.

  This is useful in a range of circumstances, allowing the following benefits:

  - Ability to delete or insert any data in the database, without affecting other tests
  - Providing a transactional context for any code requiring a transaction
  - Ability to write anything to the database without any need to clean up.

  This class is typically very fast, compared to traditional setup/teardown scripts.

  If data should be left in the database, call the `setComplete()` method in each test. The `"defaultRollback"` property, which defaults to "true", determines whether transactions will complete by default.

  It is even possible to end the transaction early; for example, to verify lazy loading behavior of an O/R mapping tool. (This is a valuable away to avoid unexpected errors when testing a web UI, for example.) Simply call the `endTransaction()` method. Execution will then occur without a transactional context.

  The `startNewTransaction()` method may be called after a call to `endTransaction()` if you wish to create a new transaction, quite independent of the old transaction. The new transaction's default fate will be to roll back, unless `setComplete()` is called again during the scope of the new transaction. Any number of transactions may be created and ended in this way. The final transaction will automatically be rolled back when the test case is torn down.

  Transactional behavior requires a single bean in the context implementing the `PlatformTransactionManager` interface. This will be set by the superclass's Dependency Injection mechanism. If using the superclass's Field Injection mechanism, the implementation should be named "transactionManager". This mechanism allows the use of the `AbstractDependencyInjectionSpringContextTests` superclass even when there is more than one transaction manager in the context.

  This base class can also be used without transaction management, if no PlatformTransactionManager bean is found in the context provided. Be careful about using this mode, as it allows the potential to permanently modify data. This mode is available only if dependency checking is turned off in the `AbstractDependencyInjectionSpringContextTests` superclass. The non-transactional capability is provided to enable use of the same subclass in different environments.

  Since:
    1.1.1
  Author:
    Rod Johnson, Juergen Hoeller, Sam Brannen

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected TransactionDefinition` | `transactionDefinition` Deprecated. Transaction definition used by this test class: by default, a plain DefaultTransactionDefinition.
    `protected PlatformTransactionManager` | `transactionManager` Deprecated. The transaction manager to use
    `protected TransactionStatus` | `transactionStatus` Deprecated. TransactionStatus for this test.

    - ### Fields inherited from class org.springframework.test.AbstractDependencyInjectionSpringContextTests

      `AUTOWIRE_BY_NAME, AUTOWIRE_BY_TYPE, AUTOWIRE_NO`

    - ### Fields inherited from class org.springframework.test.AbstractSingleSpringContextTests

      `applicationContext`

    - ### Fields inherited from class org.springframework.test.ConditionalTestCase

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractTransactionalSpringContextTests()` Deprecated. Default constructor for AbstractTransactionalSpringContextTests.
    `AbstractTransactionalSpringContextTests(String name)` Deprecated. Constructor for AbstractTransactionalSpringContextTests with a JUnit name.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `endTransaction()` Deprecated. Immediately force a commit or rollback of the transaction, according to the `complete` and `rollback` flags.
    `protected boolean` | `isDefaultRollback()` Deprecated. Get the default rollback flag for this test.
    `protected boolean` | `isRollback()` Deprecated. Determines whether or not to rollback transactions for the current test.
    `protected void` | `onSetUp()` Deprecated. This implementation creates a transaction before test execution.
    `protected void` | `onSetUpBeforeTransaction()` Deprecated. Subclasses can override this method to perform any setup operations, such as populating a database table, before the transaction created by this class.
    `protected void` | `onSetUpInTransaction()` Deprecated. Subclasses can override this method to perform any setup operations, such as populating a database table, within the transaction created by this class.
    `protected void` | `onTearDown()` Deprecated. This implementation ends the transaction after test execution.
    `protected void` | `onTearDownAfterTransaction()` Deprecated. Subclasses can override this method to perform cleanup after a transaction here.
    `protected void` | `onTearDownInTransaction()` Deprecated. Subclasses can override this method to run invariant tests here.
    `protected void` | `preventTransaction()` Deprecated. Call this method in an overridden `ConditionalTestCase.runBare()` method to prevent transactional execution.
    `protected void` | `setComplete()` Deprecated. Cause the transaction to commit for this test method, even if the test method is configured to `rollback`.
    `void` | `setDefaultRollback(boolean defaultRollback)` Deprecated. Subclasses can set this value in their constructor to change the default, which is always to roll the transaction back.
    `protected void` | `setTransactionDefinition(TransactionDefinition customDefinition)` Deprecated. Call this method in an overridden `ConditionalTestCase.runBare()` method to override the transaction attributes that will be used, so that `AbstractSingleSpringContextTests.setUp()` and `AbstractSingleSpringContextTests.tearDown()` behavior is modified.
    `void` | `setTransactionManager(PlatformTransactionManager transactionManager)` Deprecated. Specify the transaction manager to use.
    `protected void` | `startNewTransaction()` Deprecated. Start a new transaction.

    - ### Methods inherited from class org.springframework.test.AbstractDependencyInjectionSpringContextTests

      `getAutowireMode, injectDependencies, isDependencyCheck, isPopulateProtectedVariables, prepareTestInstance, setAutowireMode, setDependencyCheck, setPopulateProtectedVariables`

    - ### Methods inherited from class org.springframework.test.AbstractSingleSpringContextTests

      `contextKey, createApplicationContext, createBeanDefinitionReader, customizeBeanFactory, getApplicationContext, getConfigLocations, getConfigPath, getConfigPaths, getLoadCount, loadContext, loadContextLocations, prepareApplicationContext, setDirty, setUp, tearDown`

    - ### Methods inherited from class org.springframework.test.AbstractSpringContextTests

      `addContext, contextKeyString, getContext, hasCachedContext, isContextKeyEmpty, setDirty`

    - ### Methods inherited from class org.springframework.test.ConditionalTestCase

      `getDisabledTestCount, isDisabledInThisEnvironment, recordDisabled, runBare`

    - ### Methods inherited from class junit.framework.TestCase

      `countTestCases, createResult, getName, run, run, runTest, setName, toString`

    - ### Methods inherited from class junit.framework.Assert

      `assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertFalse, assertFalse, assertNotNull, assertNotNull, assertNotSame, assertNotSame, assertNull, assertNull, assertSame, assertSame, assertTrue, assertTrue, fail, fail, failNotEquals, failNotSame, failSame, format`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### transactionManager

          protected PlatformTransactionManager transactionManager

      Deprecated.
      The transaction manager to use

    - #### transactionDefinition

          protected TransactionDefinition transactionDefinition

      Deprecated.
      Transaction definition used by this test class: by default, a plain DefaultTransactionDefinition. Subclasses can change this to cause different behavior.

    - #### transactionStatus

          protected TransactionStatus transactionStatus

      Deprecated.
      TransactionStatus for this test. Typical subclasses won't need to use it.

  - ### Constructor Detail

    - #### AbstractTransactionalSpringContextTests

          public AbstractTransactionalSpringContextTests()

      Deprecated.
      Default constructor for AbstractTransactionalSpringContextTests.

    - #### AbstractTransactionalSpringContextTests

          public AbstractTransactionalSpringContextTests(String name)

      Deprecated.
      Constructor for AbstractTransactionalSpringContextTests with a JUnit name.

  - ### Method Detail

    - #### setTransactionManager

          public void setTransactionManager(PlatformTransactionManager transactionManager)

      Deprecated.
      Specify the transaction manager to use. No transaction management will be available if this is not set. Populated through dependency injection by the superclass.

      This mode works only if dependency checking is turned off in the `AbstractDependencyInjectionSpringContextTests` superclass.

    - #### setDefaultRollback

          public void setDefaultRollback(boolean defaultRollback)

      Deprecated.
      Subclasses can set this value in their constructor to change the default, which is always to roll the transaction back.

    - #### isDefaultRollback

          protected boolean isDefaultRollback()

      Deprecated.
      Get the default rollback flag for this test.
      Returns:
        The default rollback flag.
      See Also:
        `setDefaultRollback(boolean)`

    - #### isRollback

          protected boolean isRollback()

      Deprecated.
      Determines whether or not to rollback transactions for the current test.

      The default implementation delegates to `isDefaultRollback()`. Subclasses can override as necessary.

    - #### preventTransaction

          protected void preventTransaction()

      Deprecated.
      Call this method in an overridden `ConditionalTestCase.runBare()` method to prevent transactional execution.

    - #### setTransactionDefinition

          protected void setTransactionDefinition(TransactionDefinition customDefinition)

      Deprecated.
      Call this method in an overridden `ConditionalTestCase.runBare()` method to override the transaction attributes that will be used, so that `AbstractSingleSpringContextTests.setUp()` and `AbstractSingleSpringContextTests.tearDown()` behavior is modified.
      Parameters:
        `customDefinition` - the custom transaction definition

    - #### onSetUp

          protected void onSetUp()
                          throws Exception

      Deprecated.
      This implementation creates a transaction before test execution.

      Override `onSetUpBeforeTransaction()` and/or `onSetUpInTransaction()` to add custom set-up behavior for transactional execution. Alternatively, override this method for general set-up behavior, calling `super.onSetUp()` as part of your method implementation.

      Overrides:
        `onSetUp` in class `AbstractSingleSpringContextTests`
      Throws:
        `Exception` - simply let any exception propagate
      See Also:
        `onTearDown()`

    - #### onSetUpBeforeTransaction

          protected void onSetUpBeforeTransaction()
                                           throws Exception

      Deprecated.
      Subclasses can override this method to perform any setup operations, such as populating a database table, before the transaction created by this class. Only invoked if there is a transaction: that is, if `preventTransaction()` has not been invoked in an overridden `TestCase.runTest()` method.
      Throws:
        `Exception` - simply let any exception propagate

    - #### onSetUpInTransaction

          protected void onSetUpInTransaction()
                                       throws Exception

      Deprecated.
      Subclasses can override this method to perform any setup operations, such as populating a database table, within the transaction created by this class.

      NB: Not called if there is no transaction management, due to no transaction manager being provided in the context.

      If any `Throwable` is thrown, the transaction that has been started prior to the execution of this method will be `ended` (or rather an attempt will be made to `end it gracefully`); The offending `Throwable` will then be rethrown.

      Throws:
        `Exception` - simply let any exception propagate

    - #### onTearDown

          protected void onTearDown()
                             throws Exception

      Deprecated.
      This implementation ends the transaction after test execution.

      Override `onTearDownInTransaction()` and/or `onTearDownAfterTransaction()` to add custom tear-down behavior for transactional execution. Alternatively, override this method for general tear-down behavior, calling `super.onTearDown()` as part of your method implementation.

      Note that `onTearDownInTransaction()` will only be called if a transaction is still active at the time of the test shutdown. In particular, it will not be called if the transaction has been completed with an explicit `endTransaction()` call before.

      Overrides:
        `onTearDown` in class `AbstractSingleSpringContextTests`
      Throws:
        `Exception` - simply let any exception propagate
      See Also:
        `onSetUp()`

    - #### onTearDownInTransaction

          protected void onTearDownInTransaction()
                                          throws Exception

      Deprecated.
      Subclasses can override this method to run invariant tests here. The transaction is still active at this point, so any changes made in the transaction will still be visible. However, there is no need to clean up the database, as a rollback will follow automatically.

      NB: Not called if there is no actual transaction, for example due to no transaction manager being provided in the application context.

      Throws:
        `Exception` - simply let any exception propagate

    - #### onTearDownAfterTransaction

          protected void onTearDownAfterTransaction()
                                             throws Exception

      Deprecated.
      Subclasses can override this method to perform cleanup after a transaction here. At this point, the transaction is not active anymore.
      Throws:
        `Exception` - simply let any exception propagate

    - #### setComplete

          protected void setComplete()

      Deprecated.
      Cause the transaction to commit for this test method, even if the test method is configured to `rollback`.
      Throws:
        `IllegalStateException` - if the operation cannot be set to complete as no transaction manager was provided

    - #### endTransaction

          protected void endTransaction()

      Deprecated.
      Immediately force a commit or rollback of the transaction, according to the `complete` and `rollback` flags.

      Can be used to explicitly let the transaction end early, for example to check whether lazy associations of persistent objects work outside of a transaction (that is, have been initialized properly).

      See Also:
        `setComplete()`

    - #### startNewTransaction

          protected void startNewTransaction()
                                      throws TransactionException

      Deprecated.
      Start a new transaction. Only call this method if `endTransaction()` has been called. `setComplete()` can be used again in the new transaction. The fate of the new transaction, by default, will be the usual rollback.
      Throws:
        `TransactionException` - if starting the transaction failed