Typical business applications are often cluttered with repetitive resource management code. Many projects try to invent their own solutions for this issue, sometimes sacrificing proper handling of failures for programming convenience. Spring advocates strikingly simple solutions for proper resource handling, namely IoC via templating; for example infrastructure classes with callback interfaces, or applying AOP interceptors. The infrastructure cares for proper resource handling, and for appropriate conversion of specific API exceptions to a common infrastructure exception hierarchy. Spring introduces a DAO exception hierarchy, applicable to any data access strategy. For direct ADO.NET, the AdoTemplate class mentioned in a previous section cares for connection handling, and for proper conversion of ADO.NET data access exceptions (not even singly rooted in .NET 1.1) to Spring's DataAccessException hierarchy, including translation of database-specific SQL error codes to meaningful exception classes. It supports both distributed and local transactions, via respective Spring transaction managers.

Spring also offers Hibernate support, consisting of a HibernateTemplate analogous to AdoTemplate, a HibernateInterceptor, and a Hibernate transaction manager. The major goal is to allow for clear application layering, with any data access and transaction technology, and for loose coupling of application objects. No more business service dependencies on the data access or transaction strategy, no more hard-coded resource lookups, no more hard-to-replace singletons, no more custom service registries. One simple and consistent approach to wiring up application objects, keeping them as reusable as possible. All the individual data access features are usable on their own but integrate nicely with Spring's application context concept, providing XML-based configuration and cross-referencing of plain object instances that don't need to be Spring-aware. In a typical Spring application, many important objects are plain CLR objects: data access templates, data access objects (that use the templates), transaction managers, business services (that use the data access objects and transaction managers), ASP.NET web pages (that use the business services),and so on.

While NHibernate offers an API for transaction management you will quite likely find the benefits of using Spring's generic transaction management features to be more compelling to use, typically for use of a declarative programming model for transaction demarcation and easily mixing ADO.NET and NHibernate operations within a single transaction. See the chapter on transaction management for more information on Spring's transaction management features. There are two choices for transaction management strategies, one based on the NHibernate API and the other the .NET 2.0 TransactionScope API.

The first strategy is encapsulated in the class Spring.Data.NHibernate.HibernateTransactionManager in both the Spring.Data.NHibernate namespace. This strategy is preferred when you are using a single database. ADO.NET operations can also participate in the same transaction, either by using AdoTemplate or by retrieving the ADO.NET connection/transaction object pair stored in thread local storage when the transaction begins. Refer to the documentation of Spring's ADO.NET framework for more information on retrieving and using the connection/transaction pair without using AdoTemplate. You can use the HibernateTransactionManager and associated classes such as SessionFactory, HibernateTemplate directly as you would any third party API, however they are most commonly used through Spring's XML configuration file to gain the benefits of easy configuration for a particular runtime environment and as the basis for the configuration of a data access layer also configured using XML. An XML fragment showing the declaration of HibernateTransactionManager is shown below.

  <object id="transactionManager"
        type="Spring.Data.NHibernate.HibernateTransactionManager, Spring.Data.NHibernate">

    <property name="DbProvider" ref="DbProvider"/>
    <property name="SessionFactory" ref="MySessionFactory"/>

  </object>

The important property of HibernateTransactionManager are the references to the DbProvider and the Hibernate ISessionFactory. For more information on the DbProvider, refer to the chapter DbProvider and the following section on SessionFactory set up.

The second strategy is to use the class Spring.Data.TxScopeTransactionManager that uses .NET 2.0 System.Transaction namespace and its corresponding TransactionScope API. This is preferred when you are using multiple transactional resources, such as multiple databases. Note that due to changes in the manner in which NHibernate manages its own transactions introduced in NHibernate 2.1.2 (and later), when using NHibernate 2.1.2 (and later) in the context of the .NET System.Transaction class and its TransactionScope API Spring.NET users are advised to use the Spring.Data.HibernateTxScopeTransactionManager class which is specifically designed to manage the new NHibernate transcational model when used in the context of the System.Transaction API. The API of the Spring.Data.HibernateTxScopeTransactionManager class is functionally equivalent to that of the Spring.Data.HibernateTransactionManager class but it is designed to cooperate with the .NET System.Transaction TransactionScope API for NHibernate 2.1.2 (and later).

