TDD

Linq to NHibernate

NHibernate's Answers — Wed, 26 Nov 2008 17:13:20 GMT

The popularity of NHibernate is steadily increasing. At the same time people get used to LINQ. Now there exists a LINQ to NHibernate provider since quite some time. It's not a complete implementation of a LINQ provider but it is still quite useful. Most of the day to day problems we face when developing typical business application can be solved by using this provider. And if there is a query that cannot be executed against the provider we still have the option to falling back to the hibernate query language (HQL).

In this post I'll give you an introduction on how you can use NHibernate in conjunction with LINQ. Let's start with the definition of a domain model we are going to use when querying the database by using LINQ expressions or LINQ query operators.

The domain model

I have the following simple domain model. A person can have a set of assigned tasks.

The entities

I want to keep the entities as simple as possible for this example. So their implementation is as follows

public class Person

    public Person()

        Tasks = new List<Task>();

    public virtual long Id { get; set; }

    public virtual string Lastname { get; set; }

    public virtual string Firstname { get; set; }

    public virtual IList<Task> Tasks { get; set; }

public class Task

    public virtual long Id { get; set; }

    public virtual string TaskName { get; set; }

    public virtual DateTime DueDate { get; set; }

one thing worth noting is the fact that I instantiate a new empty Tasks collection in the constructor of the Person class.

The mapping

For the mapping of my domain model I am going to use the Fluent NHibernate framework (please refer to my previous posts for a detailed introduction to this framework: part 1, part 2, part 3, part 4) .

The Task is very easy to map

public class TaskMap : ClassMap<Task>

    public TaskMap()

        Id(x => x.Id);

        Map(x => x.TaskName);

        Map(x => x.DueDate);

And the person is nothing more complicated

public class PersonMap : ClassMap<Person>

    public PersonMap()

        Id(x => x.Id);

        Map(x => x.Firstname);

        Map(x => x.Lastname);

        HasMany<Task>(x => x.Tasks)

            .LazyLoad()

            .Cascade.All();

Just let's have a look at the mapping of the Tasks collection. I want the tasks to only be lazy loaded when loading a person entity (LazyLoad). And I want NHibernate to automatically save or update any tasks associated with a given person if ever the person is updated (Cascade.All).

Test the mapping

One quick test I want to always do is to check whether my mappings work as expected. Since I use Fluent NHibernate this is very easy and straight forward. A lot of infrastructure code is available to me to leverage and thus simplify my unit test regarding mapping of the domain entities.

The base test fixture

First I want to present my base class I use for all of my tests. Every test fixture used in this post will inherit from this base class.

public class FixtureBase<TModel> where TModel : PersistenceModel, new()

    protected SessionSource SessionSource { get; set; }

    protected ISession Session { get; private set; }

    [SetUp]

    public void SetupContext()

        var cfg = new SQLiteConfiguration()

                        .InMemory()

                        .ShowSql();

        SessionSource = new SessionSource(cfg.ToProperties(), new TModel());

        Session = SessionSource.CreateSession();

        SessionSource.BuildSchema(Session);

        Context();

        Because();

        Session.Flush();

        Session.Clear();

    [TearDown]

    public void TearDown()

        TearDownContext();

        Session.Close();

        Session.Dispose();

    protected virtual void Context()

    protected virtual void Because()

    protected virtual void TearDownContext()

First of all my base fixture has a generic parameter TModel. TModel represents the persistence model used during the tests. The persistence model must inherit from the PersistenceModel (provided by Fluent NHibernate) and it must have a default constructor.

In the SetupContext method (which is executed before each test)

I define my configuration I want to use. Most of the time I use the SQLite database in in-memory mode for my database related tests. Fluent NHibernate provides me such a configuration object. For debugging purposes I declare that I want to see the SQL statements generated by NHibernate (ShowSql).
Second I create a session source and pass the above configuration as well as an instance of the model used to the constructor of the session source.
Then I create a new session object. Note that since I am using SQLite in in-memory mode I have to use the same session object during the whole test (including setup and tear down) since the database schema (and the data) is destroyed when the session is closed.
I now use the Session object created above to generate the database schema. The schema is generated from the information provided by the model (which consists of all mappings)
Now I call the virtual Context and Because methods. The reason is that I want my unit test to be more BDD like
Finally I flush all pending operations from the session to the database and then clear the session.

The persistence model

The persistence model I am using is very straight forward. I just include all class mappings that are in the same assembly as the PersonMap.

public class TestModel : PersistenceModel

    public TestModel()

        addMappingsFromAssembly(typeof(PersonMap).Assembly);

I could also explicitly add mappings if I want so

public class TestModel : PersistenceModel

    public TestModel()

        addMapping(new PersonMap());

        addMapping(new TaskMap());

The test

Writing a test for the mapping is really straight forward with the aid of the PersistenceSpecification class provided by Fluent NH.

[Test]

public void can_add_person_without_tasks()

    new PersistenceSpecification<Person>(Session)

        .CheckProperty(x => x.Firstname, "Gabriel")

        .CheckProperty(x => x.Lastname, "Schenker")

        .VerifyTheMappings();

or a test which also tries to add tasks

[Test]

public void can_add_person_with_tasks()

    var tasks = new[]

                        new Task {TaskName = "Task 1", DueDate = DateTime.Today.AddDays(5)},

                        new Task {TaskName = "Task 2", DueDate = DateTime.Today.AddDays(6)},

                        new Task {TaskName = "Task 3", DueDate = DateTime.Today.AddDays(3)},

};

    new PersistenceSpecification<Person>(Session)

        .CheckProperty(x => x.Firstname, "Gabriel")

        .CheckProperty(x => x.Lastname, "Schenker")

        .CheckList(x=>x.Tasks, tasks)

        .VerifyTheMappings();

Do I need to tell that the tests pass successfully? It's really that easy... I have not needed a single line of XML so far. And no "magic strings" are involved. For me it's really a joy to work like this.

And now finally we get LINQ into the play

The context

In LINQ the notion of a context is very important. It represent kind of a facade to the database. LINQ to NHibernate provides us a base class from which we can derive when we define our own context. In our simplified model we have only 2 entities and thus our context needs just two members to have access via LINQ to either the persons or tasks.

public class SampleContext : NHibernateContext

    public SampleContext(ISession session)

        : base(session)

{ }

    public IOrderedQueryable<Person> Persons

        get { return Session.Linq<Person>(); }

    public IOrderedQueryable<Task> Tasks

        get { return Session.Linq<Task>(); }

Testing

Now I want to implement a first test to check whether LINQ to NHibernate does indeed work as expected. First I have to setup a context where I have some person object with tasks in the database

