The preferred approach is to use Spring's high level persistence integration APIs. These do not replace native APIs, but internally handle resource creation/reuse, cleanup, and optional transaction synchronization (i.e. event notification) of the resources and exception mapping so that user data access code doesn't have to worry about these concerns at all, but can concentrate purely on non-boilerplate persistence logic. Generally, the same inversion of control approach is used for all persistence APIs. In this approach the API has a callback method or delegate that presents the user code with the relevant resource ready to use - i.e. a DbCommand with its Connection and Transaction properties set based on the transaction option metadata. These classes go by the naming scheme 'template', examples of which are AdoTemplate and HibernateTemplate. Convenient 'one-liner' helper methods in these template classes build upon the core callback/IoC design by providing specific implementations of the callback interface.

A utility class can be used to directly obtain a connection/transaction pair that is aware of the transactional calling context and returns a pair suitable for that context. The class ConnectionUtils contains the static method ConnectionTxPair GetConnectionTxPair(IDbProvider provider) which serves this purpose.

public class LowLevelIntegration
{
  // Spring's IDbProvider abstraction 
  private IDbProvider dbProvider;

  public IDbProvider dbProvider  
  {
    set { dbProvider = value; }
  }
  
  public void DoWork() {
    ConnectionTxPair connTxPair = ConnectionUtils.GetConnectionTxPair(dbProvider);
    //Use some data access library that allows you to pass in the transaction

    DbWrapper dbWrapper = new DbWrapper();
    string cmdText = ... // some command text
    dbWrapper.ExecuteNonQuery(cmdText, connTxPair.Transaction);
  }
}

It is not sufficient to tell you simply to annotate your classes with the [Transaction] attribute, add the line (<tx:attribute-driven/>) to your configuration, and then expect you to understand how it all works. This section explains the inner workings of the Spring Framework's declarative transaction infrastructure in the event of transaction-related issues.

The most important concepts to grasp with regard to the Spring Framework's declarative transaction support are that this support is enabled via AOP proxies, and that the transactional advice is driven by metadata (currently XML- or attribute-based). The combination of AOP with transactional metadata yields an AOP proxy that uses a TransactionInterceptor in conjunction with an appropriate IPlatformTransactionManager implementation to drive transactions around method invocations.

	Note
	Spring AOP is covered in Chapter 13, Aspect Oriented Programming with Spring.NET

Conceptually, calling a method on a transactional proxy looks like this.

Consider the following interface. The intent is to convey the concepts to you so you can concentrate on the transaction usage and not have to worry about domain specific details.

	Note
	A QuickStart application for declarative transaction management is included in the Spring.NET distribution and is decribed here.

The ITestObjectManager is a poor-mans business service layer - the implementation of which will make two DAO calls. Clearly this example is overly simplistic from the service layer perspective as there isn't any business logic at all!. The 'service' interface is shown below.

public interface ITestObjectManager 
{
  void SaveTwoTestObjects(TestObject to1, TestObject to2);

  void DeleteTwoTestObjects(string name1, string name2);
}

The implementation of ITestObjectManager is shown below

public class TestObjectManager : ITestObjectManager 
{

   // Fields/Properties ommited

   [Transaction]
   public void SaveTwoTestObjects(TestObject to1, TestObject to2)
   {
     TestObjectDao.Create(to1.Name, to1.Age);
     TestObjectDao.Create(to2.Name, to1.Age);
   }

   [Transaction]
   public void DeleteTwoTestObjects(string name1, string name2)
   {
     TestObjectDao.Delete(name1);
     TestObjectDao.Delete(name2);
   }
}

Note the Transaction attribute on the methods. Other options such as isolation level can also be specified but in this example the default settings are used. However, please note that the mere presence of the Transaction attribute is not enough to actually turn on the transactional behavior - the Transaction attribute is simply metadata that can be consumed by something that is Transaction attribute-aware and that can use the said metadata to configure the appropriate objects with transactional behavior.

The TestObjectDao property has basic create update delete and find method for the 'domain' object TestObject. TestObject in turn has simple properties like name and age.

public interface ITestObjectDao
{
  void Create(string name, int age);
  void Update(TestObject to);
  void Delete(string name);
  TestObject FindByName(string name);
  IList FindAll();
}

