Patterns

First and Second Level caching in NHibernate

NHibernate's Answers — Sun, 09 Nov 2008 17:57:58 GMT

I'll try to dive deep into the caching of NHibernate in this article. This post has been inspired by the talk given by Oren Eini (aka Ayende) at the Kaizen Conference in Austin TX.

Caching is a topic that is IMHO only superficially described so far especially regarding the second level cache. Most of the time one finds a lot of information about how to configure a specific cache provider for usage but the real usage (who and when) is not really described. I hope to be able to provide some of the missing pieces with this post.

The full source code used for this post can be found here.

First Level Cache

When using NHibernate the first level cache is automatically enabled as long as one uses the standard session object. We can avoid to use a cache at all when using the stateless session provided by NHibernate though. The stateless session is especially useful for reporting situations or for batch processing. When NHibernate is loading an entity by its unique id from the database then it is automatically put into the so called identity map. This identity map represents the first level cache.
The life-time of the first level cache is coupled to the current session. As soon as the current session is closed the content of the respective first level cache is cleared. Once an entity is in the first level cache a subsequent operation that wants to load the very same entity inside the current session retrieves this entity from the cache and no roundtrip to the database is needed.
One of the main reasons behind this entity map is to avoid the situation that two different instances in memory can represent the same database record (or entity). The NHibernate session object provides us two ways to retrieve an entity by its unique id from the database. There are subtle but important differences between them.

Let's implement an Account class for our samples

public class Account

    public virtual int Id { get; private set; }

    public virtual string Name { get; private set; }

    public virtual decimal Balance { get; private set; }

    protected Account()

    public Account(string name, decimal balance)

        Name = name;

        Balance = balance;

    public virtual void Credit(decimal amount)

        Balance += amount;

the corresponding XML mapping file is

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

<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2"

                   namespace="Caching"

                   assembly="Caching">

  <class name="Account">

    <id name="Id">

      <generator class="hilo"/>

    </id>

    <property name="Name"/>

    <property name="Balance"/>

  </class>

</hibernate-mapping>

Get an entity from database

With the session.Get(id) method we can retrieve an entity from database. If there is no record found in the database with the given id then null is returned.
On the other hand if a record with the given unique id exists in the database then NHibernate loads this record and instantiates a fully populated entity in memory and immediately puts this entity into the entity map (or first level cache)
Assuming that a specific record has already been loaded from database inside the current session then a subsequent Get(id) operation will return the cached entity to the caller. We can see this in the following output produced by the unit test. There is only ONE select statement produced by NHibernate

The above output was produced by this unit test

[Test]

public void trying_to_get_the_same_account_a_second_time_should_get_the_account_from_1st_level_cache()

    Console.WriteLine("------ now getting entity for the first time");

    var acc1 = Session.Get<Account>(account.Id);

    Console.WriteLine("------ now getting entity for the second time");

    var acc2 = Session.Get<Account>(account.Id);

    acc1.ShouldBeTheSameAs(acc2);

Load an entity from database

When using the session.Load(id) method NHibernate only instantiates a proxy for the given entity. As long as we only access the id of the entity the entity itself is not loaded from the database. Only when we try to access one of the other properties of the entity NHibernate loads the entity from the database. We can see this clearly in the following output produced by the unit test. I have added some comment to the output to make it easier to verify the result.

Here is a unit test

[Test]

public void trying_to_load_a_non_existing_entity()

    var acc1 = Session.Load<Account>(account.Id);

    acc1.ShouldNotBeNull();

    Console.WriteLine("------ now accessing the id of the entity");

    Console.WriteLine("The id is equal to {0}", acc1.Id);

    acc1.Id.ShouldEqual(account.Id);

    Console.WriteLine("------ now accessing a property (other than the ID) of the entity");

    Console.WriteLine("The name of the account is: {0}", acc1.Name);

    acc1.Name.ShouldEqual(account.Name);

and the output produced by the above code

Using Load to optimize data access

The behavior mentioned above is especially useful when creating or updating complex entities which have relations to other entities. Assume that the account entity references a customer entity and I want to create a new account for a customer from which I only know its unique id. Then my code might look as follows

var newAccount = new Account("EUR Account 1", 1250m);

newAccount.Customer = Session.Load<Customer>(customerId);

Session.Save(newAccount);

Note that I use the Load method to get the (existing) customer entity. NHibernate will not physically load the customer since in the account table on the database there is only the id of the customer needed (as a foreign key). And as I mentioned above, as long as you only use the id of an entity retrieved with the Load method the corresponding entity is not physically loaded from the database.

Second level cache

The life time of the second level cache is tied to the session factory and not to an individual session. Once an entity is loaded by its unique id and the second level cache is active the entity is available for all other sessions (of the same session factory). Thus once the entity is in the second level cache NHibernate won't load the entity from the database until it is removed from the cache.
To enable the second level cache we have to adjust our configuration file. We have to define which cache provider we want to use. There exist various implementations of a second level cache. For our sample we use a Hashtable based cache which is included in the core NHibernate assembly. Please note that you should never use this cache provider for production code but only for testing. Please refer to the chapter "Second Level Cache implementations" below to decide which implementation fits best for your needs. You won't have to change your code if you change the cache provider though.

We have to add the the following line to the configuration file

<property name="cache.provider_class">NHibernate.Cache.HashtableCacheProvider</property>

this will instruct NHibernate to use the previously mentioned Hashtable based cache provider as a provider for the second level cache.
Now let's have a look at the following unit test.

[Test]

public void trying_to_load_an_existing_item_twice_in_different_sessions_should_use_2nd_level_cache()

    using(var session = SessionFactory.OpenSession())

        var acc = session.Get<Account>(account.Id);

        acc.ShouldNotBeNull();

    using(var session = SessionFactory.OpenSession())

        var acc = session.Get<Account>(account.Id);

        acc.ShouldNotBeNull();

In the above test we open a first session and load an existing entity from the database. Then we open a second session and try to load the very same entity from the database again. Without a second level cache we would expect that NHibernate loads the entity two times from the database since we are using 2 different sessions and thus the first level cache can not be used to avoid a roundtrip to the database. So let's have a look at the result produced.

Wait a moment - we clearly see two select statements instead of only one. What did we do wrong? This is not an error, no but it's a feature. NHibernate does not enable the second level cache by default, since it would have too many undesired implications. One has to explicitly enable the second level cache. If we add the following statement to the configuration file

we activate the second level cache. But that is still not enough. We have to also enable our entity to be cached in the second level cache.
This can be done by adding the following statement to the entity's mapping file

If we now run the unit test again we obtain the expected result. The entity is loaded only once from the database. The second time it is loaded from the second level cache.
Now if we try to update an entity which is already in the second level cache then this entity should also be automatically updated in the second level cache. The following unit test should prove this behavior.

[Test]

public void when_updating_the_entity_then_2nd_level_cache_should_also_be_updated()

    using(var session = SessionFactory.OpenSession())

    using (var tx = session.BeginTransaction())

        var acc = session.Get<Account>(account.Id);

        acc.Credit(200m);

        tx.Commit();

    using(var session = SessionFactory.OpenSession())

        var acc = session.Get<Account>(account.Id);

        acc.Balance.ShouldEqual(1200m);

and indeed it does as we can see in the test output. Again the entity is loaded from the cache the second time it is requested although it was updated (no select statement after the update statement). The last line in the test code verifies that the entity was indeed updated.

Second Level Cache Providers

All second level cache providers are part of the NHibernate contribution. The following list gives as short description of each provider.

Velocity: uses Microsoft Velocity which is a highly scalable in-memory application cache for all kinds of data.
Prevalence: uses Bamboo.Prevalence as the cache provider. Bamboo.Prevalence is a .NET implementation of the object prevalence concept brought to life by Klaus Wuestefeld in Prevayler. Bamboo.Prevalence provides transparent object persistence to deterministic systems targeting the CLR. It offers persistent caching for smart client applications.
SysCache: Uses System.Web.Caching.Cache as the cache provider. This means that you can rely on ASP.NET caching feature to understand how it works.
SysCache2: Similar to NHibernate.Caches.SysCache, uses ASP.NET cache. This provider also supports SQL dependency-based expiration, meaning that it is possible to configure certain cache regions to automatically expire when the relevant data in the database changes.
MemCache: uses memcached; memcached is a high-performance, distributed memory object caching system, generic in nature, but intended for use in speeding up dynamic web applications by alleviating database load. Basically a distributed hash table.
SharedCache: high-performance, distributed and replicated memory object caching system. See here and here for more info