public class a_repository_with_persons_having_tasks : Person_Fixture

    protected Person[] persons;

    private IList<Task> tasks1, tasks2, tasks3;

    protected override void Context()

        base.Context();

        tasks1 = new[]

                         new Task {TaskName = "Task 1.1", DueDate = DateTime.Today.AddDays(5)},

                         new Task {TaskName = "Task 1.2", DueDate = DateTime.Today.AddDays(6)},

                         new Task {TaskName = "Task 1.3", DueDate = DateTime.Today.AddDays(3)},

};

        tasks2 = new[]

                         new Task {TaskName = "Task 2.1", DueDate = DateTime.Today.AddDays(5)},

                         new Task {TaskName = "Task 2.2", DueDate = DateTime.Today.AddDays(6)},

                         new Task {TaskName = "Task 2.3", DueDate = DateTime.Today.AddDays(3)},

};

        tasks3 = new[]

                         new Task {TaskName = "Task 3.1", DueDate = DateTime.Today.AddDays(5)},

                         new Task {TaskName = "Task 3.2", DueDate = DateTime.Today.AddDays(6)},

                         new Task {TaskName = "Task 3.3", DueDate = DateTime.Today.AddDays(2)},

};

        persons = new[]

                          new Person {Firstname = "Gabriel", Lastname = "Schenker", Tasks = tasks1},

                          new Person {Firstname = "John", Lastname = "Doe", Tasks = tasks2},

                          new Person {Firstname = "Ann", Lastname = "Moe", Tasks = tasks3},

};

        foreach (var person in persons)

            Session.Save(person);

Now I can write a test for the case where I want to retrieve all persons from the database

[TestFixture]

public class when_querying_all_persons : a_repository_with_persons_having_tasks

    private IEnumerable<Person> list;

    protected override void Because()

        list = from p in db.Persons

               select p;

    [Test]

    public void should_return_all_persons()

        list.Count().ShouldEqual(persons.Length);

The query generated by the above test is

SELECT  this_.Id as Id0_0_,

        this_.Lastname as Lastname0_0_,

        this_.Firstname as Firstname0_0_

FROM [Person] this_

That's exactly what we were expecting!

Using Where to get a filtered list

Now let's do some more interesting stuff. I want to have a filtered list of persons

[TestFixture]

public class when_retrieving_filtered_list_of_persons : a_repository_with_persons_having_tasks

    [Test]

    public void can_filter_by_LastName()

        var list = db.Persons.Where(x=>x.Lastname=="Doe");

        list.Count().ShouldEqual(1);

    [Test]

    public void can_filter_by_task()

        var list = from p in db.Persons

                   from t in p.Tasks

                   where t.DueDate == DateTime.Today.AddDays(3)

                   select p;

        list.Count().ShouldEqual(2);

In the first test I use the Where extension method defined by LINQ to filter my collection of persons. The extension methods defined by LINQ are also called query operators. The select statement generated by Linq2NH is

SELECT count(*) as y0_

FROM [Person] this_

WHERE this_.Lastname = @p0;

@p0 = 'Doe'

In the second test I use the new language extension introduced for C# (also called a query expression) to get a filtered set of persons. This time we get the following select statement sent to the database

SELECT          count(*) as y0_

FROM            [Person] this_

left outer join [Task] t1_ on this_.Id=t1_.Person_id

WHERE t1_.DueDate = @p0;

@p0 = '29.11.2008 00:00:00'

Obviously also joins between tables work as expected.

Getting ordered lists

Often we need an ordered list of items, in this case persons ordered by their last name.

[Test]

public void can_order_by_LastName()

    var list = db.Persons.OrderBy(x => x.Lastname);

    list.First().Lastname.ShouldEqual("Doe");

The query generated is

SELECT  this_.Id as Id0_0_,

        this_.Lastname as Lastname0_0_,

        this_.Firstname as Firstname0_0_

FROM [Person] this_

ORDER BY this_.Lastname asc

Code

The code accompanying this post can be found here.

Summary

It is straight forward to use LINQ to NHibernate. Although the Linq2NH provider is not fully implemented it is more than sufficient for most scenarios we encounter in typical projects. And if ever we encounter a query that cannot be executed through the Linq2NH provider we can still implement the query by using HQL instead.

Enjoy

Lazy loading BLOBS and the like in NHibernate

NHibernate's Answers — Mon, 17 Nov 2008 12:23:16 GMT

[Updated, 2008-11-20 --> see end of post]

One of the questions that is asked again and again in the NHibernate user mailing list is the question about whether NHibernate supports lazy-loading of properties. The answer is NO - at least for the time being. Why is this question reasonable? Well, often we have entities in our domain that contain fields with large amount of data. Some samples are

a large binary object (BLOB, e.g. an image, a Word document, a PDF, etc.),
a large text object (CLOB, or nvarchar(max) )
a cluster of rarely used extra fields

The problem is that we do not always need all this information when loading an entity. Thus we can massively improve the performance of our queries if those fields would only be loaded on demand.

The Model

Let's have a look at the following simplified domain model.

Here the person entity has an associated photo. The photo has been extracted from the person entity since NHibernate does not support lazy load of specific properties of an entity (as mentioned above) and thus each time we load a person entity we would also load its photo which might be huge (e.g. several MB).

The code for the person entity is simple

public class Person

    public virtual Guid Id { get; private set; }

    public virtual string LastName { get; private set; }

    public virtual string FirstName { get; private set; }

    public virtual PersonPhoto Photo { get; private set; }

    // to satisfy NHibernate only!

    protected Person() { }

    public Person(string lastName, string firstName, PersonPhoto personPhoto)

        LastName = lastName;

        FirstName = firstName;

        AssignPhoto(personPhoto);

    public virtual void AssignPhoto(PersonPhoto photo)

        Photo = photo;

        photo.Owner = this;

please note that I have defined a method to assign a photo to the person. This method takes care of the fact that the relation between the person and the photo entity is bi-directional (via the assignment photo.Owner = this). I have omitted any validation code for brevity.

Let's also have a look at the implementation of the PersonPhoto class which I kept even simpler

public class PersonPhoto

    public virtual Guid Id { get; set; }

    public virtual Person Owner { get; set; }

    public virtual byte[] Image { get; set; }

Let's now define the mapping for my simple model.

Mapping with XML

The question is now: how can I map this model to achieve the desired result that is

whenever I load a person its photo is not automatically loaded but only on request (lazy load)
treating the person photo like an associated entity of the person entity, that is the photo is created, updated and deleted together with its parent - the person.

It is not possible in NHibernate to define a (bi-directional) one-to-one relation between Person and PersonPhoto and requesting at the same time that the PersonPhoto is lazy loaded.

But a possible solution to declare the relation between Person and PersonPhoto as many-to-one and between PersonPhoto and Photo as one-to-one.

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

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

                   assembly="Blobs"

                   namespace="Blobs">

  <class name="Person">

    <id name="Id">

      <generator class="guid"/>

    </id>

    <property name="LastName"/>

    <property name="FirstName"/>

    <many-to-one name="Photo" class="PersonPhoto" unique="true"

                 column="PersonPhotoId" cascade="all-delete-orphan"/>

  </class>

  <class name="PersonPhoto">

    <id name="Id">

      <generator class="guid"/>

    </id>

    <property name="Image" type="BinaryBlob"/>

    <one-to-one name="Owner" property-ref="Photo" constrained="true"/>

  </class>

</hibernate-mapping>

It is important to note that the many-to-one relation defined in the Person mapping is declared as unique to avoid that a single photo is assigned to more than one person. Also I define that each insert, update and delete action applied to a person entity should be cascaded to the associated PersonPhoto entity.

Unit testing the XML mapping

Let's now write some unit tests that verify that my requirements are indeed satisfied.

[Updated]