The Create and Delete method implementation is shown below. Note that this uses the AdoTemplate class discussed in the following chapter. Refer to Section 17.4, “Resource synchronization with transactions” for information on the interaction between Spring's high level persistence integration APIs and transaction management features.

public class TestObjectDao : AdoDaoSupport, ITestObjectDao
{
   public void Create(string name, int age)
   {
       AdoTemplate.ExecuteNonQuery(CommandType.Text,
           String.Format("insert into TestObjects(Age, Name) VALUES ({0}, '{1}')", 
           age, name));
   }

   public void Delete(string name)
   {
       AdoTemplate.ExecuteNonQuery(CommandType.Text,
           String.Format("delete from TestObjects where Name = '{0}'",
           name));
   }
}

The TestObjectManager is configured with the DAO objects by standard dependency injection techniques. The client code, which in this case directly asks the Spring IoC container for an instance of ITestObjectManager, will receive a transaction proxy with transaction options based on the attribute metadata. Note that typically the ITestObjectManager would be set on yet another higher level object via dependency injection, for example a web service.

The client calling code is shown below

IApplicationContext ctx =
   new XmlApplicationContext("assembly://Spring.Data.Integration.Tests/Spring.Data/autoDeclarativeServices.xml");

ITestObjectManager mgr = ctx["testObjectManager"] as ITestObjectManager; 

TestObject to1 = new TestObject();
to1.Name = "Jack";
to1.Age = 7;

TestObject to2 = new TestObject();
to2.Name = "Jill";
to2.Age = 8;

mgr.SaveTwoTestObjects(to1, to2);

mgr.DeleteTwoTestObjects("Jack", "Jill");

            

The configuration of the object definitions of the DAO and manager classes is shown below.

<objects xmlns='http://www.springframework.net'
         xmlns:db="http://www.springframework.net/database">

    <db:provider id="DbProvider" 
                  provider="SqlServer-1.1" 
                  connectionString="Data Source=(local);Database=Spring;User ID=springqa;Password=springqa;Trusted_Connection=False"/>

    <object id="transactionManager" 
            type="Spring.Data.Core.AdoPlatformTransactionManager, Spring.Data">
            
        <property name="DbProvider" ref="DbProvider"/>
    </object>
        
    <object id="adoTemplate" type="Spring.Data.AdoTemplate, Spring.Data">
        <property name="DbProvider" ref="DbProvider"/>                
    </object>

    <object id="testObjectDao" type="Spring.Data.TestObjectDao, Spring.Data.Integration.Tests">
        <property name="AdoTemplate" ref="adoTemplate"/>
    </object>
            
    
    <!-- The object that performs multiple data access operations -->
    <object id="testObjectManager" type="Spring.Data.TestObjectManager, Spring.Data.Integration.Tests">
        <property name="TestObjectDao" ref="testObjectDao"/>
    </object>
 
    
</objects>

This is standard Spring configuration and as such provides you with the flexibility to parameterize your connection string and to easily switch implementations of your DAO objects.

The following section shows how to configure the declarative transactions using Spring's transaction namespace.

Spring provides a custom XML schema to simplify the configuration of declarative transaction management. If you would like to perform attribute driven transaction management you first need to register the custom namespace parser for the transaction namespace. This can be done in the application configuration file as shown below

<?xml version="1.0" encoding="utf-8" ?>
<configuration>

  <configSections>

    <sectionGroup name="spring">
      <section name="parsers" type="Spring.Context.Support.NamespaceParsersSectionHandler, Spring.Core" />
      
      <!-- other spring config sections like context, typeAliases, etc not shown for brevity -->

    </sectionGroup>
  </configSections>

  <spring>
    
    <parsers>
      <parser type="Spring.Data.Config.DatabaseNamespaceParser, Spring.Data" />
      <parser type="Spring.Transaction.Config.TxNamespaceParser, Spring.Data" />
      <parser type="Spring.Aop.Config.AopNamespaceParser, Spring.Aop" />
    </parsers>

   </spring>

  </configSections>