All of these strategies associate one Hibernate Session for the scope of the transaction (scope in the general demarcation sense, not System.Transaction sense). If there is no transaction then a new Session will be opened for each operation. The exception to this rule is when using the OpenSessionInViewModule in a web application in single session mode (see Section 21.2.8, “Web Session Management”). In this case the session will be created on the start of the web request and closed on the end of the request. Note that the session's flush mode will be set to FlushMode.NEVER at the start of the request. If a non-readonly transaction is performed, then during the scope of that transaction processing the flush mode will be changed to AUTO, and then set back to NEVER at the end of the transaction scope so that any changes to objects associated with the session during rendering will not be persisted back to the database when the session is closed at the end of the web request.

To avoid tying application objects to hard-coded resource lookups, Spring allows you to define resources like a DbProvider or a Hibernate SessionFactory as objects in an application context. Application objects that need to access resources just receive references to such pre-defined instances via object references (the DAO definition in the next section illustrates this). The following excerpt from an XML application context definition shows how to set up Spring's ADO.NET DbProvider and a Hibernate SessionFactory on top of it:

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


  <!-- Property placeholder configurer for database settings -->

  <object type="Spring.Objects.Factory.Config.PropertyPlaceholderConfigurer, Spring.Core">
    <property name="ConfigSections" value="databaseSettings"/>
  </object>

  <!-- Database and NHibernate Configuration -->

  <db:provider id="DbProvider"
                   provider="SqlServer-1.1"
                   connectionString="Integrated Security=false; Data Source=(local);Integrated Security=true;Database=Northwin;User ID=springqa;Password=springqa;"/>



  <object id="MySessionFactory" type="Spring.Data.NHibernate.LocalSessionFactoryObject, Spring.Data.NHibernate">
    <property name="DbProvider" ref="DbProvider"/>
    <property name="MappingAssemblies">
      <list>
        <value>Spring.Northwind.Dao.NHibernate</value>
      </list>
    </property>
    <property name="HibernateProperties">
      <dictionary>

        <entry key="hibernate.connection.provider"
               value="NHibernate.Connection.DriverConnectionProvider"/>

        <entry key="hibernate.dialect"
               value="NHibernate.Dialect.MsSql2000Dialect"/>

        <entry key="hibernate.connection.driver_class"
               value="NHibernate.Driver.SqlClientDriver"/>

      </dictionary>
    </property>

  </object>

</objects>

Many of the properties on LocalSessionFactoryObject are those you will commonly configure, for example the property MappingAssemblies specifies a list of assemblies to seach for hibernate mapping files. The property HibernateProperies are the familiar NHibernate properties used to set typical options such as dialect and driver class. The location of NHibernate mapping information can also be specified using Spring's IResource abstraction via the property MappingResources. The IResource abstraction supports opening an input stream from assemblies, file system, and http(s) based on a Uri syntax. You can also leverage the extensibility of IResource and thereby allow NHibernate to obtain its configuration information from locations such as a database or LDAP.For other properties you can configure them as you normal using the file hibernate.cfg.xml and refer to it via the property ConfigFileNames. This property is a string array so multiple configuration files are supported.

There are other properties in LocalSessionFactoryObject that relate to the integration of Spring with NHibernate. The property ExposeTransactionAwareSessionFactory is discussed below and allows you to use Spring's declarative transaction demarcation functionality with the standard NHibernate API (as compared to using HibernateTemplate).

The property DbProvider is used to infer two NHibernate configurations options.

If you specify both the property hibernate.connection.provider and DbProvider (as shown above) the configuration of the property hibernate.connection.provider is used and a warning level message is logged. If you use Spring's DbProvider as the NHibernate connection provider then you can take advantage of IDbProvider implementations that will let you change the connection string at runtime such as UserCredentialsDbProvider and MultiDelegatingDbProvider.

Hibernate 1.2 introduced a feature called "contextual Sessions", where Hibernate itself manages one current ISession per transaction. This is roughly equivalent to Spring's synchronization of one Hibernate Session per transaction. A corresponding DAO implementation looks like as follows, based on the plain Hibernate API:

public class ProductDaoImpl implements IProductDao {