First I want to analyze what database schema is created. Remember: whenever I have the possibility to start a so called green field project I always start by defining the domain and then let the database auto-generated from the domain (that is: the database is only an implementation detail). Things might be different if you have to use a pre-existing database though...

So my unit test to verify that the schema can indeed be created is

[TestFixture]

public class when_creating_the_schema : Person_Fixture

    protected override void Context()

        base.Context();

        new SchemaExport(Configuration).Execute(true, false, false, false, Session.Connection, null);

    [Test]

    public void smoke_test()

        true.ShouldBeTrue();

In the last line of the Context method I use the SchemaExport class of NHibernate to generate the database schema from the model and the mapping information. The first (and only) test I write is a so called smoke test, that is it's a dummy test which should run just to test that setting up the context doesn't throw an exception. And indeed the test succeeds and the following output is produced

The script is generated for the SQLite database I use. For a different type of database server the script would look slightly different. The two tables created are

create table Person (

  Id UNIQUEIDENTIFIER not null,

  LastName TEXT,

  FirstName TEXT,

  PersonPhotoId UNIQUEIDENTIFIER unique,

  primary key (Id)

create table PersonPhoto (

  Id UNIQUEIDENTIFIER not null,

  Image BLOB,

  primary key (Id)

Second I want to test whether I can create a new person object having a photo and save this aggregate to the database.

[TestFixture]

public class when_adding_a_new_person_with_a_photo : Person_Fixture

    private PersonPhoto photo;

    private Person person;

    protected override void Context()

        base.Context();

        photo = new PersonPhoto {Image = Encoding.Default.GetBytes("This is a placeholder for a photo...")};

        person = new Person("Schenker", "Gabriel", photo);

        Session.Save(person);

        // clean up

        Session.Flush();

        Session.Clear();

In the above code I have setup the context, that is - I want to add a new person with photo to the database - (please have a look at the source code regarding the base class Person_Fixture which I use)

The first test I write is again smoke test, which should run just to test that setting up the context doesn't throw an exception.

// Smoke test

[Test]

public void should_execute_without_an_error()

    true.ShouldBeTrue();

And indeed, if you run this test it is green. This tells me that the method Context is running without causing an exception.

Remarks: All the ShouldXXX methods you'll see in the presented code fragments are extension methods I defined and use for better readability of the code. You can find them here.

The second test method checks whether there exists indeed a person record in the database

[Test]

public void person_should_exist_in_the_database()

    var fromDb = Session.Get<Person>(person.Id);

    fromDb.ShouldNotBeNull();

    fromDb.ShouldNotBeTheSameAs(person);

    fromDb.LastName.ShouldEqual(person.LastName);

    fromDb.FirstName.ShouldEqual(person.FirstName);

In the above code I first check whether a non null object is loaded from db and then whether it is a different instance (that is it has not been just loaded from the first level cache of NHibernate --> please see also this post) which means it has really been loaded from the database. Finally I check some of the properties for equality. As you might have expected: this test is green when run.

Now I want to also check whether the photo has really been stored in the database or not. The following test should confirm that

[Test]

public void person_photo_should_exist_in_the_database()

    var fromDb = Session.Get<Person>(person.Id);

    fromDb.Photo.ShouldNotBeNull();

    fromDb.Photo.ShouldNotBeTheSameAs(person.Photo);

    fromDb.Photo.Image.ShouldEqual(person.Photo.Image);

Well, green again when run - so no problem!

One important thing to check is that the very same photo cannot assigned to two different person instances. Each photo is uniquely assigned to a certain person. The following test verifies that behavior.

[Test]

public void adding_another_person_with_same_photo_should_not_be_possible()

    var otherPerson = new Person("Doe", "John", photo);

    Session.Save(otherPerson);

try

        Session.Flush();

        Assert.Fail("Expected exception!");

    catch(HibernateException)

        Session.Clear();

this code needs some further explanation. As you probably can see I expect that NHibernate throws an exception when trying to add a new person having the same photo as an already existing person. The exception is not thrown when calling the save method of the session but only when the session is flushed (that is: the insert command is executed on the database). I clear the session in the catch block since otherwise the exception would be raised again by my test tear-down method (in the base fixture class) which also flushes and disposes the session object.

The above test also passes and thus we are left with only one additional test. Does the person photo indeed lazy load? Let's write a test which verifies this

[TestFixture]

public class when_loading_an_existing_person_from_database : Person_Fixture

    private PersonPhoto photo;

    private Person person;

    protected override void Context()

        base.Context();

        photo = new PersonPhoto { Image = Encoding.Default.GetBytes("This is a placeholder for a photo...") };

        person = new Person("Schenker", "Gabriel", photo);

        Session.Save(person);

        // clean up

        Session.Flush();

        Session.Clear();

    [Test]

    public void Person_photo_should_be_lazy_loaded()

        var fromDb = Session.Load<Person>(person.Id);

        NHibernateUtil.IsInitialized(fromDb.Photo).ShouldBeFalse();

        var image = fromDb.Photo.Image;

        NHibernateUtil.IsInitialized(fromDb.Photo.Image).ShouldBeTrue();

Again I first setup the context for the test, that is I add a person with a photo to the database. Then in the test method I load the previously save person from database and with the aid of a utility class of NHibernate I check whether the property Photo of the person entity is un-initialized (i.e. the entity behind the property is not loaded). Then I access the property and finally I use the utility class again to test whether now the photo has been (lazy) loaded.

Wow - the test passes! We have found a mapping which satisfies all our needs!

Mapping with Fluent NHibernate

As described in earlier posts (part 1, part 2, part 3 and part 4) we have the possibility to use Fluent NHibernate to map our entities. Mapping this way has many advantages (I already discussed in the posts just mentioned). Let's have a look at the mapping needed for the Person entity

public class PersonMapper : ClassMap<Person>

    public PersonMapper()

        LazyLoad();

        Id(x => x.Id);

        Map(x => x.FirstName);

        Map(x => x.LastName);

        References(x => x.Photo)

            .FetchType.Select()

            .Cascade.All()

            .TheColumnNameIs("PersonPhotoId")

            .WithUniqueConstraint();

I define a mapper class which inherits form the generic ClassMap<T> base class provided by the Fluent NHibernate framework. In the constructor of this class I define the mapping. The first line defines that I want my person entity to be lazy loaded (by default in Fluent NHibernate all entities are NOT lazy loaded).

The many-to-one relation between person and person photo is mapped with the aid of the References method.

The PersonPhoto entity is mapped as follows

public class PersonPhotoMapper : ClassMap<PersonPhoto>

    public PersonPhotoMapper()

        LazyLoad();

        Id(x => x.Id);

        Map(x => x.Image);

        HasOne(x => x.Owner)

            .PropertyRef(x=>x.Photo)

            .Constrained();

Here the part that interests us most (the reverse relation from photo to person) is mapped with the aid of the HasOne method.

Unit testing the Fluent NHibernate mapping

There is not much to say about this. The unit test are nearly the same with only one difference. I use a different base class from which I derive all my test classes. The definition of the base class used can be found here.

Code

You can find the accompanying this post here.

Summary

I have shown you a way how you can structure your domain model and map your entities to be able to lazy load "extra" information of a given entity. I have explained how to map the domain by using standard XML mapping files as well as by using the Fluent NHibernate framework. By applying this technique you can massively improve the performance of queries and reduce the bandwidth needed to transfer data from the database to the consuming client.

[Update] Uni-directional link between Person and PersonPhoto

In a comment I was asked why I implemented the relation between the person and the person photo entity as bi-directional and whether it would not be possible to only implement and uni-directional realtion between person and person photo.

The answer is: there is NO special reason for having a bi-directional relation (Eric Evans in his DDD book even suggests to keep the relations uni-directional whenever possible). And yes, it is possible to implement the sample with an uni-directional relation. I'll show the details below (this time I only show the mapping in Fluent NHibernate but the XML mapping is straight forward.

Here is the model with only an uni-directional relation

and the code

public class Person

    public virtual Guid Id { get; private set; }

    public virtual string LastName { get; private set; }

    public virtual string FirstName { get; private set; }

    public virtual PersonPhoto Photo { get; private set; }

    // to satisfy NHibernate only!

    public Person() { }

    public Person(string lastName, string firstName, PersonPhoto personPhoto)

        LastName = lastName;

        FirstName = firstName;

        AssignPhoto(personPhoto);

    public virtual void AssignPhoto(PersonPhoto photo)

        Photo = photo;

public class PersonPhoto

    public virtual Guid Id { get; set; }

    public virtual byte[] Image { get; set; }

Now let me show the mapping for this model (Fluent NHibernate)

public class PersonMapper : ClassMap<Person>

    public PersonMapper()

        LazyLoad();

        Id(x => x.Id);

        Map(x => x.FirstName);

        Map(x => x.LastName);

        References(x => x.Photo)

            .FetchType.Select()

            .Cascade.All()

            .TheColumnNameIs("PersonPhotoId")

            .WithUniqueConstraint();

public class PersonPhotoMapper : ClassMap<PersonPhoto>

    public PersonPhotoMapper()

        LazyLoad();

        Id(x => x.Id);

        Map(x => x.Image);

If I generate the schema from this model I get the very same create table scripts as in the bi-directional sample. And all the other unit tests I have shown above run successfully.

The code has been updated to contain both samples the uni- and the bi-directional relation.

Enjoy

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.

A fluent interface to NHibernate - Part 3 - Mapping Relations

NHibernate's Answers — Fri, 15 Aug 2008 13:36:03 GMT

This is the third post in a series of articles where I want to analyze and describe the new upcoming mapping interface providing a fluent interface to NHibernate for the mapping of a domain model to the underlying database. The other posts are

You can get the source code of the solution accompanying this post here.

In the time between my last post and today a lot has happened to the mapping framework. The contributors are busily improving the source and are also very responsive to my questions and remarks.

In this post I want to focus on how one can map various relations between entities and value objects of a domain model.

Scenario 3

Domain Model

Let's have a look at the following simplified model

I have a Blog which has an author of type Person. Each Blog can have many Posts. To each Post readers can give feedback in the form of Comments. Comments are considered value objects in this model, that is they have no identity and are immutable (a reader cannot edit its comment after it has been published...). All other elements are true entities. If I consider the Blog to be the root object then the relation between Blog and Person is of type many-to-one (a person can be the owner of more than one blog). On the other hand the relation between Blog and Post is of type one-to-many. The parent and the children are both entities.

A special case (as we will see) is the relation between Post and Comment (since Comment is a value object). It is also of type one-to-many but this time the parent is an entity and the children are value objects.

Mapping

How can we map this? Well, let's start with the easy one. In this simplified model the Person class has no external dependencies and is thus easy to map

public class PersonMap : ClassMap<Person>

    public PersonMap()

        Id(x => x.Id);

        Map(x => x.FirstName);

        Map(x => x.LastName);

The Comment class has also no external dependencies. I want to treat the Comment as a value Object. So I have to map it as follows

public class PostMap : ClassMap<Post>

    public PostMap()

        Id(x => x.Id);

        Map(x => x.Title);

        Map(x => x.Body);

        Map(x => x.PublicationDate);

        HasManyComponent<Comment>(x => x.Comments,

                                  c =>

                                          c.Map(x => x.Text);

                                          c.Map(x => x.AuthorEmail);

                                          c.Map(x => x.CreationDate);

                                      }).AsSet();

I had to implement the method HasManyComponent by myself since it was missing in the actual trunk of the framework. That is, it was not possible to map a collection of value objects. But it has not been that hard since the source base is really nice. My changes will probably be integrated into the framework soon. The official contributors to the project are VERY responsive and do their best to fix bugs and/or implement missing features. Keep on rolling guys! IMHO we will see soon a high adoption rate of this new framework in the NHibernate community if the development pace stay at this high rate.

I don't want to show the implementation details of the method mentioned above in this post since it is off-topic and since it will soon be incorporated into the framework anyway. Eventually the name of the method will change though...

Finally we can map the Blog class which is now easy

public class BlogMap : ClassMap<Blog>

    public BlogMap()

        Id(x => x.Id);

        Map(x => x.Name);

        References(x => x.Author);

        HasMany<Post>(x => x.Posts).AsSet();

Note that we map the many-to-one relation between Blog and Person with the aid of the References method. Note further that we map the collection of Posts with the HasMany method. Since by default this method maps to a "bag" we have to further specify that we want to map with a "set" (--> see my post on collection mapping for the various types of collections).

The XML generated by the above mapping class is shown below. Now you can ask yourself which way of mapping your entities you prefer...

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

<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" default-lazy="false"

                   assembly="FluentMapping.Domain"

                   namespace="FluentMapping.Domain.Scenario3">

  <class name="Post" table="[Post]" xmlns="urn:nhibernate-mapping-2.2">

    <id name="Id" column="Id" type="Int64">

      <generator class="identity" />

    </id>

    <property name="PublicationDate" column="PublicationDate" type="DateTime">

      <column name="PublicationDate" />

    </property>

    <property name="Body" column="Body" length="100" type="String">

      <column name="Body" />

    </property>

    <property name="Title" column="Title" length="100" type="String">

      <column name="Title" />

    </property>

    <set name="Comments" cascade="none">

      <key column="Post_id" />

      <composite-element class="FluentMapping.Domain.Scenario3.Comment,

                                FluentMapping.Domain, Version=1.0.0.0,

                                Culture=neutral, PublicKeyToken=null">

        <property name="CreationDate" column="CreationDate" type="DateTime">

          <column name="CreationDate" />

        </property>

        <property name="AuthorEmail" column="AuthorEmail" length="100" type="String">

          <column name="AuthorEmail" />

        </property>

        <property name="Text" column="Text" length="100" type="String">

          <column name="Text" />

        </property>

      </composite-element>

    </set>

  </class>

</hibernate-mapping>

Ok I admit, when hand crafting the XML we can skip some of the elements, but still...

Testing

All tests use the base class FixtureBase which I have introduced in my first post about the mapping framework. In the mean time the SessionSource class of the framework has been re-factored such as that it now works for our scenarios and I don't have to use my own implementation any more. For completeness I present here the updated source once again

public class FixtureBase

    protected SessionSource SessionSource { get; set; }

    protected ISession Session { get; private set; }

    [SetUp]

    public void SetupContext()

        Before_each_test();

    [TearDown]

    public void TearDownContext()

        After_each_test();

    protected virtual void Before_each_test()

        SessionSource = new SessionSource(new TestModel());

        Session = SessionSource.CreateSession();

        SessionSource.BuildSchema(Session);

        CreateInitialData(Session);

        Session.Flush();

        Session.Clear();

    protected virtual void After_each_test()

        Session.Close();

        Session.Dispose();

    protected virtual void CreateInitialData(ISession session)

The only two lines that have changed are printed in bold.

Now let's test whether we can create a blog and add posts to it. Let's start with the former. I define a base class for all my further blog related tests as

public class Blog_Fixture : FixtureBase

    protected Person author;

    protected override void CreateInitialData(ISession session)

        base.CreateInitialData(session);

        author = new Person {FirstName = "Gabriel", LastName = "Schenker"};

        session.Save(author);

In the CreateInitialData method I create an author object since every blog has to have an author. I save this author object to the database. To make the author available to all child test classes I have declared it as a protected filed. Now to the test which tries to create a new blog and verifies that it has be written correctly and completely to the database

[TestFixture]

public class When_no_blog_exists : Blog_Fixture

    [Test]

    public void Can_add_new_blog()

        var blog = new Blog {Name = "Gabriel's Blog", Author = author};

        Session.Save(blog);

        Session.Flush();

        Session.Clear();

        var fromDb = Session.Get<Blog>(blog.Id);

        fromDb.ShouldNotBeNull();

        fromDb.ShouldNotBeTheSameAs(blog);

        fromDb.Id.ShouldEqual(blog.Id);

        fromDb.Name.ShouldEqual(blog.Name);

        fromDb.Author.ShouldNotBeNull();

        fromDb.Author.Id.ShouldEqual(blog.Author.Id);

Note that I have inherited this test class from the previously implemented Blog_Fixture class. In the test method I first create a new blog instance. Then I save it to the database. I then flush and clear the session instance to guarantee that all the object(s) in NHibernate's session cache are written to the DB and that the cache is cleared afterwards such as that when a read operation is invoked the respective object is really retrieved from the database.

If you wonder where all these ShouldXXX methods in the second part of the test come from then wonder no longer. These are extension methods which I have implemented. They make all the asserts that you normally would do with the aid on NUnit's Assert class. But like this the code is way more readable, isn't it? If you wonder how these methods are implemented then please have a look into the source code of the solution accompanying this post. Search for the class SpecificationExtensions.

When running this test it succeeds!

But we have seen in the past that the framework offers us some help to reduce the size of our test methods. So let's revisit the test and leverage the framework.

[Test]

public void Can_add_new_blog_revisited()

    new PersistenceSpecification<Blog>(Session)

        .CheckProperty(x => x.Name, "Gabriel's Blog")

        .CheckProperty(x => x.Author, author);

Yeah, much shorter! That's what I call wrist friendly... Of course when run also this test succeeds.

Second we want to try to add a post to an already existing blog. I have the following code for that

[TestFixture]

public class When_a_blog_exists : Blog_Fixture

    private Blog blog;

    protected override void CreateInitialData(ISession session)

        base.CreateInitialData(session);

        blog = new Blog {Name = "Gabriel's Blog", Author = author};

        session.Save(blog);

    [Test]

    public void Can_add_post_to_blog()

        var post = new Post

                        Title = "First Post",

                        Body = "Just a test",

                        PublicationDate = DateTime.Today

};

        blog.Posts.Add(post);

        Session.Update(blog);

        Session.Flush();

        Session.Clear();

        var fromDb = Session.Get<Blog>(blog.Id);

        fromDb.Posts.Count.ShouldEqual(1);

        fromDb.Posts.First().Id.ShouldEqual(post.Id);

