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 an 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 and 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 .NET 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="HibernateTransactionManager"
        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 setup.

The second strategy is to use the class Sping.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.

Both 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.10, “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 flushmode 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 flushmode 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>

The location of NHibernate mapping information can also be specified using Spring's IResource abstraction via the property MappingResources. The IResource abstraction supports opening and input stream from assemblies, file system, and http(s) based on a uri syntax. You can also leverage the extensiblity of IResoure and thereby allow NHibernate to obtain its configuration information from locations such as a database or ldap.

The basic programming model for templating looks as follows, for methods that can be part of any custom data access object or business service. There are no restrictions on the implementation of the surrounding object at all, it just needs to provide a Hibernate SessionFactory. It can get the latter from anywhere, but preferably as an object reference from a Spring IoC container - via a simple SessionFactory property setter. The following snippets show a DAO definition in a Spring container, referencing the above defined SessionFactory, and an example for a DAO method implementation.

<objects>

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

</objects>

public class HibernateCustomerDao : ICustomerDao {

  private HibernateTemplate hibernateTemplate;

  public ISessionFactory SessionFactory
  {
      set { hibernateTemplate = new HibernateTemplate(value); }
  }

  public Customer SaveOrUpdate(Customer customer)
  {
      hibernateTemplate.SaveOrUpdate(customer);
      return customer;
  }
}

The HibernateTemplate class provides many methods that mirror the methods exposed on the Hibernate Session interface, in addition to a number of convenience methods such as the one shown above. If you need access to the Session to invoke methods that are not exposed on the HibernateTemplate, you can always drop down to a callback-based approach like so.

public class HibernateCustomerDao : ICustomerDao {

  private HibernateTemplate hibernateTemplate;

  public ISessionFactory SessionFactory
  {
      set { hibernateTemplate = new HibernateTemplate(value); }
  }

  public Customer SaveOrUpdate(Customer customer)
  {
      return HibernateTemplate.Execute(
                 delegate(ISession session)
                     {
                         // do whatever you want with the session....
                         session.SaveOrUpdate(customer);
                         return customer;
                     }) as Customer;
  }

}

Using the anonymous delegate is particularly convenient when you would otherwise be passing various method parameter calls to the interface based version of this callback. Furthermore, when using generics, you can avoid the typecast and write code like the following

IList<Supplier> suppliers = HibernateTemplate.ExecuteFind<Supplier>(
   delegate(ISession session)
   {
      return session.CreateQuery("from Supplier s were s.Code = ?")
                    .SetParameter(0, code)
                    .List<Supplier>();
    });

where code is a variable in the surrounding block, accessbile inside the anonymous delegate implementation.

A callback implementation effectively can be used for any Hibernate data access. HibernateTemplate will ensure that Session instances are properly opened and closed, and automatically participate in transactions. The template instances are thread-safe and reusable, they can thus be kept as instance variables of the surrounding class. For simple single step actions like a single Find, Load, SaveOrUpdate, or Delete call, HibernateTemplate offers alternative convenience methods that can replace such one line callback implementations. Furthermore, Spring provides a convenient HibernateDaoSupport base class that provides a SessionFactory property for receiving a SessionFactory and for use by subclasses. In combination, this allows for very simple DAO implementations for typical requirements:

public class HibernateCustomerDao : HibernateDaoSupport, ICustomerDao
{
    public Customer SaveOrUpdate(Customer customer)
    {
        HibernateTemplate.SaveOrUpdate(customer);
        return customer;
    }
}

As alternative to using Spring's HibernateTemplate to implement DAOs, data access code can also be written in a more traditional fashion, without wrapping the Hibernate access code in a callback, while still respecting and participating in Spring's generic DataAccessException hierarchy. The HibernateDaoSupport base class offers methods to access the current transactional Session and to convert exceptions in such a scenario; similar methods are also available as static helpers on the SessionFactoryUtils class. Note that such code will usually pass 'false' as the value of the DoGetSession(..) methods 'allowCreate' argument, to enforce running within a transaction (which avoids the need to close the returned Session, as its lifecycle is managed by the transaction). Asking for the

public class HibernateProductDao extends HibernateDaoSupport implements ProductDao {

        public Customer SaveOrUpdate(Customer customer)
        {
            ISession session = DoGetSession(false);
            session.SaveOrUpdate(customer);
            return customer;
        }
    }
}

This code will not translate the Hibernate exception to a generic DataAccessException.

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 is 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 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.

However, the DAO throws plain HibernateException which means that callers can only treat exceptions as generally fatal - unless they want to depend on Hibernate's own exception hierarchy. Catching specific causes such as an optimistic locking failure is not possible without tieing the caller to the implementation strategy. This trade off might be acceptable to applications that are strongly Hibernate-based and/or do not need any special exception treatment.

Fortunately, Spring's LocalSessionFactoryObject supports Hibernate's SessionFactory.GetCurrentSession() method for any Spring transaction strategy, returning the current Spring-managed transactional Session even with HibernateTransactionManager.

In summary: DAOs can be implemented based on the plain Hibernate 1.2 API, while still being able to participate in Spring-managed transactions. In this approach there is one session associated with the transaction.

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

TO BE DONE

</objects>

public class FulfillmentService : IFulfillmentService

    private TransactionTemplate transactionTemplate;

    private IProductDao productDao;

    private ICustomerDao customerDao;

    private IOrderDao orderDao;

    private IShippingService shippingService;

    public void ProcessCustomer(string customerId)
    {
           TO BE DONE
    }
}

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 an external 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="HibernateTransactionManager"
        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 declartive 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:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:tx="http://www.springframework.net/schema/tx"
         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">


  <object id="HibernateTransactionManager"
        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.

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.

Important

By default, OSIV applies FlushMode.NEVER on every session it creates. This is because if OSIV flushed pending changes during "EndRequest" and an error occurs, all response has already been sent to the client. There would be no way of telling the client about the error. By default this means you MUST explicitely demarcate transaction boundaries around non-readonly statements when using OSIV. For configuring transactions see Section 21.2.8, “Declarative transaction demarcation” or the Spring.Data.NHibernate.Northwind example application.

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

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

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 futher information on those usage scenarios.