Saving a transient entity

Lately the following question came up in the NHibernate user list. "When I create a transient object and then save it to my session and
commit to my database, should it be added to my second level cache as well?" The answer is of course YES. Let's write a unit test

[TestFixture]

public class when_saving_a_transient_account : FixtureBase

    private Account newAccount;

    protected override void Context()

        base.Context();

        using (var session = SessionFactory.OpenSession())

        using (var tx = session.BeginTransaction())

            newAccount = new Account("CHF Account", 5500m);

            session.Save(newAccount);

            tx.Commit();

    [Test]

    public void account_should_be_in_second_level_cache()

        using (var session = SessionFactory.OpenSession())

            Console.WriteLine("--> Now loading account");

            var acc = session.Get<Account>(newAccount.Id);

            acc.ShouldNotBeNull();

            acc.Name.ShouldEqual(newAccount.Name);

In the method Context I create and save a new account entity. In the test method I open a new session and try to load the previously created entity from database. I now expect that NHibernate should take the entity out of the second level cache. And indeed it does. This is the resulting output

as we can see, no select statement is sent to the database when the entity is loaded from a new session after it has been created and saved beforehand.

Inside the second level cache

An important point is that the second-level cache does not cache instances of the object type being cached; instead it caches the individual values of the properties of that object. This provides two benefits. One, NHibernate doesn't have to worry that your client code will manipulate the objects in a way that will disrupt the cache. Two, the relationships and associations do not become stale, and are easy to keep up-to-date because they are simply identifiers. The cache is not a tree of objects but rather a map of arrays.

If you are interested in some more details about the inner workings of the second level cache then the following text (taken from Ayende and only slightly edited by me) will be of interest to you:

NHibernate is design as an enterprise OR/M product, and as such, it has very good support for running in web farms scenarios. This support include running along side with distributed caches, including immediate farm wide updates. NHibernate goes to great lengths to ensure cache consistency in these scenarios...

The way it works, NHibernate keeps three caches.

The entities cache - the entity data is disassembled and then put in the cache, ready to be assembled to entities again.

The queries cache - the identifiers of entities returned from queries, but no the data itself (since this is in the entities cache).

The update timestamp cache - the last time a table was written to.

The last cache is very important, since it ensures that the cache will not serve stale results.

Now, when we come to actually using the cache, we have the following semantics.

Each session is associated with a timestamp on creation.

Every time we put query results in the cache, the timestamp of the executing session is recorded.

The timestamp cache is updated whenever a table is written to, but in a tricky sort of way:

When we perform the actual writing, we write a value that is somewhere in the future to the cache. So all queries that hit the cache now will not find it, and then hit the DB to get the new data. Since we are in the middle of transaction, they would wait until we finish the transaction. If we are using low isolation level, and another thread / machine attempts to put the old results back in the cache, it wouldn't hold, because the update timestamp is into the future.

When we perform the commit on the transaction, we update the timestamp cache with the current value.

Now, let us think about the meaning of this, shall we?

If a session has perform an update to a table, committed the transaction and then executed a cache query, it is not valid for the cache. That is because the timestamp written to the update cache is the transaction commit timestamp, while the query timestamp is the session's timestamp, which obviously comes earlier.

The update timestamp cache is not updated until you commit the transaction! This is to ensure that you will not read "uncommitted values" from the cache.

Please note that if you open a session with your own connection, it will not be able to put anything in the cache (all its cached queries will have an invalid timestamp!)

In general, those are not things that you need to concern yourself with, but I spent some time today just trying to get tests for the second level caching working, and it took me time to realize that in the tests I didn't used transactions and I used the same session for querying as for performing the updates.

Collections and the second level cache

Let's assume the following scenario: we have a blog which can have many posts. See the diagram below.

The corresponding code to define the entities is as follows

public class Blog

    public virtual int Id { get; set; }

    public virtual string Author { get; set; }

    public virtual string Name { get; set; }

    public virtual IList<Post> Posts { get; set; }

    public Blog()

        Posts = new List<Post>();

public class Post

    public virtual int Id { get; private set; }

    public virtual string Title { get; set; }

    public virtual string Body { get; set; }

and we can define the mapping of the blog and the post entity like this

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

<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2"

                   namespace="Caching"

                   assembly="Caching">

  <class name="Blog">

    <cache usage="read-write"/>

    <id name="Id">

      <generator class="hilo"/>

    </id>

    <property name="Author"/>

    <property name="Name"/>

    <bag name="Posts" cascade="all" lazy="true">

      <cache usage="read-write"/>

      <key column="BlogId"/>

      <one-to-many class="Post"/>

    </bag>

  </class>

  <class name="Post">

    <cache usage="read-write"/>

    <id name="Id">

      <generator class="hilo"/>

    </id>

    <property name="Title"/>

    <property name="Body"/>

  </class>

</hibernate-mapping>

Note that I have added a <cache> element to the mapping for the Blog entity. This is enough to cache all simple Blog property values (e.g. Id, Name and Author) but not the state of associated entities or collections. Collections require their own <cache> element. In our case I added a <cache> element to the Posts collection (which is mapped as a bag). This cache will be used when enumeration the collection blog.Posts, for example. Please be aware that a collection cache only holds the identifiers of the associated post instances. That is, if we have a blog with three posts having id's 1,2 and 3 respectively then the second level cache will contain the values of simple properties of the blog and in addition an array with the ids {1,2,3}. If we require the post instances themselves to be cached, then we must enable caching of the Post class by adding a <cache> element to it's mapping.

Let me resume: by adding a <cache> element to the Blog, the Posts collection and the Post itself I have declared that I want NHibernate to cache not only my blog entities but also the associated Post collection in full detail.

Attention: dragons ahead

A common error (It happened to me as well!) is to forget to commit or omit a transaction when adding or changing an entity/aggregate to the database. If we now access the entity/aggregate from another session then the 2nd level cache will not be prepared to provide us the cached instances and NHibernate makes an (unexpected round trip to the database). The reason why this is the case is described in the chapter "Inside the second level cache" above.

What does this mean? Let's have a look at the code I use to setup the context for our unit tests regarding the Blog-->Posts problem.

blog = new Blog{ Author = "Gabriel", Name = "Keep on running"};

blog.Posts.Add(new Post{Title = "First post", Body = "Some text"});

blog.Posts.Add(new Post { Title = "Second post", Body = "Some other text" });

blog.Posts.Add(new Post { Title = "Third post", Body = "Third post text" });

using (var session = SessionFactory.OpenSession())

using(var tx = session.BeginTransaction())

    session.Save(blog);

    tx.Commit();        // important otherwise caching does NOT work!

In the above code I create a new blog having three assigned posts. The blog instance is then saved to the database inside a transaction. If I would omit the transaction or if I would forget to commit the transaction then the above samples would not work as expected and the 2nd level cache would not be used as desired.

Caching queries in the second level cache

We cannot only cache entities loaded by their respective unique id but also any query. For this we have to define the query as cacheable and set the desired cache mode. Let's have a look at a typical sample

[Test]

public void trying_to_cache_a_query()

    using (var session = SessionFactory.OpenSession())

        Console.WriteLine("---> using query first time");

        var query = session

            .CreateQuery("from Blog b where b.Author = :author")

            .SetString("author", "Gabriel")

            .SetCacheable(true);

        var list = query.List<Blog>();

    using (var session = SessionFactory.OpenSession())

        Console.WriteLine("---> using query second time");

        var query2 = session

            .CreateQuery("from Blog b where b.Author = :author")

            .SetString("author", "Gabriel")

            .SetCacheable(true);

        var list2 = query2.List<Blog>();