    private SessionFactory sessionFactory;

    public ISessionFactory SessionFactory
    {
        get { return sessionFactory; }
        set { sessionFactory = value; }
    }

    public IList<Product> LoadProductsByCategory(String category) {
        return SessionFactory.GetCurrentSession()
                .CreateQuery("from test.Product product where product.category=?")
                .SetParameter(0, category)
                .List<Product>();
    }
}


public class HibernateCustomerDao : ICustomerDao {

  private ISessionFactory sessionFactory;

  public ISessionFactory SessionFactory
  {
      set { sessionFactory = value; }
  }

  public Customer SaveOrUpdate(Customer customer)
  {
      sessionFactory.GetCurrentSession().SaveOrUpdate(customer);
      return customer;
  }
}

The above DAO follows the Dependency Injection pattern: it fits nicely into a Spring IoC container, just like it would if coded against Spring's HibernateTemplate. Of course, such a DAO can also be set up in plain C# (for example, in unit tests): simply instantiate it and call SessionFactory property with the desired factory reference. As a Spring object definition, it would look as follows:

<objects>

  <object id="CustomerDao" type="Spring.Northwind.Dao.NHibernate.HibernateCustomerDao, Spring.Northwind.Dao.NHibernate">
    <property name="sessionFactory" ref="MySessionFactory"/>
  </object>

</objects>

The SessionFactory configuration to support this programming model can be done two ways, both via configuration of Spring's LocalSessionFactoryObject. You can enable the use of Spring's implementation of the NHibernate extension interface, ICurrentSessionContext, by setting the property 'ExposeTransactionAwareSessionFactory' to true on LocalSessionFactoryObject. This is just a short-cut for setting the NHibernate property current_session_context_class with the name of the implementation class to use.

The first way is shown below

<object id="sessionFactory" type="Spring.Data.NHibernate.LocalSessionFactoryObject, Spring.Data.NHibernate12">

  <property name="ExposeTransactionAwareSessionFactory" value="true" />

   <!-- other configuration settings omitted -->

</object>

Which is simply a shortcut for the following configuration

<object id="sessionFactory" type="Spring.Data.NHibernate.LocalSessionFactoryObject, Spring.Data.NHibernate12">

   <!-- other configuration settings omitted -->

   <property name="HibernateProperties">
     <dictionary>

       <!-- other dictionary entries omitted -->

       <entry key="hibernate.current_session_context_class"
              value="Spring.Data.NHibernate.SpringSessionContext, Spring.Data.NHibernate12"/>

    </dictionary>
   </property>

</object>

The main advantage of this DAO style is that it depends on the Hibernate API only; no import of any Spring class is required. This is of course appealing from a non-invasiveness perspective, and will no doubt feel more natural to Hibernate developers.

Alternatively, one can use Spring's declarative transaction support, which essentially enables you to replace explicit transaction demarcation API calls in your C# code with an AOP transaction interceptor configured in a Spring container. You can either externalize the transaction semantics (like propagation behavior and isolation level ) in a configuration file or use the Transaction attribute on the service method to set the transaction semantics.

An example showing attribute driven transaction is shown below

<objects>

  <object id="TransactionManager"
        type="Spring.Data.NHibernate.HibernateTransactionManager, Spring.Data.NHibernate">

    <property name="DbProvider" ref="DbProvider"/>
    <property name="SessionFactory" ref="MySessionFactory"/>

  </object>

  <!-- DAO definition not listed, see above for an example. -->

  <object id="FulfillmentService" type="Spring.Northwind.Service.FulfillmentService, Spring.Northwind.Service">
    <property name="CustomerDao" ref="CustomerDao"/>
    <property name="OrderDao" ref="OrderDao"/>
    <property name="ShippingService" ref="ShippingService"/>
  </object>

  <!-- Import 'standard xml' configuration for attribute driven declarative tx management -->
  <import resource="DeclarativeServicesAttributeDriven.xml"/>

</objects>

Note that with the new transaction namespace, you can replace the importing of DeclarativeServicesAttributeDriven.xml with the following single line, <tx:attribute-driven/> that more clearly expresses the intent as compared to the contents of DeclarativeServicesAttributeDriven.xml.