In the CreateInitialData I setup my context which in this case is: I have a blog in the database. In the test method I take this existing blog instance and add a new post to it. I then tell the session to update the blog. As usual I flush and clear the session before I assert that the operation was indeed successful.

Now I reload the blog from the database and test whether it has one post as expected and whether it's the post we have added to the blog (it suffices to test the post's id). Note that the method First() applied to the Posts collection of the blog (on the last line of the test) is also an extension method. This extension method just returns the first element of any collection of objects implementing IEnumerable<T> onto which it is applied.

Again when we run the test it is successful.

We want to leverage the framework once more and thus I revisit the test

[Test]

public void Can_add_post_to_blog_revisited()

    var posts = new[]

                        new Post {

                                    Title = "First Post",

                                    Body = "Just a test",

                                    PublicationDate = DateTime.Today

},

                        new Post {

                                    Title = "Second Post",

                                    Body = "Just another test",

                                    PublicationDate = DateTime.Today.AddDays(-1)

},

};

    new PersistenceSpecification<Blog>(Session)

        .CheckProperty(x => x.Name, "Gabriel's Blog")

        .CheckProperty(x => x.Author, author)

        .CheckList(x=>x.Posts, posts);

Once again I use our friend the PersistenceSpecification class. This time I use it's method CheckList to test the Posts collection of the blog instance. This method expects a collection of Post objects which I have defined in the first part of this test. Here I have defined two posts in the list but also a single one would suffice for the test.