In the above sample I use the same query from different sessions. Please not that I have set cacheable to true for the query. In this case the query will be cached in the second level cache the first time it is executed. Any subsequent calls using the very same query will not hit the database. It is important to note however that if I change the value of the parameter(s) in the query then the query is reloaded again from the database. So it is the query and the set of parameter values that define the key under which the query is stored in the 2nd level cache.

The result of the above test looks as follows

Of course I can also use named queries and cache them. A named query is defined inside a mapping file, e.g.

<query cacheable="true" cache-mode="normal" name="query1">

  <![CDATA[from Blog b where b.Name like :name]]>

  <query-param name="name" type="String"/>

</query>

The above query is called "query1" and has a single parameter called "name". The cache mode for this query is set to "normal". I can use such a query as follows

[Test]

public void trying_named_query()

    using (var session = SessionFactory.OpenSession())

        Console.WriteLine("---> using named query first time");

        var list = session.GetNamedQuery("query1")

            .SetString("name", "Keep%")

            .List<Blog>();

    using (var session = SessionFactory.OpenSession())

        Console.WriteLine("---> using named query second time");

        var list2 = session.GetNamedQuery("query1")

            .SetString("name", "Keep%")

            .List<Blog>();

The session object has a method GetNamedQuery to retrieve the query. The output produced by the above test is then

If the content of the table on which the cached query is based is changed then the query is evicted from the second level cache and the next time the query is executed the query must be reloaded.

Cache Regions

If we don't use cache regions the second level cache can only be cleared as a whole. If you need to clear only part of the second level cache then use regions. Regions are distinguished by their name. One can put any number of different queries into a named cache region. The command to clear a cache region is as follows
SessionFactory.EvictQueries("My Region");
where SessionFactory is the session factory instance currently used and "My Region" is the name of the cache region.

Source Code

The full source code used for this post can be found here.

Summary

NHibernate provides two types of caches. The first level cache and the second level cache. The first level cache is also called the identity map and is used not only to reduce the number of round trips to the database to improve the speed of an application but also to guarantee that there do not exist two distinct instances of an object having the very same id. NHibernate provides us two methods to load an entity by its unique id from the database. The Get method returns null if an entity with the given id does not exist or returns the fully loaded entity to the caller. The Load method on the other hand returns a proxy to the caller and only loads the entity from the database if another property than the identity is accessed. One can also call this a deferred load.

The second level cache is not used by default and should be used with caution. It can provide a huge scalability gain if used wisely but also reduce the performance of the overall system and introduce unnecessary complexity if used wrong.

The second level cache is related to the session factory, that is all session instances of a given session factory use the same 2nd level cache. That's differs from the behavior of the 1st level cache which is related to an individual session instance. One can cache individual entities or whole aggregates in the 2nd level cache. But one can also cache (complex and/or time consuming) queries in the 2nd level cache. The 2nd level cache can be fragmented into regions for a more fine grained control.

Enjoy.

The Repository Pattern

NHibernate's Answers — Wed, 08 Oct 2008 13:42:03 GMT

Introduction

When accessing data from a data source we have several well documented possibilities. Martin Fowler e.g. describes several of them in his PoEAA book.

Table data gateway
Row data gateway
Active record
Data mapper

When applying DDD (domain driven design) we often use the so called Repository Pattern to access the data needed by the domain model.

What is a Repository

Martin Fowler writes:

"A Repository mediates between the domain and data mapping layers, acting like an in-memory domain object collection. Client objects construct query specifications declaratively and submit them to Repository for satisfaction. Objects can be added to and removed from the Repository, as they can from a simple collection of objects, and the mapping code encapsulated by the Repository will carry out the appropriate operations behind the scenes. Conceptually, a Repository encapsulates the set of objects persisted in a data store and the operations performed over them, providing a more object-oriented view of the persistence layer. Repository also supports the objective of achieving a clean separation and one-way dependency between the domain and data mapping layers."

Implementation

In DDD we have the notion of aggregates. An aggregate is "A cluster of associated objects that are treated as a unit for the purpose of data changes. External references are restricted to one member of the Aggregate, designated as the root. A set of consistency rules applies within the Aggregate's boundaries.".

Usually one defines a repository per aggregate in the domain. That is: we don't have a repository per entity! If we have a look at a simple order entry system the entity Order might be the root of a Order aggregate. Thus we will have an Order Repository.

The interface (or contract) of the repository is considered as a part of the domain model where as the implementation of the repository is infrastructure specific and thus does NOT belong to the domain model.

When dealing with aggregates most of the time we need exactly 3 persistence related operations

get an aggregate by it's id (primary key)
add a new aggregate to the repository
remove an aggregate from the repository

Depending on the context there might be other persistence related operations that are needed but the most common and often used ones are the three mentioned above. This leads us to the following minimal contract (interface) with the repository

public interface IOrderRepository

    Order GetById(int id);

    void Add(Order order);

    void Remove(Order order);

In the above sample we assume that the primary key of the Order is a surrogate key and is of type int.

Now let's assume that we have identified a second aggregate in our domain model, the Product aggregate. Then we can immediately deduce the appropriate repository interface from the interface to the order repository. We have

public interface IProductRepository

    Product GetById(int id);

    void Add(Product product);

    void Remove(Product product);

Now this looks very similar to the first interface and we can generalize the interface by using a generic parameter. We then have

public interface IRepository<T>

    T GetById(int id);

    void Add(T entity);

    void Remove(T entity);

Now the interfaces to the product and the order repository will just be

public interface IOrderRepository : IRepository<Order> { }

public interface IProductRepository : IRepository<Product> { }

A fake repository

For testing purposes we can implement a fake repository for the product aggregate. In this case it will be a dictionary with some predefined products. The key to each product will be its primary key. In our simple sample the Product aggregate consists only of the Product entity

public class Product

    public virtual int Id { get; set; }

    public virtual string Name { get; set; }

    public virtual int ReorderLevel { get; set; }

    public virtual bool Discontinued { get; set; }

This is a very simple entity but it is sufficient for our purposes. Now let's have a look at the implementation of the faked repository

public class ProductRepositoryFake : IProductRepository

    private readonly Dictionary<int, Product> dictionary;

    public ProductRepositoryFake()

        dictionary = new Dictionary<int, Product>();

        dictionary.Add(1, new Product {Id = 1, Name = "Product 1", ReorderLevel = 10, Discontinued = false});

        dictionary.Add(2, new Product {Id = 2, Name = "Product 2", ReorderLevel = 15, Discontinued = false});

        dictionary.Add(3, new Product {Id = 3, Name = "Product 3", ReorderLevel = 10, Discontinued = false});

        dictionary.Add(4, new Product {Id = 4, Name = "Product 4", ReorderLevel = 12, Discontinued = false});

        dictionary.Add(5, new Product {Id = 5, Name = "Product 5", ReorderLevel = 20, Discontinued = true});

    public Product GetById(int id)

        return dictionary[id];

    public void Add(Product product)

        dictionary.Add(product.Id, product);

    public void Remove(Product product)

        dictionary.Remove(product.Id);

In the constructor I instantiate a dictionary which takes as key an int (the type of the primary key in our case) and as value a Product instance. Then I define several sample Product instances which I fill into the dictionary. The implementation of the three methods GetById, Add and Remove is straight forward and needs no further explanation.

Now let's write some unit tests where we use this implementation of the repository. Note that the special methods (e.g. ShouldEqual, ShouldNotBeNull, ShouldBeThrownBy, etc.) found in the code below are extension methods and can be found in the code accompanying this post. They aid to make the test code more readable than when using the Assert.Equals(...), etc. syntax.

[TestFixture]

public class FakeRepositoryTester

    private IProductRepository repository;

    [SetUp]

    public void SetupContext()

        repository = new ProductRepositoryFake();

    [Test]

    public void can_load_a_product_by_its_id_from_the_repository()

        var product = repository.GetById(2);

        product.ShouldNotBeNull();

        product.Id.ShouldEqual(2);

    [Test]

    public void can_add_a_new_product_to_the_repository()

        repository.Add(new Product {Id = 99, Name = "Product 99", ReorderLevel = 13, Discontinued = false});

        // let's try to load this new product

        var product = repository.GetById(99);

        product.Id.ShouldEqual(99);

        product.Name.ShouldEqual("Product 99");

    [Test]

    public void can_remove_an_existing_product_from_the_repository()

        var product = repository.GetById(1);

        repository.Remove(product);

        typeof (KeyNotFoundException).ShouldBeThrownBy(() => repository.GetById(1));