<objects xmlns="http://www.springframework.net"
	        xmlns:tx="http://www.springframework.net/schema/tx">


  <object id="transactionManager"
        type="Spring.Data.NHibernate.HibernateTransactionManager, Spring.Data.NHibernate">

    <property name="DbProvider" ref="DbProvider"/>
    <property name="SessionFactory" ref="MySessionFactory"/>

  </object>

  <!-- DAO definition not listed, see above for an example. -->

  <object id="FulfillmentService" type="Spring.Northwind.Service.FulfillmentService, Spring.Northwind.Service">
    <property name="CustomerDao" ref="CustomerDao"/>
    <property name="OrderDao" ref="OrderDao"/>
    <property name="ShippingService" ref="ShippingService"/>
  </object>


  <tx:attribute-driven/>


</objects>

The placement of the transaction attribute in the service layer method is shown below.

public class FulfillmentService : IFulfillmentService
{
  // fields and properties for dao object omitted, see above


    [Transaction(ReadOnly=false)]
    public void ProcessCustomer(string customerId)
    {

            //Find all orders for customer
            Customer customer = CustomerDao.FindById(customerId);

            foreach (Order order in customer.Orders)
            {
                //Validate Order
                Validate(order);

                //Ship with external shipping service
                ShippingService.ShipOrder(order);

                //Update shipping date
                order.ShippedDate = DateTime.Now;

                //Update shipment date
                OrderDao.SaveOrUpdate(order);

                //Other operations...Decrease product quantity... etc
            }

    }
}

If you prefer to not use attribute to demarcate your transaction boundaries, you can import a configuration file with the following XML instead of using <tx:attribute-driven/>

  <object id="TxProxyConfigurationTemplate" abstract="true"
          type="Spring.Transaction.Interceptor.TransactionProxyFactoryObject, Spring.Data">

    <property name="PlatformTransactionManager" ref="HibernateTransactionManager"/>

    <property name="TransactionAttributes">
      <name-values>
        <!-- Add common methods across your services here -->
        <add key="Process*" value="PROPAGATION_REQUIRED"/>
      </name-values>
    </property>
  </object>

Refer to the documentation on Spring Transaction management for configuration of other features, such as rollback rules.

Transactions can be demarcated in a higher level of the application, on top of such lower-level data access services spanning any number of operations. There are no restrictions on the implementation of the surrounding business service here as well, it just needs a Spring PlatformTransactionManager. Again, the latter can come from anywhere, but preferably as an object reference via a TransactionManager property - just like the productDAO should be set via a setProductDao(..) method. The following snippets show a transaction manager and a business service definition in a Spring application context, and an example for a business method implementation.

<objects>

  <object id="TransactionManager"
        type="Spring.Data.NHibernate.HibernateTransactionManager, Spring.Data.NHibernate">

    <property name="DbProvider" ref="DbProvider"/>
    <property name="SessionFactory" ref="MySessionFactory"/>

  </object>

  <!-- DAO definition not listed, see above for an example. -->

  <object id="FulfillmentService" type="Spring.Northwind.Service.FulfillmentService, Spring.Northwind.Service">
    <property name="CustomerDao" ref="CustomerDao"/>
    <property name="OrderDao" ref="OrderDao"/>
    <property name="ShippingService" ref="ShippingService"/>
    <property name="TransactionManager" ref="TransactionManager"/>
  </object>


</objects>

public class FulfillmentService : IFulfillmentService

    private TransactionTemplate transactionTemplate;

    private IProductDao productDao;

    private ICustomerDao customerDao;

    private IOrderDao orderDao;

    private IShippingService shippingService;


    public TransactionManager TransactionManager
    {
       set { transactionTemplate = new TransactionTemplate(value);
    }
    public void ProcessCustomer(string customerId)
    {
      tt.Execute(delegate(ITransactionStatus status) 
          {
            //Find all orders for customer
            Customer customer = CustomerDao.FindById(customerId);
            foreach (Order order in customer.Orders)
            {
                //Validate Order
                Validate(order);

                //Ship with external shipping service
                ShippingService.ShipOrder(order);

                //Update shipping date
                order.ShippedDate = DateTime.Now;

                //Update shipment date
                OrderDao.SaveOrUpdate(order);

                //Other operations...Decrease product quantity... etc
            }
            return null;
          });
    }
}