Let me resume: to completely test the mapping of the Blog class I need four lines of code! Nice.

The last thing we have left to test is whether we can add comments to our posts. First I setup my context; that is I have a blog with one post. I also prepare a comment which I can then later on add to the post.

[TestFixture]

public class When_a_blog_with_a_post_exists : Blog_Fixture

    private Blog blog;

    private Post post;

    private Comment comment;

    protected override void CreateInitialData(ISession session)

        base.CreateInitialData(session);

        blog = new Blog { Name = "Gabriel's Blog", Author = author };

        post = new Post

                       Title = "First Post",

                       Body = "Just a test",

                       PublicationDate = DateTime.Today

};

        blog.Posts.Add(post);

        session.Save(blog);

        comment = new Comment("This is my comment", DateTime.Today, "someone@gmail.com");

Once my context is set up writing the test is easy. I read the post from the database, add the prepared comment to it and then flush and clear the session (note that the session automatically realizes that the post is dirty and that an update must be made to the database). The I re-read the post from the database and verify that indeed one comment was added and that it is the comment which I expect (by comparing it's Id).

[Test]

public void Can_add_comment_to_post()

    var thePost = Session.Get<Post>(post.Id);

    thePost.Comments.Add(comment);

    Session.Flush();

    Session.Clear();

    var fromDb = Session.Get<Post>(post.Id);

    fromDb.Comments.Count.ShouldEqual(1);

    fromDb.Comments.First().Equals(comment);

And again the test succeeds. Unfortunately we cannot leverage the framework this time since the CheckList method of the PersistenceSpecification class does not yet work for collections of value objects. But I'm sure this will be fixed soon. The test would be like this

[Test][Ignore(".CheckList is not yet working")]

public void Can_add_comment_to_post_revisited()

    new PersistenceSpecification<Post>(Session)

        .CheckProperty(x => x.Title, "Some title")

        .CheckProperty(x => x.Body, "Some text")

        .CheckProperty(x => x.PublicationDate, DateTime.Today)

        .CheckList(x => x.Comments, new[] {comment});

Source Code

You can get the source code of the solution accompanying this post here.

Summary

In this post I have shown you that the mapping framework is indeed ready for mapping more advanced scenarios. I have shown you how to map one-to-many relations where either the children are entities or the children are value objects. I also have shown how to map many-to-one relations.

Create and Update Database Schema

NHibernate's Answers — Mon, 28 Apr 2008 21:52:51 GMT

Introduction

When developing an application using DDD one starts by trying to define a model of the domain for/in which the application should be used. At the same time you try to establish the so called ubiquitous language. At some point you might need to store and or retrieve data into or from a data source. Very often this data source is a relational database. But it's not necessarily always the case. It could as well be a web service or a XML document. That leads me to the notion that "the database is just an implementation detail of the application". Or if I turn this sentence a little bit around "...it should not be the database (-schema) that determines the design of an application but rather should the database schema be a natural outcome of the domain model...". I know, this is NOT what a DBA likes to hear. But trust me I have developed many applications in the past where the first thing that was designed of the application was the entity relationship diagram (ERD)... I have also implemented quite a lot of stored procedures on Oracle and SQL server in the past. So I know both sides of the argument.

Assuming that the database schema should be an implementation detail of the overall application it would be great if the schema could be somehow auto-generated from the domain model. As you might expect, when using NHibernate as the ORM tool this is possible. We have to distinguish between the two possibilities

(re-) create a new schema from scratch
updating an existing schema

Create Schema

The model

To start we define a very basic model

The Mappings

In our data layer we define the two mapping files Product.hbm.xml and Category.hbm.xml. The former's content is

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

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

                   namespace="Domain"

                   assembly="Domain">

  <class name="Product">

    <id name="Id">

      <generator class="guid"/>

    </id>

    <property name="Name"/>

    <many-to-one name="Category" class="Category"/>

  </class>

</hibernate-mapping>

and the latter's content is

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

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

                   namespace="Domain"

                   assembly="Domain">

  <class name="Category">

    <id name="Id">

      <generator class="guid"/>

    </id>

    <property name="Name"/>

  </class>

</hibernate-mapping>

Note that we have defined only the absolute minimum needed and rely heavily on the (meaningful) defaults provided by NHibernate.

Tests

To analyze the database schema creation script generated by NHibernate we write the following test

[TestFixture]

public class CreateSchema_Fixture

    private Configuration _cfg;

    [SetUp]

    public void SetupContext()

        _cfg = new Configuration();

        _cfg.Configure();

        _cfg.AddAssembly(Assembly.LoadFrom("DataLayer.dll"));

    [Test]

    public void Create_a_database_schema_creation_script()

        var export = new SchemaExport(_cfg);

        var sb = new StringBuilder();

        TextWriter output = new StringWriter(sb);

        export.Execute(true, false, false, false, null, output);

Note that the configuration file hibernate.cfg.xml has the following content in our case

<?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=NHibernateFAQ;Integrated Security=SSPI;</property>

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

  </session-factory>

</hibernate-configuration>

That is, we are using a SQL Server 2005 database called NHibernateFAQ. It is not necessary to have SQL Server 2005 installed though since we are only generating (and analyzing) the scripts generated by NHibernate and not accessing the database itself!

The output generated by the above test is similar to this

if exists (select 1 from sys.objects

           where object_id = OBJECT_ID(N'[FK1F94D86A9F364CC5]')

           AND parent_object_id = OBJECT_ID('Product'))

    alter table Product  drop constraint FK1F94D86A9F364CC5

if exists (select * from dbo.sysobjects

           where id = object_id(N'Product')

           and OBJECTPROPERTY(id, N'IsUserTable') = 1)

    drop table Product

if exists (select * from dbo.sysobjects

           where id = object_id(N'Category')

           and OBJECTPROPERTY(id, N'IsUserTable') = 1)

    drop table Category

create table Product (Id UNIQUEIDENTIFIER not null,

                      Name NVARCHAR(255) null,

                      Category UNIQUEIDENTIFIER null,

                      primary key (Id))

create table Category (Id UNIQUEIDENTIFIER not null,

                       Name NVARCHAR(255) null,

                       primary key (Id))

alter table Product add constraint FK1F94D86A9F364CC5

foreign key (Category) references Category

That's really wonderful for a quick shot!

The default for a column is that it is nullable and the default type and length for a string type field is NVARCHAR(255).

Mandatory columns and maximal length of column

But there are a few details that we might want to improve. First we want to make the Name columns mandatory (NOT NULL). Nothing easier than that; just add an attribute not-null="true" to the mapping files where appropriate. Also we want to limit the length of the Name column to given amount, e.g. 50 characters. Just add a length="50" to the appropriate property of the mapping files. The create table part of the schema creation script is then

create table Product (Id UNIQUEIDENTIFIER not null,

                      Name NVARCHAR(50) not null,

                      Category UNIQUEIDENTIFIER null,

                      primary key (Id))

create table Category (Id UNIQUEIDENTIFIER not null,

                       Name NVARCHAR(20) not null,

                       primary key (Id))

Foreign Keys

There is still a detail in the script that might disturb you. It's the name of the foreign key constraint between the Product and the Category tables. If we want to choose a name we can use the foreign-key attribute on the many-to-one node of the mapping file, e.g.

<many-to-one name="Category" class="Category" foreign-key="fk_Product_Category"/>

now the corresponding snippet of the script is

if exists (select 1 from sys.objects

           where object_id = OBJECT_ID(N'[fk_Product_Category]')

           AND parent_object_id = OBJECT_ID('Product'))

    alter table Product  drop constraint fk_Product_Category

...

alter table Product add constraint fk_Product_Category

foreign key (Category) references Category

Unique Constraints

If we want to guarantee that the Name property of the Category class is unique we can do this by either using business logic to enforce this requirement or define a unique constraint on the database. Let's have a look at the latter. Just add the attribute unique="true" to the mapping of the Name property in the mapping file for the Category class. That is

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

and the script generated is this

create table Category (

    Id UNIQUEIDENTIFIER not null,

    Name NVARCHAR(20) not null unique,

    primary key (Id)

If you want to define a unique constraint which spans multiple columns then you have to resort to the attribute unique-key. Let's assume we have a Person class like

public class Person

    public Guid Id { get; set; }

    public string FirstName { get; set; }

    public string LastName { get; set; }

and we want to define a unique constraint on the combination of the FirstName and LastName columns then our mapping file looks like this

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

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

                   namespace="Domain"

                   assembly="Domain">

  <class name="Person">

    <id name="Id">

      <generator class="guid"/>

    </id>

    <property name="FirstName" not-null="true" length="50" unique-key="uk_Person_Name"/>

    <property name="LastName" not-null="true" length="50" unique-key="uk_Person_Name"/>

  </class>

</hibernate-mapping>

Note that the name you choose for the unique-key is not important (here "uk_Person_Name"). Just use the same name for all columns that make up for a unique constraint. The create table script generated by NHibernate is then

create table Person (

    Id UNIQUEIDENTIFIER not null,

    FirstName NVARCHAR(50) not null,

    LastName NVARCHAR(50) not null,

    primary key (Id),

    unique (FirstName, LastName)

Indices

We might also want to tune our database schema and define some indices. Often we might search for a product by its name and thus the Name column might be a good candidate for an index. How can we do this. Well it's again very easy. Just add the attribute index to the right property tag in the product mapping file and provide a name for the index. That is

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

now our create script will look like this (note the second last statement where the index is created)

create table Category (Id UNIQUEIDENTIFIER not null, ...)

create table Product (Id UNIQUEIDENTIFIER not null, ...)

create index idx_Product_Name on Product (Name)

alter table Product add constraint fk_Product_Category ...

Check Constraints

We can also define some check constraints on our columns in the database. Let's assume our product has a UnitsOnStock property which must be greater or equal than zero. To define this constraint on the database column we can define the mapping of UnitsOnStock as follows

<property name="UnitsOnStock" not-null="true" >

  <column name="UnitsOnStock" check="UnitsOnStock >= 0"/>

</property>

Note that there is no check attribute defined for the property tag. Thus we have to use the child tag column for this purpose. The create table script is then

create table Product (

    Id UNIQUEIDENTIFIER not null,

    Name NVARCHAR(50) not null,

    UnitsOnStock INT null check( UnitsOnStock >= 0) ,

    Category UNIQUEIDENTIFIER not null,

    primary key (Id)

Update Schema

Once we have an existing database schema which we cannot re-create from scratch (because we might already have a first version of our application in production with productive data...) we need another technique. Fortunately NHibernate provides us the possibility to update an existing schema, that is NHibernate creates an update script which can the be applied to the database.

As usual we want to define a unit test for this situation. In the setup for the unit test I'll predefine a first version of my database schema. This time we need to have a database installed on the system (in our case SQL Server 2005) since this first version of the schema is generated in the database otherwise update schema will not work.

So let's have a look at the setup

[TestFixture]

public class UpdateSchema_Fixture

    private Configuration _cfg;

    public const string product_xml =

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

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

        "                   namespace='Domain'"+

        "                   assembly='Domain'>"+

        "  <class name='Product'>"+

        "    <id name='Id'>"+

        "      <generator class='guid'/>"+

        "    </id>"+

        "    <property name='Name' not-null='true' length='20'/>" +

        "  </class>"+

        "</hibernate-mapping>";

    public const string category_xml =

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

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

        "                   namespace='Domain'"+

        "                   assembly='Domain'>"+

        "  <class name='Category'>"+

        "    <id name='Id'>"+

        "      <generator class='guid'/>"+

        "    </id>"+

        "  </class>"+

        "</hibernate-mapping>";

    [SetUp]

    public void SetupContext()

        // Setup "old" database schema

        _cfg = new Configuration();

        _cfg.Configure();

        _cfg.AddXml(product_xml);

        _cfg.AddXml(category_xml);

        var export = new SchemaExport(_cfg);

        export.Execute(false, true, false, false);

I define 2 strings containing the (first version of the) mapping files for the Category and the Product class. In the SetupContext method I create a configuration object and feed it with these two mapping XML fragments. I then export this schema to the database by creating an instance of the SchemaExport class and calling the Execute method.

Note that the Category mapping fragment does not contain a mapping for the Name column and the Product mapping fragment does not contain a mapping for the relation to the Category class as well as no definition of the UnitsInStock column.

Now I want to test the UpdateSchema class and thus implement the following test

[Test]

public void Update_an_existing_database_schema()

    _cfg = new Configuration();

    _cfg.Configure();

    _cfg.AddAssembly(Assembly.LoadFrom("DataLayer.dll"));

    var update = new SchemaUpdate(_cfg);

    update.Execute(true, false);

The update script generated by NHibernate is

alter table Category add Name NVARCHAR(20) unique

alter table Product add UnitsOnStock INT check(UnitsOnStock >= 0)

alter table Product add Category UNIQUEIDENTIFIER

alter table Product add constraint

fk_Product_Category foreign key (Category) references Category

As expected I only get alter statements for existing tables and create statements for the elements missing so far.

Code

You can find the code here. Download it with a SVN client like TortoiseSVN. It's a VS 2008 project.

Summary

When developing a application using DDD the database is often considered an "implementation detail". NHibernate provides us tools to auto-generate create and alter scripts for the database schema from the domain model. I have shown you, by using a simple domain model how to create a schema from scratch and how to alter a pre-existing database schema. I have also discussed various optimization techniques used when creating database schemas as there are unique constraints, indices and check constraints.

Enjoy

NHibernate and Castle Active Record (Part 1)

NHibernate's Answers — Sat, 26 Apr 2008 19:33:44 GMT

Introduction

The Castle ActiveRecord project is an implementation of the ActiveRecord pattern for .NET. The ActiveRecord pattern consists on instance properties representing a record in the database, instance methods acting on that specific record and static methods acting on all records.

Castle ActiveRecord is built on top of NHibernate, but its attribute-based mapping free the developer of writing XML for database-to-object mapping, which is needed when using NHibernate directly.

You can find the home page of the Castle project here.

How will we use it?

My intent is not to implement the ActiveRecord pattern but rather use ActiveRecord

as an alternative way to define the mapping between my domain objects and the relational database.
to simplify the initialization of NHibernate (I'm not so sure about this...)

In my previous posts (here and here) I have shown you how to define the mapping between domain objects and database tables by writing XML documents. Active Record allows me to decorate my domain objects with attributes which define the mapping instead of (hand-) coding XML documents.

Downloading and compiling the Castle Active Record Trunk

If you have never downloaded and compiled OSS software from a SVN repository before please refer to my previous post about preparing your system for NHibernate which you can find here.

I assume you have TortoiseSVN installed as your SVN client.

Make a new sub-folder called 'Castle' in your OSS folder (e.g. m:\dev\OSS\Castle). Right click on the folder an select 'SVN Checkout...'. Enter the URL 'http://svn.castleproject.org:8080/svn/castle/trunk/' in the Checkout dialog and press OK. The Castle stack will be downloaded. Depending on the bandwidth of your Internet connection this may take a while. The whole Castle stack contains more software than we need at the moment but let's just download all and ignore the parts we don't need. The whole download is around 21 MB.

When the download is finished you can compile the Castle stack. This is an automated process.

Unit Tests during the build process

During the build a lot of unit tests will be executed. For this we either need NUnit or MbUnit on our system. If you don't have it you can e.g. download NUnit from here. Download just the zip file containing the binaries for .NET 2.0 (at the time of this writing it's the file 'NUnit-2.4.7-net-2.0.zip'). Extract the binaries into a sub-folder of your OSS directory (e.g. m:\dev\OSS\nunit).

Building the Castle Stack

Open a command console and navigate to the directory where you have downloaded Castle (e.g. m\dev\OSS\Castle). Assuming that NAnt is also installed in the OSS directory enter the following command

..\NAnt\bin\nant.exe -D:nunit-console=<path to nunit-console.exe>

where at the place of <path to nunit-console.exe> you enter the path where you have unzipped/installed NUnit. In our case this is 'm:\dev\OSS\NUnit\bin\NUnit-Console.exe'.

Now the whole Castle stack is compiled and all tests are executed. This can take a while. On my machine it took about 2.5 minutes. The overall build may fail but still the assemblies are created (the reason of the overall failure might be that some of the Unit test fail. Remember that we are on the Trunk and this is under constant development. Sometimes some of the tests may thus fail.). The result on my machine was as follows

After building the Castle stack you should find a new sub-folder 'build' in the Castle folder.

Using Active Record

External dependencies of the Solution

For an introduction on how to setup a new solution please refer to this post. You can now copy all the necessary external assemblies on which the solution depends into the SharedLibs folder in your solution tree. You should copy all files (including NHibernate) from the build folder of Castle which was created during the build process described above. For this solution you need at least the following files

The sql*.dll are in the folder since we are using SQL Server Compact edition as a database. If you have read the previous posts about using NHibernate (e.g. here and here) the only new files are Castle.ActiveRecord.dll and Castle.Components.Validator.dll.

The Domain Model and the Mapping

To have a good comparison let's take the same domain model as in this post. Below is the class diagram of the domain.

Now instead of writing a domain class and then a XML mapping document we now only write the domain class and decorate it and its members with attributes. During initialization ActiveRecord will automatically generate the XML mapping documents for us which NHibernate requires for the object-relational mapping.

When using attributes the Order class will look like this

using System;

using Castle.ActiveRecord;

using Iesi.Collections.Generic;

using NHibernateAndActiveRecord.Domain;

namespace NHibernateAndActiveRecord.Domain

    [ActiveRecord(Table = "Orders")]

    public class Order

        public Order()

            OrderLines = new HashedSet<OrderLine>();

        [PrimaryKey(Generator = PrimaryKeyType.Guid)]

        public virtual Guid Id { get; set; }

        [BelongsTo(NotNull = true)]

        public virtual Customer Customer { get; set; }

        [Property]

        public virtual string OrderNumber { get; set; }

        [Property]

        public virtual DateTime OrderDate { get; set; }

        [HasMany(Table = "OrderLine",

                 ColumnKey = "OrderId",

                 Cascade = ManyRelationCascadeEnum.AllDeleteOrphan)]

        public virtual ISet<OrderLine> OrderLines { get; set; }

compared to a typical XML mapping document this is much more wrist friendly, isn't it. Some people also argue that attributes help to document the code, since I can immediately see e.g. which is the primary key and which property values should never be null, etc. I do not have to consult another file but can just look at the domain class to have the "full" picture. On the other hand the attributes also "clutter" my nice code and I partially violate the SoC pattern since mapping is not part of the domain in a DDD world.

Now let's look at the OrderLine class

using System;

using Castle.ActiveRecord;

namespace NHibernateAndActiveRecord.Domain

    [ActiveRecord]

    public class OrderLine

        [PrimaryKey(Generator = PrimaryKeyType.Guid)]

        public virtual Guid Id { get; set; }

        [Property(NotNull = true)]

        public virtual int Amount { get; set; }

        [Property(NotNull = true, Length = 50)]

        public virtual string ProductName { get; set; }

Here I have defined that Amount and ProductName cannot be null (this will be used for the generation of the database schema - there will be not null constraints on the corresponding table column). I also have defined that the maximal length of the ProductName cannot exceed 50 characters (also used for schema generation).

Finally the Customer class

using System;

using Castle.ActiveRecord;

namespace NHibernateAndActiveRecord.Domain

    [ActiveRecord]

    public class Customer

        [PrimaryKey(Generator = PrimaryKeyType.Guid)]

        public virtual Guid Id { get; set; }

        [Property(NotNull = true, Length = 50)]

        public virtual string CompanyName { get; set; }

That's it. Our domain and mapping is complete. We can now write our tests similar to the once we used in this post.

Unit Tests

Add an xml document to your test project and call it ActiveRecord.cfg.xml (similar to what you do when you ONLY use NHibernate). Add the following content to the file

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

<activerecord>

  <config>

    <add key="connection.provider"

         value="NHibernate.Connection.DriverConnectionProvider" />

    <add key="dialect"

         value="NHibernate.Dialect.MsSqlCeDialect" />

    <add key="connection.driver_class"

         value="NHibernate.Driver.SqlServerCeDriver" />

    <add key="connection.connection_string"

         value="Data Source=SampleDb.sdf" />

    <add key="show_sql"

         value="true" />

  </config>

</activerecord>

Set the Copy to Output Directory to Copy always.

Note: we are using SQL server compact edition in this case (the second, third and fourth entry in the XML are specific for this database).

Add an new item of type LocalDatabase to the test project and call it SampleDb.sdf.

Still in the test project add a reference to the System.Data.SqlServerCe.dll in the SharedLibs folder. This assembly contains the ado.net driver for SQL server compact edition.

Open the properties page of the test project and add the following command in the "Pre-build event command line" text box

copy $(ProjectDir)..\..\SharedLibs\sqlce*.dll $(ProjectDir)$(OutDir)

This command copies all the SQL server CE files from the SharedLibs folder to the target folder of the test project. Note: this is important, otherwise the test will not run. Also note that this is only needed if you use SQL server CE.

The first unit test we write will test whether we can successfully create the database schema or not. This is always a good test if your new to ActiveRecord. Add a new class CreateSchema_Fixture.cs to the test project and add the code below

using Castle.ActiveRecord;

using Castle.ActiveRecord.Framework.Config;

using NHibernateAndActiveRecord.Domain;

using NUnit.Framework;

namespace NibernateAndActiveRecord.Tests

    [TestFixture]

    public class CreateSchema_Fixture

        [Test]

        public void Can_initialize_and_create_schema()

            var configurationSource = new XmlConfigurationSource("ActiveRecord.cfg.xml");

            ActiveRecordStarter.Initialize(typeof(Customer).Assembly, configurationSource);

            ActiveRecordStarter.CreateSchema();

In the first line of the test we provide ActiveRecord with the necessary configuration info. In the second line we tell ActiveRecord to initialize itself (and NHibernate) with the given configuration info as well as the assembly in which the domain classes are implemented (and which also contains the mapping info since we use attributes). Then in the third line we create the schema. If there is already a schema in the db this will be deleted first.

If you have done every thing right, then the test should succeed.

Now we can continue to test our domain model. Let's first implement a base fixture class to free us from repeating code again and again. I suggest a class as follows

using Castle.ActiveRecord;

using Castle.ActiveRecord.Framework.Config;

using NHibernateAndActiveRecord.Domain;

using NUnit.Framework;

namespace NibernateAndActiveRecord.Tests

    [TestFixture]

    public class TestFixtureBase

        [TestFixtureSetUp]

        public void TestFixtureSetUp()

            var configurationSource = new XmlConfigurationSource("ActiveRecord.cfg.xml");

            ActiveRecordStarter.Initialize(typeof(Customer).Assembly, configurationSource);

        [SetUp]

        public void SetupContext()

            ActiveRecordStarter.CreateSchema();

            Before_each_test();

        [TearDown]

        public void TearDownContext()

            After_each_test();

        protected virtual void Before_each_test()

{ }

        protected virtual void After_each_test()

{ }

This class is equivalent to the class presented in this post on NHibernate. Once for each test session I configure ActiveRecord (and implicitly NHibernate). Before each single test I recreate the database schema to avoid any side effects leaking from one test to another. I also provide virtual methods which can be overridden in the child classes to execute specific code before or after each test.

Summary

I have introduced Castle ActiveRecord as an alternative way to use NHibernate. It's a layer on top of NHibernate and simplifies in many cases the usage of NHibernate. I have shown you how you can get the latest code from the source repository and compile it. I have then setup a simple domain model and defined a test fixture base class.

I'll continue to implement the tests in part 2 of this series. So keep ready...

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