In the SetupContext method (which will be executed before each test) I define the repository to be an instance of type ProductRepositoryFake. Note that the repository field is declared as type of IProductRepository!

The first test method verifies that the GetById method works as expected. Which indeed it does since when running the test it is green. The second test verifies that the Add method works. First I add a new (non existing) product instance. Then I immediately try to reload this new instance by its id. Then the reloaded instance is tested whether it is the one expected (by comparing some of its properties).

Last but not least the third method tests the Remove method. In the first line I load a product instance from the repository which I know exists. This instance is then removed from the repository. In the third line I test whether the product was really removed from the repository by expecting an exception when trying to get the (previously removed) product from the repository again.

Please note that in the above test code there is only one place where the specific implementation of the repository is of interest. It's the line in the SetupContext method where the repository instance is created. The rest of the code is fully agnostic regarding the specific implementation of the repository. That's an important fact to remember. That means that I can exchange the implementation used in the above code by only changing a single line of code!

An implementation for NHibernate

Now let's try a first implementation for the repository that uses NHibernate. First I need a session provider. I use the following implementation

public class SessionProvider

    private static Configuration configuration;

    private static ISessionFactory sessionFactory;

    public static Configuration Configuration

get

            if(configuration == null)

                configuration = new Configuration();

                configuration.Configure();                              // A

                configuration.AddAssembly(typeof (Product).Assembly);   // B

            return configuration;

    public static ISessionFactory SessionFactory

get

            if (sessionFactory == null)

                sessionFactory = Configuration.BuildSessionFactory();

            return sessionFactory;

    private SessionProvider()

{ }

    public static ISession GetSession()

        return SessionFactory.OpenSession();

In the above sample code the session factory is only built on demand and only once during the life-time of the application (the construction of the session factory is an expensive operation, on the other hand the session factory is thread safe). I make the following assumptions

the existence of a hibernate.cfg.xml for configuration of the connection properties (A)
all mapping files for the domain entities can be found in the assembly where the Product entity is defined (B)

With the aid of this SessionProvider class the implementation of the repository for e.g. the Product entity is really trivial

public class ProductRepositoryNH : IProductRepository

    private static ISession GetSession() { return SessionProvider.GetSession(); }

    public Product GetById(int id)

        using (var session = GetSession())

            return session.Get<Product>(id);

    public void Add(Product product)

        using (var session = GetSession())

            session.Save(product);

    public void Remove(Product product)

        using (var session = GetSession())

            session.Delete(product);

We have a private helper function GetSession which just returns a new session object whenever accessed. The other methods use this helper property for their operations. Note the usage of the using statement to guarantee that the session object is released whenever the database operation is finished.

But the above implementation (although working) has an important flaw and thus can hardly be used in a real application! It's the fact that the repository uses a different session instance for each operation. In a real application often several operations have to be executed inside a single transaction and thus inside a single session (the reason is that a transaction cannot span multiple sessions - at least when not using distributed transactions).

The Unit of Work to the rescue

We can resolve the above dilemma by applying the Unit of Work (UoW) pattern (for a profound discussion of this patterns please refer to this article)! The UoW manages a session for us. I can then refactor my implementation of the product repository as follows

public class ProductRepository : IProductRepository

    private ISession Session { get { return UnitOfWork.CurrentSession; } }

    public Product GetById(int id)

        return Session.Get<Product>(id);

    public void Add(Product product)

        Session.Save(product);

    public void Remove(Product product)

        Session.Delete(product);

Unit Tests

First I implement a base class for unit testing repositories. This base class configures my unit of work and re-creates the schema for each test (I'm using SqLite in in-memory mode as my database)

public class RepositoryFixtureBase<T>

    [TestFixtureSetUp]

    public void TestFixtureSetup()

        UnitOfWork.Configuration.AddAssembly(typeof(T).Assembly);

    [SetUp]

    public void SetupContext()

        UnitOfWork.Start();

        new SchemaExport(UnitOfWork.Configuration)

            .Execute(false, true, false, false, UnitOfWork.CurrentSession.Connection, null);

        Context();

    [TearDown]

    public void TearDownContext()

        UnitOfWork.Current.TransactionalFlush();

        UnitOfWork.Current.Dispose();

    protected virtual void Context() { }

with the aid of the above base class the unit tests for my product repository look like this

[TestFixture]

public class ProductRepository_Tester : RepositoryFixtureBase<Product>

    private IProductRepository repository;

    private Product[] products;

    protected override void Context()

        products = new[]

                           new Product {Id = 1, Name = "Product 1", ReorderLevel = 10, Discontinued = false},

                           new Product {Id = 2, Name = "Product 2", ReorderLevel = 15, Discontinued = false},

                           new Product {Id = 3, Name = "Product 3", ReorderLevel = 10, Discontinued = false},

                           new Product {Id = 4, Name = "Product 4", ReorderLevel = 12, Discontinued = false},

                           new Product {Id = 5, Name = "Product 5", ReorderLevel = 20, Discontinued = true},

};

        foreach (var product in products)

            UnitOfWork.CurrentSession.Save(product);

        UnitOfWork.CurrentSession.Flush();

        UnitOfWork.CurrentSession.Clear();

        repository = new ProductRepository();

    [Test]

    public void can_load_product()

        var p = repository.GetById(2);

        p.ShouldNotBeNull();

        p.Id.ShouldEqual(products[1].Id);

    [Test]

    public void can_add_a_product_to_the_repository()

        repository.Add(new Product { Id = 6, Name = "Product 6", ReorderLevel = 6, Discontinued = false });

        UnitOfWork.CurrentSession.Flush();

        UnitOfWork.CurrentSession.Clear();

        var prod = UnitOfWork.CurrentSession.Get<Product>(6);

        prod.ShouldNotBeNull();

    [Test]

    public void can_remove_product_from_repository()

        repository.Remove(products[2]);

        UnitOfWork.CurrentSession.Flush();

        UnitOfWork.CurrentSession.Clear();

        var prod = UnitOfWork.CurrentSession.Get<Product>(products[2].Id);

        prod.ShouldBeNull();

In the Context method (which is executed before each test) I set up my boundary conditions (=the context). I define an array of products which are then inserted into the database. After inserting these products the current session is flushed and then cleared.

In the first test method can_load_product I try to load a product with the id equal to 2. This product exists in the database since I have applied the boundary conditions. After loading the product I check whether it has really been loaded (ShouldNotBeNull) and that I indeed received the product with the requested id.

In the second test method can_add_a_product_to_the_repository I first try to add a new product instance to the repository. I then flush the current session and clear it. Then I try to re-load the new product from the repository and verify that it is not null. Note that if I wouldn't clear the session after inserting the product, the product would still be in the first level cache and NHibernate would not query the database when I execute the ...Get<Product>(id) method but rather return the object in the cache.

In the third and last test method can_remove_product_from_repository test I try to remove an existing product from the repository. Now when trying to reload the deleted product I should get null.

A generic base repository

When having a look again at our product repository (and possibly at the order repository whose implementation I leave as an exercise for you) we can see some room left for improvement. What if I implement a base repository which in a generic way implements all the common functionality. This leads to the following implementation

public class Repository<T> : IRepository<T>

    public ISession Session { get { return UnitOfWork.CurrentSession; } }

    public T GetById(int id)

        return Session.Get<T>(id);

    public ICollection<T> FindAll()

        return Session.CreateCriteria(typeof(T)).List<T>();

    public void Add(T product)

        Session.Save(product);

    public void Remove(T product)

        Session.Delete(product);

I have taken the code from the ProductRepository class and just replaced any occurrence of Product with the generic parameter T.

