org.springframework.test
Class AbstractTransactionalSpringContextTests

java.lang.Object
  extended by junit.framework.Assert
      extended by junit.framework.TestCase
          extended by org.springframework.test.AbstractSpringContextTests
              extended by org.springframework.test.AbstractDependencyInjectionSpringContextTests
                  extended by org.springframework.test.AbstractTransactionalSpringContextTests
All Implemented Interfaces:
Test
Direct Known Subclasses:
AbstractTransactionalDataSourceSpringContextTests

public abstract class AbstractTransactionalSpringContextTests
extends AbstractDependencyInjectionSpringContextTests

Convenient superclass for 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:

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 this superclass even when there's more than one transaction manager in the context.

This superclass 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

Field Summary
protected  PlatformTransactionManager transactionManager
          The transaction manager to use
protected  TransactionStatus transactionStatus
          TransactionStatus for this test.
 
Fields inherited from class org.springframework.test.AbstractDependencyInjectionSpringContextTests
applicationContext, AUTOWIRE_BY_NAME, AUTOWIRE_BY_TYPE, AUTOWIRE_NO, managedVariableNames
 
Fields inherited from class org.springframework.test.AbstractSpringContextTests
logger
 
Constructor Summary
AbstractTransactionalSpringContextTests()
          Default constructor for AbstractTransactionalSpringContextTests.
AbstractTransactionalSpringContextTests(String name)
          Constructor for AbstractTransactionalSpringContextTests with a JUnit name.
 
Method Summary
protected  void endTransaction()
          Immediately force a commit or rollback of the transaction, according to the complete flag.
protected  void onSetUp()
          This implementation creates a transaction before test execution.
protected  void onSetUpBeforeTransaction()
          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()
          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()
          This implementation ends the transaction after test execution.
protected  void onTearDownAfterTransaction()
          Subclasses can override this method to perform cleanup after a transaction here.
protected  void onTearDownInTransaction()
          Subclasses can override this method to run invariant tests here.
protected  void preventTransaction()
          Call in an overridden runBare() method to prevent transactional execution.
protected  void setComplete()
          Cause the transaction to commit for this test method, even if default is set to rollback.
 void setDefaultRollback(boolean defaultRollback)
          Subclasses can set this value in their constructor to change default, which is always to roll the transaction back.
protected  void setTransactionDefinition(TransactionDefinition customDefinition)
          Override the transaction attributes that will be used.
 void setTransactionManager(PlatformTransactionManager ptm)
          Specify the transaction manager to use.
protected  void startNewTransaction()
          Start a new transaction.
 
Methods inherited from class org.springframework.test.AbstractDependencyInjectionSpringContextTests
contextKey, getAutowireMode, getConfigLocations, getLoadCount, initManagedVariableNames, isDependencyCheck, isPopulateProtectedVariables, loadContextLocations, populateProtectedVariables, setAutowireMode, setDependencyCheck, setDirty, setPopulateProtectedVariables, setUp, tearDown
 
Methods inherited from class org.springframework.test.AbstractSpringContextTests
contextKeyString, getContext, hasCachedContext, loadContext, setDirty
 
Methods inherited from class junit.framework.TestCase
countTestCases, createResult, getName, run, run, runBare, 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
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

transactionManager

protected PlatformTransactionManager transactionManager
The transaction manager to use


transactionStatus

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

Constructor Detail

AbstractTransactionalSpringContextTests

public AbstractTransactionalSpringContextTests()
Default constructor for AbstractTransactionalSpringContextTests.


AbstractTransactionalSpringContextTests

public AbstractTransactionalSpringContextTests(String name)
Constructor for AbstractTransactionalSpringContextTests with a JUnit name.

Method Detail

setTransactionManager

public void setTransactionManager(PlatformTransactionManager ptm)
Specify the transaction manager to use. No transaction management will be available if this is not set. (This mode works only if dependency checking is turned off in the AbstractDependencyInjectionSpringContextTests superclass.)

Populated through dependency injection by the superclass.


setDefaultRollback

public void setDefaultRollback(boolean defaultRollback)
Subclasses can set this value in their constructor to change default, which is always to roll the transaction back.


preventTransaction

protected void preventTransaction()
Call in an overridden runBare() method to prevent transactional execution.


setTransactionDefinition

protected void setTransactionDefinition(TransactionDefinition customDefinition)
Override the transaction attributes that will be used. Call in an overridden runBare() method so that setUp() and tearDown() behavior is modified.

Parameters:
customDefinition - custom definition to override with

onSetUp

protected final void onSetUp()
                      throws Exception
This implementation creates a transaction before test execution. Override onSetUpBeforeTransaction() and/or onSetUpInTransaction() to add custom set-up behavior.

Overrides:
onSetUp in class AbstractDependencyInjectionSpringContextTests
Throws:
Exception - simply let any exception propagate
See Also:
onSetUpBeforeTransaction(), onSetUpInTransaction()

onSetUpBeforeTransaction

protected void onSetUpBeforeTransaction()
                                 throws Exception
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 runTest() method.

Throws:
Exception - simply let any exception propagate
See Also:
preventTransaction()

onSetUpInTransaction

protected void onSetUpInTransaction()
                             throws Exception
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 final void onTearDown()
                         throws Exception
This implementation ends the transaction after test execution. Override onTearDownInTransaction() and/or onTearDownAfterTransaction() to add custom tear-down behavior.

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 AbstractDependencyInjectionSpringContextTests
Throws:
Exception - simply let any exception propagate
See Also:
onTearDownInTransaction(), onTearDownAfterTransaction(), endTransaction()

onTearDownInTransaction

protected void onTearDownInTransaction()
                                throws Exception
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
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()
                    throws UnsupportedOperationException
Cause the transaction to commit for this test method, even if default is set to rollback.

Throws:
IllegalStateException - if the operation cannot be set to complete as no transaction manager was provided
UnsupportedOperationException

endTransaction

protected void endTransaction()
Immediately force a commit or rollback of the transaction, according to the complete flag.

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
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
See Also:
endTransaction(), setComplete()


Copyright (c) 2002-2007 The Spring Framework Project.