Both TransactionTemplate and TransactionInterceptor (not yet seen explicitly in above configuration, TransactionProxyFactoryObject uses a TransactionInterceptor, you would have to specify it explicitly if you were using an ordinary ProxyFactoryObject.) delegate the actual transaction handling to a PlatformTransactionManager instance, which can be a HibernateTransactionManager (for a single Hibernate SessionFactory, using a ThreadLocal Session under the hood) or a TxScopeTransactionManager (delegating to MS-DTC for distributed transaction) for Hibernate applications. You could even use a custom PlatformTransactionManager implementation. So switching from native Hibernate transaction management to TxScopeTransactionManager, such as when facing distributed transaction requirements for certain deployments of your application, is just a matter of configuration. Simply replace the Hibernate transaction manager with Spring's TxScopeTransactionManager implementation. Both transaction demarcation and data access code will work without changes, as they just use the generic transaction management APIs.

For distributed transactions across multiple Hibernate session factories, simply combine TxScopeTransactionManager as a transaction strategy with multiple LocalSessionFactoryObject definitions. Each of your DAOs then gets one specific SessionFactory reference passed into it's respective object property.

TO BE DONE
     

HibernateTransactionManager can export the ADO.NET Transaction used by Hibernate to plain ADO.NET access code, for a specific DbProvider. (matching connection string). This allows for high-level transaction demarcation with mixed Hibernate/ADO.NET data access!

The open session in view pattern keeps the hibernate session open during page rendering so lazily loaded hibernate objects can be displayed. You configure its use by adding an additional custom HTTP module declaration as shown below

  <system.web>
    <httpModules>
      <add name="OpenSessionInView" type="Spring.Data.NHibernate.Support.OpenSessionInViewModule, Spring.Data.NHibernate"/>
    </httpModules>

...

  </system.web>

You can configure which SessionFactory the OpenSessionInViewModule will use by setting 'global' application key-value pairs as shown below. (this will change in future releases)

  <appSettings>
    <add key="Spring.Data.NHibernate.Support.OpenSessionInViewModule.SessionFactoryObjectName" value="SessionFactory"/>
  </appSettings>

The default behavior of the module is that a single session is currently used for the life of the request. Refer to the earlier section on Transaction Management in this chapter for more information on how sessions are managed in the OpenSessionInViewModule. You can also configure in the application setting the EntityInterceptorObjectName using the key Spring.Data.NHibernate.Support.OpenSessionInViewModule.EntityInterceptorObjectName and if SingleSession mode is used via the key Spring.Data.NHibernate.Support.OpenSessionInViewModule.SingleSession. If SingleSession is set to false, referred to as 'deferred close mode', then each transaction scope will use a new Session and kept open until the end of the web request. This has the drawback that the first level cache is not reused across transactions and that objects are required to be unique across all sessions. Problems can arise if the same object is associated with more than one hibernate session.

The class Spring.Data.NHibernate.Support.SessionScope allows for you to use a single NHibernate session across multiple transactions. The usage is shown below

using (new SessionScope())
{
    ... do multiple operations with a single session, possibly in multiple transactions.
}

Refer to the API documentation for information on overloaded constructor. At the end of the using block the session is automatically closed. All transactions within the scope use the same session, if you are using Spring's HibernateTemplate or using Spring's implementation of NHibernate 1.2's ICurrentSessionContext interface. See other sections in this chapter for further information on those usage scenarios.

When using Spring's Integration Testing support, you should make sure that the hibernate session is flushed so that the database is updated, as compared to just updating the hibernate session cache. You can implement a base class as shown below to help with the integration testing

public abstract class NHibernateIntegrationTests : AbstractTransactionalSpringContextTests
{
    private SessionFactory sessionFactory;

    public ISessionFactory SessionFactory
    {
        get { return sessionFactory; }
        set { sessionFactory = value; }
    }

    protected override void OnSetUpInTransaction()
    {
       base.OnSetUpInTransaction();
       Assert.IsNotNull(SessionFactory);
       SessionFactory.GetCurrentSession().FlushMode = FlushMode.Always;
       SessionFactory.GetCurrentSession().CacheMode = CacheMode.Ignore;
    }
}