Note that this base class can now easily be extended to contain more functionality which is used across repositories for different entities. As an example I have added a FindAll method in the above implementation which just returns a list of all items of the specific type.

Do we still need the ProductRepository and/or OrderRepository classes? Well, it depends. If our application has no other needs regarding the product and order repository then no, we can just use the generic base repository. On the other hand if we want to provide a specific query for the product aggregate (which in turn makes no sense for the order aggregate) we explicitly define a product repository which is a child of the generic base repository.

Let's take this as an example

public interface IProductRepository : IRepository<Product>

    ICollection<Product> FindAllDiscontinuedProducts();

Here I have declared the need for a query that returns the list of discontinued products (note that there is no notion of discontinued orders...). The implementation is straight forward

public class ProductRepository : Repository<Product>, IProductRepository

    public ICollection<Product> FindAllDiscontinuedProducts()

        return Session.CreateCriteria(typeof (Product))

            .Add(Restrictions.Eq("Discontinued", true))

            .List<Product>();

The above method hides the infrastructure related details from my domain and/or application and provides a business friendly interface

Let's have a look how I can test the above method

public void can_load_all_discontinued_products()

    var discontinuedProducts = repository.FindAllDiscontinuedProducts();

    discontinuedProducts.Count.ShouldBeGreaterThan(0);

    discontinuedProducts.ToList().ForEach(p=>p.Discontinued.ShouldBeTrue());

I expect the method to return at least 1 product and each returned product should have its property Discontinued set to true.

Code

The code to this post can be found here.

Summary

I have discussed the repository pattern which is used to retrieve data from external data sources (e.g. databases) in an easy and consistent way. Its main benefit is a clean separation of the domain and the data mapping layer. I have presented an implementation of the pattern for NHibernate. This implementation makes use of the Unit of Work which is another well known pattern which I have introduced in a previous post.

Enjoy

NHibernate and the Unit of Work pattern (Part 3)

NHibernate's Answers — Sat, 26 Apr 2008 19:04:36 GMT

Introduction

In the previous two posts which you can find here and here I introduced the Unit of Work pattern and developed a working version based on NHibernate. One weak point of the shown implementation is that it is strictly non thread safe. In NHibernate the session object takes the role of the Unit of Work container. The session object is not thread safe! That is a session instance may not be accessed from different threads. If your application is running on multiple threads (typically an application running on the server) then you have to open a new session instance for each running thread.

In this post I want to improve the implementation of the Unit of Work pattern such as that it is thread safe. The class which starts a new unit of work is a static class. All static members of this class are accessible from each thread of the application domain in which your application is running. Now fortunately .NET provides us a mean to define pseudo static fields in a type which are local to a single thread. That is this state is not shared between different threads. Each thread has its own thread static state. To make a field thread static one has to decorate it with the [ThreadStatic] attribute.

The easiest and most pragmatic approach would now be to just decorate our _innerUnitOfWork field of the UnitOfWork class with the [ThreadStatic] attribute. But eventually we want to keep additional state in our Unit of Work. Thus we implement a special Data class which is a kind of a wrapper around a Hashtable.

Container for Thread Static State

There are 2 possible scenarios I want to discuss. You either develop an application with a web client or an application with a windows client (e.g. WinForms).

In a web application one has the so called Http context for each request. Multiple requests from different clients can run at the same but each of them runs on a different thread and has it's own context. In this situation we store the data relevant to the unit of work in the context of the request.

In a windows client application (i.e. Smart Client Application) on the other hand we have a single client that might run on different threads at the same time. In this situation we "attach" the data relevant to the unit of work in so called thread-static fields. A thread-static field is not shared between different threads in the same application. To make a (static) field thread-static we have to just decorate it with a [ThreadStatic] attribute.

In our Unit of Work implementation we have the static UnitOfWork class which contains a static field _innerUnitOfWork of type IUnitOfWork. We now need to change this since this kind of implementation is not thread safe. Since we might want to save other data in a thread safe way as well (not just the current instance of the unit of work) we choose a slightly more sophisticated solution.

Let's define a static class Local which encapsulates the details whether we run a web- or a win-application. This class has just one (static) read-only property Data of type ILocalData.

using System;

using System.Collections;

namespace NHibernateUnitOfWork

    public static class Local

        static readonly ILocalData _data = new LocalData();

        public static ILocalData Data

            get { return _data; }

        private class LocalData : ILocalData

            // implementation details to de defined

All details of our implementation are now "hidden" in the class LocalData which we choose to be a private child class of the Local class. We now want to be able to save into and read data from this local container via a key, e.g.

Local.Data["some key"] = someValue;

// or

otherValue = Local.Data["other key"];

This should be in a thread safe way. Obviously the above sample client code implies that we use some kind of dictionary to internally store our data.

As usual we formulate our intention in a unit test which might look like this

using System;

using NUnit.Framework;

namespace NHibernateUnitOfWork.Tests

    [TestFixture]

    public class LocalData_Fixture

        [Test]

        public void Can_store_values_in_local_data()

            Local.Data["one"] = "This is a string";

            Local.Data["two"] = 99.9m;

            var person = new Person {Name = "John Doe", Birthdate = new DateTime(1991, 1, 15)};

            Local.Data[1] = person;

            Assert.AreEqual(3, Local.Data.Count);

            Assert.AreEqual("This is a string", Local.Data["one"]);

            Assert.AreEqual(99.9m, Local.Data["two"]);

            Assert.AreSame(person, Local.Data[1]);

The test shows that I want to be able to not only store basic types but any complex type in my local data container. In this case a string, an integer and an instance of a Person class. The Person class is very basic at looks like follows

public class Person

    public virtual Guid Id { get; set; }

    public virtual string Name { get; set; }

    public virtual DateTime Birthdate { get; set; }

Please also note that I use keys of different type (string and int).

Implementation for Smart Client Applications

Let's first assume that we want to provide a thread safe unit of work implementation for the smart client application. Then the most basic implementation to fulfill this test is

private class LocalData : ILocalData

    private static Hashtable _localData = new Hashtable();

    public object this[object key]

        get { return _localData[key]; }

        set { _localData[key] = value; }

    public int Count

        get { return _localData.Count; }

I just take a hash table as local storage and define an indexer property and a Count property (Note: a HashTable is an often used implementation of a Dictionary).

We want to also be able to clear the content of the local store and thus we define the following test

[Test]

public void Can_clear_local_data()

    Local.Data["one"] = "This is a string";

    Local.Data["two"] = 99.9m;

    Assert.AreEqual(2, Local.Data.Count);

    Local.Data.Clear();

    Assert.AreEqual(0, Local.Data.Count);

The code to fulfill this test is trivial, just add the code snippet below to the LocalData class

public void Clear()

    _localData.Clear();

Unfortunately the test still faults when run! This is because the local data storage is static and all test methods access the same container we have a "side effect" which we must now compensate. We can do it by just clearing the local data container before each test. Add this code to the test fixture class to compensate the side effect

[SetUp]

public void SetupContext()

    Local.Data.Clear();     // start side-effect free!

Re-run all tests. They should now all pass...

And now comes the "tricky" part of the implementation where we want to guarantee that our local data store is indeed thread safe. Let's first define a test for this scenario

private ManualResetEvent _event;

[Test]

public void Local_data_is_thread_local()

    Console.WriteLine("Starting in main thread {0}", Thread.CurrentThread.ManagedThreadId);

    Local.Data["one"] = "This is a string";

    Assert.AreEqual(1, Local.Data.Count);

    _event = new ManualResetEvent(false);

    var backgroundThread = new Thread(RunInOtherThread);

    backgroundThread.Start();

    // give the background thread some time to do its job

    Thread.Sleep(100);

    // we still have only one entry (in this thread)

    Assert.AreEqual(1, Local.Data.Count);

    Console.WriteLine("Signaling background thread from main thread {0}", Thread.CurrentThread.ManagedThreadId);

    _event.Set();

    backgroundThread.Join();