Instead of using the XML configuration listed at the end of the previous section (declarativeServices.xml you can use the following. Note that the schemaLocation in the objects element is needed only if you have not installed Spring's schema into the proper VS.NET 2005 location. See the chapter on VS.NET integration for more details.

<objects xmlns="http://www.springframework.net"
	        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:tx="http://www.springframework.net/tx"
         xmlns:db="http://www.springframework.net/database"
         xsi:schemaLocation="http://www.springframework.net http://www.springframework.net/schema/objects/spring-objects.xsd
         http://www.springframework.net/schema/tx http://www.springframework.net/schema/tx/spring-tx-1.1.xsd"
         http://www.springframework.net/schema/db http://www.springframework.net/schema/db/spring-database.xsd"> 

    <db:provider id="DbProvider" 
                  provider="SqlServer-1.1" 
                  connectionString="Data Source=(local);Database=Spring;User ID=springqa;Password=springqa;Trusted_Connection=False"/>

    <object id="transactionManager" 
            type="Spring.Data.Core.AdoPlatformTransactionManager, Spring.Data">
            
        <property name="DbProvider" ref="DbProvider"/>
    </object>
        
    <object id="adoTemplate" type="Spring.Data.AdoTemplate, Spring.Data">
        <property name="DbProvider" ref="DbProvider"/>                
    </object>

    <object id="testObjectDao" type="Spring.Data.TestObjectDao, Spring.Data.Integration.Tests">
        <property name="AdoTemplate" ref="adoTemplate"/>
    </object>
            
    
    <!-- The object that performs multiple data access operations -->
    <object id="testObjectManager" 
            type="Spring.Data.TestObjectManager, Spring.Data.Integration.Tests">
        <property name="TestObjectDao" ref="testObjectDao"/>
    </object>

   
    <tx:attribute-driven transaction-manager="transactionManager"/>

</objects>

	Tip
	You can actually omit the 'transaction-manager' attribute in the <tx:attribute-driven/> tag if the object name of the IPlatformTransactionManager that you want to wire in has the name 'transactionManager'. If the PlatformTransactionManager object that you want to dependency inject has any other name, then you have to be explicit and use the 'transaction-manager' attribute as in the example above.

The various optional elements of the <tx:attribute-driven/> tag are summarised in the following table

Note

The "proxy-target-type" attribute on the <tx:attribute-driven/> element controls what type of transactional proxies are created for classes annotated with the Transaction attribute. If "proxy-target-type" attribute is set to "true", then inheritance-based proxies will be created. If "proxy-target-type" is "false" or if the attribute is omitted, then composition based proxies will be created. (See the section entitled Section 13.6, “Proxying mechanisms” for a detailed examination of the different proxy types.)

You can also define the transactional semantics you want to apply through the use of a <tx:advice> definition. This lets you define the transaction metadata such as propagation and isolation level as well as the methods for which that metadata applies external to the code unlike the case of using the transaction attribute. The <tx:advice> definition creates an instance of a ITransactionAttributeSource during parsing time. Switching to use <tx:advice> instead of <tx:attribute-driven/> in the example would look like the following

<tx:advice id="txAdvice" transaction-manager="transactionManager">
  <tx:attributes>
    <tx:method name="Save*"/>   
    <tx:method name="Delete*"/>  
  </tx:attributes>
</tx:advice>

This says that all methods that start with Save and Delete would have associated with them the default settings of transaction metadata. These default values are listed below..

Here is an example using other elements of the <tx:method/> definition

  <!-- the transactional advice (i.e. what 'happens'; see the <aop:advisor/> object below) -->
  <tx:advice id="txAdvice" transaction-manager="transactionManager">
    <!-- the transactional semantics... -->
    <tx:attributes>
      <!-- all methods starting with 'get' are read-only -->
      <tx:method name="Get*" read-only="true"/>
      <!-- other methods use the default transaction settings (see below) -->
      <tx:method name="*"/>
    </tx:attributes>
  </tx:advice>

The <tx:advice/> definition reads as “... all methods on starting with 'Get' are to execute in the context of a read-only transaction, and all other methods are to execute with the default transaction semantics”. The 'transaction-manager' attribute of the <tx:advice/> tag is set to the name of the PlatformTransactionManager object that is going to actually drive the transactions (in this case the 'transactionManager' object).

You can also use the AOP namespace <aop:advisor> element to tie together a pointcut and the above defined advice as shown below.

<object id="serviceOperation" type="Spring.Aop.Support.SdkRegularExpressionMethodPointcut, Spring.Aop">
    <property name="pattern" value="Spring.TxQuickStart.Services.*"/>
</object>

<aop:config>
     
    <aop:advisor pointcut-ref="serviceOperation" advice-ref="txAdvice"/>

</aop:config>

This is assuming that the service layer class, TestObjectManager, in the namespace Spring.TxQuickStart.Services. The <aop:config/> definition ensures that the transactional advice defined by the 'txAdvice' object actually executes at the appropriate points in the program. First we define a pointcut that matches any operation defined on classes in the Spring.TxQuickStart.Services (you can be more selective in your regular expression). Then we associate the pointcut with the 'txAdvice' using an advisor. In the example, the result indicates that at the execution of a 'SaveTwoTestObjects' and 'DeleteTwoTestObject', the advice defined by 'txAdvice' will be run.

The various transactional settings that can be specified using the <tx:advice/> tag. The default <tx:advice/> settings are listed below and are the same as when you use the Transaction attribute.

These default settings can be changed; the various attributes of the <tx:method/> tags that are nested within <tx:advice/> and <tx:attributes/> tags are summarized below:

The Transaction attribute is metadata that specifies that a class or method must have transactional semantics. The default Transaction attribute settings are

The default settings can, of course, be changed; the various properties of the Transaction attribute are summarised in the following table

Note that setting the TransactionPropagation to Nested will throw a NestedTransactionNotSupportedException in a case where an actual nested transaction occurs, i.e. not in the case of applying the Nested propagation but in fact no nested calls are made. This will be fixed for the Spring 1.2 release for SqlServer and Oracle which support nested transactions. Also note, that changing of isolation levels on a per-method basis is also scheduled for the Spring 1.2 release since it requires detailed command text metadata for each dbprovider. Please check the forums for news on when this feature will be introduced into the nightly builds.

If you specify an exception type for 'NoRollbackFor' the action taken is to commit the work that has been done in the database up to the point where the exception occurred. The exception is still propagated out to the calling code.

The ReadOnly boolean is a hint to the data access technology to enable read-only optimizations. This currently has no effect in Spring's ADO.NET framework. If you would like to enable read-only optimizations in ADO.NET this is generally done via the 'Mode=Read' or 'Mode=Read-Only" options in the connection string. Check your database provider for more information. In the case of NHibernate the flush mode is set to Never when a new Session is created for the transaction.

Throwing exceptions to indicate failure and assuming success is an easier and less invasive programming model than performing the same task Programatically - ContextUtil.MyTransactionVote or TransactionScope.Complete. The rollback options are a means to influence the outcome of the transaction based on the exception type which adds an extra degree of flexibility.

Having any exception trigger a rollback has similar behavior as applying the AutoComplete attribute available when using .NET Enterprise Services. The difference with AutoComplete is that using AutoComplete is also coupled to the lifetime of the ServicedComponent since it sets ContextUtil.DeactivateOnReturn to true. For a stateless DAO layer this is not an issue but it could be in other scenarios. Spring's transactional aspect does not affect the lifetime of your object.

if you choose not to use the transaction namespace for declarative transaction management then you can use 'lower level' object definitions to configure declarative transactions. The use of Spring's autoproxy functionality defines criteria to select a collection of objects to create a transactional AOP proxy. There are two AutoProxy classes that you can use, ObjectNameAutoProxyCreator and DefaultAdvisorAutoProxyCreator. If you are using the new transaction namespace support you do not need to configure these objects as a DefaultAdvisorAutoProxyCreator is created 'under the covers' while parsing the transaction namespace elements

    <object name="autoProxyCreator"
            type="Spring.Aop.Framework.AutoProxy.ObjectNameAutoProxyCreator, Spring.Aop">
            
        <property name="InterceptorNames" value="transactionInterceptor"/>
        <property name="ObjectNames">
            <list>
                <idref local="testObjectManager"/>
            </list>
        </property>
    </object>

The TransactionTemplate adopts the same approach as other Spring templates such as AdoTemplate and HibernateTemplate. It uses a callback approach, to free application code from having to do the boilerplate acquisition and release of resources, and results in code that is intention driven, in that the code that is written focuses solely on what the developer wants to do. Granted that the using construct of System.Transaction alleviates much of this. One key difference with the approach taken with the TransactionTemplate is that a commit is assumed - throwing an exception triggers a rollback instead of using the TransactionScope API to commit or rollback. This also allows for the use of rollback rules, that is a commit can still occur for exceptions of certain types.

	Note
	As you will immediately see in the examples that follow, using the TransactionTemplate absolutely couples you to Spring's transaction infrastructure and APIs. Whether or not programmatic transaction management is suitable for your development needs is a decision that you will have to make yourself.

Application code that must execute in a transaction context looks like this. You, as an application developer, will write a ITransactionCallback implementation (typically expressed as an anonymous delegate) that will contain all of the code that you need to have execute in the context of a transaction. You will then pass an instance of your custom ITransactionCallback to the Execute(..) method exposed on the TransactionTemplate. Note that the ITransactionCallback can be used to return a value:

public class SimpleService : IService
{
  private TransactionTemplate transactionTemplate;

  public SimpleService(IPlatformTransactionManager transactionManager)
  {
     AssertUtils.ArgumentNotNull(transactionManager, "transactionManager");
     transactionTemplate = new TransactionTemplate(transactionManager);
  }

  public object SomeServiceMethod()
  {
     return tt.Execute(delegate {
                             UpdateOperation(userId);
                             return ResultOfUpdateOperation2();
                       });
  }
}

This code example is specific to .NET 2.0 since it uses anonymous delegates, which provides a particularly elegant means to invoke a callback function as local variables can be referred to inside the delegate, i.e. userId. In this case the ITransactionStatus was not exposed in the delegate (delegate can infer the signature to use), but one could also obtain a reference to the ITransactionStatus instance and set the RollbackOnly property to trigger a rollback - or alternatively throw an exception. This is shown below

tt.Execute(delegate(ITransactionStatus status)
           {
             try {
               UpdateOperation1();
               UpdateOperation2();
             } catch (SomeBusinessException ex) {
               status.RollbackOnly = true;
             }           
             return null;
           });

If you are using .NET 1.1 then you should provide a normal delegate reference or an instance of a class that implements the ITransactionCallback interface. This is shown below

tt.Execute(new TransactionRollbackTxCallback(amount));


    public class TransactionRollbackTxCallback : ITransactionCallback
    {
        private decimal amount;

        public TransactionRollbackTxCallback(decimal amount)
        {
            this.amount = amount
        }

        public object DoInTransaction(ITransactionStatus status)
        {
             adoTemplate.ExecuteNonQuery(CommandType.Text, "insert into dbo.Debits (DebitAmount) VALUES (@amount)", "amount", DbType.Decimal, 0,555);
             // decide you need to rollback...
             status.RollbackOnly = true;
             return null;
        }
    }

Application classes wishing to use the TransactionTemplate must have access to a IPlatformTransactionManager (which will typically be supplied to the class via dependency injection). It is easy to unit test such classes with a mock or stub IPlatformTransactionManager.

public class SimpleService : IService
{
  private TransactionTemplate transactionTemplate;

  public SimpleService(IPlatformTransactionManager transactionManager)
  {
     AssertUtils.ArgumentNotNull(transactionManager, "transactionManager");
     transactionTemplate = new TransactionTemplate(transactionManager);

     // the transaction settings can be set here explicitly if so desired

     transactionTemplate.TransactionIsolationLevel = IsolationLevel.ReadUncommitted;
     transactionTemplate.TransactionTimeout = 30;

     // and so forth...
  }

  . . .

}

<object id="sharedTransactionTemplate"
        type="Spring.Transaction.Support.TransactionTemplate, Spring.Data">
  <property name="TransactionIsolationLevel" value="IsolationLevel.ReadUncommitted"/>
  <property name="TransactionTimeout" value="30"/>
</object>

You can also use the PlatformTransactionManager directly to manage your transaction. Simply pass the implementation of the PlatformTransactionManager you're using to your object via a object reference through standard Dependency Injection techniques. Then, using the TransactionDefinition and ITransactionStatus objects, you can initiate transactions, rollback and commit.

DefaultTransactionDefinition def = new DefaultTransactionDefinition();
def.PropagationBehavior = TransactionPropagation.Required;

ITransactionStatus status = transactionManager.GetTransaction(def);

try
{
  // execute your business logic here
} catch (Exception e)
{
  transactionManager.Rollback(status);
  throw;
}
transactionManager.Commit(status);

Note that a corresponding 'using TransactionManagerScope' class can be modeled to get similar API usage to System.Transactions TransactionScope.