private void RunInOtherThread()

    Console.WriteLine("Starting (background-) thread {0}", Thread.CurrentThread.ManagedThreadId);

    // initially the local data must be empty for this NEW thread!

    Assert.AreEqual(0, Local.Data.Count);

    Local.Data["one"] = "This is another string";

    Assert.AreEqual(1, Local.Data.Count);

    Console.WriteLine("Waiting on (background-) thread {0}", Thread.CurrentThread.ManagedThreadId);

    _event.WaitOne();

    Console.WriteLine("Ending (background-) thread {0}", Thread.CurrentThread.ManagedThreadId);

In the above code I run two threads in parallel, the thread on which the test is running (let's call it the main thread) and an additional background thread. The code which is executed in the background thread is implemented in the helper method RunInOtherThread. To be able to synchronize the two threads I use an Event, in this case a ManualResetEvent. I have put some Console.WriteLine statements in the code for debugging purposes.

In the main thread I add some data to the local data store. Then I spin up the background thread. In the background thread I first test that my (thread-) local data store is empty and then also fill in some data. With the Assert statements I test that we really have a thread safe behavior.

The only change needed to make my implementation thread safe is to decorate the static field _localData with the [ThreadStatic] attribute.

[ThreadStatic]

private static Hashtable _localData = new Hashtable();

When the test is run it should pass and produce an output similar to this

Implementation for Web

As mentioned above in this scenario we want to store our local data in the context of the current HTTP request.

First I want to provide an indicator whether I am running in web and thus I add the following to the code snippet to the LocalData class

public static bool RunningInWeb

    get { return HttpContext.Current != null; }

Here I use the HttpContext class of the .NET framework (namespace System.Web). It's static property Current is equal to null if we do not run in the context of a web application.

To abstract the details of the context (web- or smart client application) I define a private read-only property LocalHashtable as below

private static readonly object LocalDataHashtableKey = new object();

private static Hashtable LocalHashtable

get

        if (!RunningInWeb)

            if (_localData == null)

                _localData = new Hashtable();

            return _localData;

        else

            var web_hashtable = HttpContext.Current.Items[LocalDataHashtableKey] as Hashtable;

            if (web_hashtable == null)

                web_hashtable = new Hashtable();

                HttpContext.Current.Items[LocalDataHashtableKey] = web_hashtable;

            return web_hashtable;

In this code I use the RunningInWeb helper method to distinguish the two cases. In the case of NOT running in web context I test whether my thread static _localData field is equal to null, and If so I initialize it with a new instance of type Hashtable. I then return this instance. On the other hand, when running in web context I try to access a hash table instance in the Items collection of the current Http context. If I do not find such an instance then I create a new one and put it into the items collection of the current context. I then return the instance.

Now I have to locate every place in the LocalData class where I access the _localData field directly and replace it with a reference to the LocalHashtable property. E.g. the indexer will have to be changed as follows

public object this[object key]

    get { return LocalHashtable[key]; }

    set { LocalHashtable[key] = value; }

Our thread- and/or Http context local data store is now complete and we can use it in our UnitOfWork class.

Make Unit Of Work implementation thread safe

To make our unit of work implementation thread safe we change the implementation of our static UnitOfWork class as shown below

public static class UnitOfWork

    private static readonly IUnitOfWorkFactory _unitOfWorkFactory = new UnitOfWorkFactory();

    public static Configuration Configuration

        get { return _unitOfWorkFactory.Configuration; }

    public const string CurrentUnitOfWorkKey = "CurrentUnitOfWork.Key";

    private static IUnitOfWork CurrentUnitOfWork

        get { return Local.Data[CurrentUnitOfWorkKey] as IUnitOfWork; }

        set { Local.Data[CurrentUnitOfWorkKey] = value; }

    public static IUnitOfWork Current

get

            var unitOfWork = CurrentUnitOfWork;

            if (unitOfWork == null)

                throw new InvalidOperationException("You are not in a unit of work");

            return unitOfWork;

    public static bool IsStarted

        get { return CurrentUnitOfWork != null; }

    public static ISession CurrentSession

        get { return _unitOfWorkFactory.CurrentSession; }

        internal set { _unitOfWorkFactory.CurrentSession = value; }

    public static IUnitOfWork Start()

        if (CurrentUnitOfWork != null)

            throw new InvalidOperationException("You cannot start more than one unit of work at the same time.");

        var unitOfWork = _unitOfWorkFactory.Create();

        CurrentUnitOfWork = unitOfWork;

        return unitOfWork;

    public static void DisposeUnitOfWork(IUnitOfWorkImplementor unitOfWork)

        CurrentUnitOfWork = null;

As you can see the field _innerUnitOfWork has gone and is replaced by a private property CurrentUnitOfWork. This property in turn uses the previously defined Local class to store the current unit of work item.

Note that there is one place in our unit tests that makes a reference to the field _innerUnitOfWork and must thus be changed. It's the method ResetUnitOfWork in the class UnitOfWork_With_Factory_Fixture. The new implementation is

private void ResetUnitOfWork()

    // assert that the UnitOfWork is reset

    var propertyInfo = typeof(UnitOfWork).GetProperty("CurrentUnitOfWork",

                        BindingFlags.Static | BindingFlags.SetProperty | BindingFlags.NonPublic);

    propertyInfo.SetValue(null, null, null);

When run, all tests should again pass. So now our implementation of the unit of work is thread safe.

You can find the full code here.

Enjoy

NHibernate and the Unit of Work Pattern (Part 2)

NHibernate's Answers — Mon, 14 Apr 2008 10:16:47 GMT

In the first part of this series I have started to implement the Unit of Work pattern.

In this post I'll finish this implementation (for non-thread safe version) and in a third post I'll discuss how to make this implementation thread safe.

Design and Implementation

The Unit Of Work Factory

The creation of a unit of work instance is a complex process and as such is a good candidate for a factory.

Since a UoW (Unit of Work) is basically a wrapper around a NHibernate session object I'll need to open such a session whenever I start a new UoW. But to be able to get such a session NHibernate has to be configured and a NHibernate Session Factory has to be available. The interface of my UoW factory is defined as follows

I basically have two public methods on my factory. One for the creation of the UoW and the second for the disposal of a specific UoW instance. The disposal involves also some work and thus justifies the existence of this second factory method. The 3 properties Configuration, SessionFactory and CurrentSession are there mostly for advanced scenarios (and as such could theoretically be omitted in a first simple implementation).

Let's now write the test for the Create method of the UoW factory implementation. At first I prepare a new test fixture class

using System;

using NHibernate;

using NUnit.Framework;

namespace NHibernateUnitOfWork.Tests

    [TestFixture]

    public class UnitOfWorkFactory_Fixture

        private IUnitOfWorkFactory _factory;

        [SetUp]

        public void SetupContext()

            _factory = (IUnitOfWorkFactory) Activator.CreateInstance(typeof (UnitOfWorkFactory), true);

Why the heck do I need the Activator.CreateInstance to get an instance of the factory? Well I decided that the construction of a new factory instance should be internal to the assembly implementing the Unit of Work pattern. Thus the (default) constructor of the UnitOfWorkFactory class has a modifier internal and as a consequence cannot be used from code outside the assembly in which the factory is implemented. But I need an instance when testing and thus have to resort to the technique used above.

Now the question is: "what confirms me that the method Create of the factory works as expected?". I have chosen the following: I expect

the method returning a non null instance of type IUnitOfWork
the returned instance having a non null (NHibernate) session
the (NHibernate) session having the Flush Mode set to commit (that is: the session is never flushed except when I explicitly commit a transaction - see the NHibernate documentation for any details about the Flush Mode)

Now the code

[Test]

public void Can_create_unit_of_work()

    IUnitOfWork implementor = _factory.Create();

    Assert.IsNotNull(implementor);

    Assert.IsNotNull(_factory.CurrentSession);

    Assert.AreEqual(FlushMode.Commit, _factory.CurrentSession.FlushMode);

and the implementation

public class UnitOfWorkFactory : IUnitOfWorkFactory

    private static ISession _currentSession;

    private ISessionFactory _sessionFactory;

    internal UnitOfWorkFactory()

{ }

    public IUnitOfWork Create()

        ISession session = CreateSession();

        session.FlushMode = FlushMode.Commit;

        _currentSession = session;

        return new UnitOfWorkImplementor(this, session);

As you can see I first need a new session instance. I then set the flush mode to commit and assign the session to an instance variable for further use. Finally I return a new instance of the UnitOfWorkImplementor (which implements the interface IUnitOfWork). The constructor of the UnitOfWorkImplementor class requires two parameters, the session and a reference to this factory.

To be able to compile I also have to define the UnitOfWorkImplementor class. Of this class I just implement the minimum needed so far

public class UnitOfWorkImplementor : IUnitOfWork

    private readonly IUnitOfWorkFactory _factory;

    private readonly ISession _session;

    public UnitOfWorkImplementor(IUnitOfWorkFactory factory, ISession session)

        _factory = factory;

        _session = session;

Now back to the implementation of the CreateSession method. To be able to create (and open) a session NHibernate must have been configured previously. So I solve this problem first.

First we add a file hibernate.cfg.xml to our test project and put the following content into it (don't forget to set the property 'Copy to Output Directory' of this file to 'Copy always').

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

<hibernate-configuration xmlns="urn:nhibernate-configuration-2.2">

  <session-factory>

    <property name="connection.provider">NHibernate.Connection.DriverConnectionProvider</property>

    <property name="dialect">NHibernate.Dialect.MsSql2005Dialect</property>

    <property name="connection.driver_class">NHibernate.Driver.SqlClientDriver</property>

    <property name="connection.connection_string">Server=(local);Database=Test;Integrated Security=SSPI;</property>

    <property name="show_sql">true</property>

  </session-factory>

</hibernate-configuration>

The above configuration file assumes that you have an SQL Server 2005 installed on your local machine and that you are using integrated security to authenticate and authorize the access to the database. It further assumes that there exists a database called 'Test' on this server. To configure NHibernate for other types of databases please consult the online documentation here.

Now we define this test method

[Test]

public void Can_configure_NHibernate()

    var configuration = _factory.Configuration;

    Assert.IsNotNull(configuration);

    Assert.AreEqual("NHibernate.Connection.DriverConnectionProvider",

                    configuration.Properties["connection.provider"]);

    Assert.AreEqual("NHibernate.Dialect.MsSql2005Dialect",

                    configuration.Properties["dialect"]);

    Assert.AreEqual("NHibernate.Driver.SqlClientDriver",

                    configuration.Properties["connection.driver_class"]);

    Assert.AreEqual("Server=(local);Database=Test;Integrated Security=SSPI;",

                    configuration.Properties["connection.connection_string"]);

Here we test whether we can successfully create a configuration and whether this configuration contains the attributes we have defined via the NHibernate configuration file.

To fulfill this test we can e.g. implement the following code

public Configuration Configuration

get

        if (_configuration == null)

            _configuration = new Configuration();

            string hibernateConfig = Default_HibernateConfig;

            //if not rooted, assume path from base directory

            if (Path.IsPathRooted(hibernateConfig) == false)

                hibernateConfig = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, hibernateConfig);

            if (File.Exists(hibernateConfig))

                _configuration.Configure(new XmlTextReader(hibernateConfig));

        return _configuration;

Note that I have defined a class variable _configuration such as that I only execute the configuration logic once during the life time of the application. Note further that in this implementation I assume that the configuration of NHibernate is defined via the hibernate.cfg.xml file which must be in the same directory as the test assembly.

As soon as I have a valid configuration I can create a NHibernate session factory. Note that this is a rather expensive operation (takes some time depending on the number of entities you are mapping) and thus should only be executed once during the life time of the application. The access to the NHibernate SessionFactory is thread safe!

Let's write a test for the creation of the SessionFactory.

[Test]

public void Can_create_and_access_session_factory()

    var sessionFactory = _factory.SessionFactory;

    Assert.IsNotNull(sessionFactory);

    Assert.AreEqual("NHibernate.Dialect.MsSql2005Dialect", sessionFactory.Dialect.ToString());

This is a rather basic test and only checks whether I can successfully create a session factory and whether at least one of its properties is configured as I expect it, namely the dialect used.

The implementation to fulfill the test is rather simple

public ISessionFactory SessionFactory

get

        if (_sessionFactory == null)

            _sessionFactory = Configuration.BuildSessionFactory();

        return _sessionFactory;

I have defined a class variable _sessionFactory such that I only execute the BuildSessionFactory method once during the life time of the application. The session factory is created on demand, that is when first needed. At the same time this property getter method accesses the previously defined Configuration property which in turn triggers the configuration of NHibernate (if not already done).

The last missing piece is the implementation of the CreateSession method which now is trivial

private ISession CreateSession()

    return SessionFactory.OpenSession();

I want to be able to access the current (open) session via my factory. If there is no such session open at the moment a meaningful exception should be raised. To test this write

[Test]

public void Accessing_CurrentSession_when_no_session_open_throws()

try

        var session = _factory.CurrentSession;

    catch (InvalidOperationException)

{ }

and the implementation is easy

public ISession CurrentSession

get

        if (_currentSession == null)

            throw new InvalidOperationException("You are not in a unit of work.");

        return _currentSession;

    set { _currentSession = value; }

The last method to implement is the UoW disposal method. In this method I want to reset the CurrentSession to null and then forward the call to our static UnitOfWork class (defined in the first part of this post series) such as that this class can also make an internal clean-up. The implementation might look as follows

public void DisposeUnitOfWork(UnitOfWorkImplementor adapter)

    CurrentSession = null;

    UnitOfWork.DisposeUnitOfWork(adapter);

That's all we have to do for now regarding the UoW factory. Again we have implemented it in a TDD way. When we later re-factor our implementation to make it thread-safe this TDD approach will be a huge benefit since we have a complete test coverage of out code.

The Unit of Work Implementor

This class defines an actual Unit of Work instance. It implements the already mentioned (and defined) interface IUnitOfWork which in turn inherits from IDisposal. This allows us to work with a UoW using the following syntax

using(UnitOfWork.Start())

    // use Unit of Work

at the end of the block the Dispose method of the UoW will be called. So let's first think of a test for the implementation of this method. Here we have to use mocking to be able to test our SUT (system under test) in isolation. So let me setup a test fixture first.

[TestFixture]

public class UnitOfWorkImplementor_Fixture

    private readonly MockRepository _mocks = new MockRepository();

    private IUnitOfWorkFactory _factory;

    private ISession _session;

    private IUnitOfWorkImplementor _uow;

    [SetUp]

    public void SetupContext()

        _factory = _mocks.DynamicMock<IUnitOfWorkFactory>();

        _session = _mocks.DynamicMock<ISession>();

Again I use Rhino.Mocks as my mocking framework. My UoW instance has two external dependencies namely the UnitOfWork factory and the NHibernate session. In the SetupContext I generate a dynamic mock for each of them.

Now I can write my test method

[Test]

public void Can_Dispose_UnitOfWorkImplementor()

    using(_mocks.Record())

        Expect.Call(() => _factory.DisposeUnitOfWork(null)).IgnoreArguments();

        Expect.Call(_session.Dispose);

    using (_mocks.Playback())

        _uow = new UnitOfWorkImplementor(_factory, _session);

        _uow.Dispose();

During the recording phase I define my expectations (of what should happen when calling the Dispose method of the UoW). First the DisposeUnitOfWork method of the factory and second the Dispose method of the session object should be called.

Here is the code which fulfills this test

public void Dispose()

    _factory.DisposeUnitOfWork(this);

    _session.Dispose();

As you can see I just forward the call to the Unit of Work factory and dispose my internal (NHibernate) session instance as formulated in the expectations of the test.

When working with a UoW I also have to be able to use transactions. Thus I need a way to "play" with transactions. Let's call the corresponding methods BeginTransaction and TransactionalFlush.

Generic Transaction

To shield the client code from all NHibernate specifics and to provide a simple(r) interface I define a GenericTransaction class (which implements the interface IGenericTransaction) which is just a wrapper around the NHibernate transaction.

I think that the implementation is trivial and doesn't need any further explanation

public interface IGenericTransaction : IDisposable

    void Commit();

    void Rollback();

public class GenericTransaction : IGenericTransaction

    private readonly ITransaction _transaction;

    public GenericTransaction(ITransaction transaction)

        _transaction = transaction;

    public void Commit()

        _transaction.Commit();

    public void Rollback()

        _transaction.Rollback();

    public void Dispose()

        _transaction.Dispose();

just note that the IGenericTransaction inherits form IDisposable.

With this definition of a generic transaction we can proceed to the implementation of the BeginTransaction and TransactionalFlush methods.

First I'll implement the BeginTransaction method. As usual I define the test first

[Test]

public void Can_BeginTransaction()

    using(_mocks.Record())

        Expect.Call(_session.BeginTransaction()).Return(null);

    using (_mocks.Playback())

        _uow = new UnitOfWorkImplementor(_factory, _session);

        var transaction = _uow.BeginTransaction();

        Assert.IsNotNull(transaction);

I expect that during execution of the method under test the BeginTransaction method of the NHibernate session is called. After calling BeginTransaction on the UoW (in the Playback phase) I additionally test whether I get a not-null transaction.

I also want to be able to start a transaction and define an isolation level for the transaction. The corresponding test might look like

[Test]

public void Can_BeginTransaction_specifying_isolation_level()

    var isolationLevel = IsolationLevel.Serializable;

    using(_mocks.Record())

        Expect.Call(_session.BeginTransaction(isolationLevel)).Return(null);

    using (_mocks.Playback())

        _uow = new UnitOfWorkImplementor(_factory, _session);

        var transaction = _uow.BeginTransaction(isolationLevel);

        Assert.IsNotNull(transaction);

To fulfill the test(s) I just have to create a new instance of a generic transaction and pass the result of the _session.BeginTransaction call to the constructor (that is: a NHibernate ITransaction object)

public IGenericTransaction BeginTransaction()

    return new GenericTransaction(_session.BeginTransaction());

public IGenericTransaction BeginTransaction(IsolationLevel isolationLevel)

    return new GenericTransaction(_session.BeginTransaction(isolationLevel));

The methods each return me an instance of type GenericTransaction which I can use in my code and call their respective commit or rollback methods if appropriate.

The TransactionalFlush method should flush the content of the NHibernate session to the database wrapped inside a transaction. Let's define the test(s) for it

[Test]

public void Can_execute_TransactionalFlush()

    var tx = _mocks.CreateMock<ITransaction>();

    var session = _mocks.DynamicMock<ISession>();

    SetupResult.For(session.BeginTransaction(IsolationLevel.ReadCommitted)).Return(tx);

    _uow = _mocks.PartialMock<UnitOfWorkImplementor>(_factory, _session);

    using (_mocks.Record())

        Expect.Call(tx.Commit);

        Expect.Call(tx.Dispose);

    using (_mocks.Playback())

        _uow = new UnitOfWorkImplementor(_factory, session);

        _uow.TransactionalFlush();

[Test]

public void Can_execute_TransactionalFlush_specifying_isolation_level()

    var tx = _mocks.CreateMock<ITransaction>();

    var session = _mocks.DynamicMock<ISession>();

    SetupResult.For(session.BeginTransaction(IsolationLevel.Serializable)).Return(tx);

    _uow = _mocks.PartialMock<UnitOfWorkImplementor>(_factory, session);

    using (_mocks.Record())

        Expect.Call(tx.Commit);

        Expect.Call(tx.Dispose);

    using (_mocks.Playback())

        _uow.TransactionalFlush(IsolationLevel.Serializable);

and the implementation is straight forward

public void TransactionalFlush()

    TransactionalFlush(IsolationLevel.ReadCommitted);

public void TransactionalFlush(IsolationLevel isolationLevel)

    IGenericTransaction tx = BeginTransaction(isolationLevel);

try

        //forces a flush of the current unit of work

        tx.Commit();

    catch

        tx.Rollback();

        throw;

    finally

        tx.Dispose();

Note that when you don't provide an explicit transaction isolation level our implementation automatically assumes an isolation level equal to "read commited". Note also that if the Commit of the transaction fails the transaction is rolled back.

Important: In the case of an exception during TransactionalFlush do not try to reuse the current unit of work since the session is in an inconsistent state and must be closed. Thus abandon this UoW and start a new one.

To increase the usability of the UoW instance a little bit I add the following members (which need no further explanation)

public bool IsInActiveTransaction

get

        return _session.Transaction.IsActive;

public IUnitOfWorkFactory Factory

    get { return _factory; }

public ISession Session

    get { return _session; }

public void Flush()

    _session.Flush();

That's it! We have now a simple implementation of the Unit of Work pattern for NHibernate. Let me provide an overall picture of our implementation

Please remember: In this current version the UoW is strictly NOT thread-safe! But I'll show you how to make it thread-safe in the next post.

Using the Unit of Work

In the following section I'll quickly show the typical usage of the UoW. As usual I do this via TDD. I want to demonstrate how one can define a new instance of an entity and add it to the database. In this case the entity is a simple Person type object.

Let us first set up a test fixture as follows

using System;

using System.Reflection;

using NHibernate.Tool.hbm2ddl;

using NUnit.Framework;

namespace NHibernateUnitOfWork.Tests

    [TestFixture]

    public class Test_usage_of_UnitOfWork

        [SetUp]

        public void SetupContext()

            UnitOfWork.Configuration.AddAssembly(Assembly.GetExecutingAssembly());

            new SchemaExport(UnitOfWork.Configuration).Execute(false, true, false, false);

In the SetupContext method I first add the current assembly (the one in which this test is running) as a source of the schema mapping information to the configuration of NHibernate (which I can access via our UnitOfWork class). It is important that this call is done prior to the creation of the SessionFactory (that is prior to using a session).

After extending the configuration I use the SchemaExport class of NHibernate to automatically generate the database schema for me.

But wait: up to now I have not defined any schema at all! So let's do it now. Let's define a simple Person entity. Add a new file Person.cs to the test project and add the following code

public class Person

    public virtual Guid Id { get; set; }

    public virtual string Name { get; set; }

    public virtual DateTime Birthdate { get; set; }

add an XML mapping document called Person.hbm.xml to the test project and define the following content

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

<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2"

                   assembly="NHibernateUnitOfWork.Tests"

                   namespace="NHibernateUnitOfWork.Tests">

  <class name="Person">

    <id name="Id">

      <generator class="guid"/>

    </id>

    <property name="Name" not-null="true" length="50"/>

    <property name="Birthdate" not-null="true"/>

  </class>

</hibernate-mapping>

Don't forget to set the 'Build Action' property of this item to 'Embedded Resource'!

Now we can write a test to insert a new person instance into the database.

[Test]

public void Can_add_a_new_instance_of_an_entity_to_the_database()

    using(UnitOfWork.Start())

        var person = new Person {Name = "John Doe", Birthdate = new DateTime(1915, 12, 15)};

        UnitOfWork.CurrentSession.Save(person);

        UnitOfWork.Current.TransactionalFlush();

When running this test the output generated by NHibernate looks similar to this

NHibernate: INSERT INTO Person (Name, Birthdate, Id) VALUES (@p0, @p1, @p2);

@p0 = 'John Doe', @p1 = '15.12.1915 00:00:00',

@p2 = 'bb72ae4c-7d64-4c16-84dc-c0ba2c7d306b'

Summary

I have shown you a possible implementation of the Unit of Work pattern for NHibernate. The implementation has been developed by using TDD. The usage of a Unit of Work pattern simplifies the data manipulation tasks and hides the infrastructure details from the consumer of the UoW. NHibernate offers it's own implementation of the UoW in the form of the Session object. But NHibernate is just one of several possible ORM tools. With this implementation of the UoW pattern we have hidden most of the specifics of NHibernate an provide a generic interface to the consumer of the UoW.

There are just two open points

our implementation in not thread safe
we still need to access the session object (through UnitOfWork.CurrentSession) to read or modify our entites

The former I'll cover in my next post and the latter problem can be solved by introducing a (generic) repository which I'll also discuss in one of the next posts.

Any feedback and suggestions for improvement is welcome.

Enjoy