Mapping

Article series on NHibernate and Fluent NHibernate – Part 3

NHibernate's Answers — Wed, 02 Sep 2009 04:51:14 GMT

Today the third part of my series on NHibernate and Fluent NHibernate went live. It took a little bit longer due to work overload. You can read it here.

Summary

In part 3 of this article series about NHibernate and Fluent NHibernate I have discussed how to let Fluent NHibernate automatically map a domain model to a data model. We have realized that FNH provides a reasonable mapping out of the box by using default conventions. I have shown how one can implement user defined conventions which will influence how the mapping is defined on a very fine grained level. I have also shown that if we use a base class in our domain which implements common functionality we can instruct FNH to ignore this class and just map the “real” entities.

FNH with its auto mapping feature reduces the task of mapping a complex domain to an underlying data model to just a few keystrokes. And as is always true: less code results in less bugs and less maintenance overhead.

Article series on NHibernate and Fluent NHibernate – Part 2

NHibernate's Answers — Thu, 16 Apr 2009 12:30:10 GMT

Today the second part of my series on NHibernate and Fluent NHibernate went live. You can read it here.

Summary

In part 2 of the article series I have continued to implement the remaining part of the domain which I had introduced in the first part. I discuss the mapping of various forms of relations between different entities. For all mappings I have presented the code needed to verify the mappings.

In part 3 of the article series I’ll show how one can further refactor and improve the mapping of the domain model. I’ll then discuss the usage of conventions and finally show how one can use the auto-mapping capabilities of Fluent NHibernate to completely avoid the explicit mapping of entities.

Article series on NHibernate and Fluent NHibernate

NHibernate's Answers — Thu, 09 Apr 2009 00:04:51 GMT

Sorry for having been quiet such a long time. But I was really busy lately. I wrote several articles for journals and other non NHibernate related posts. But now the good news for all of you who like my tutorial like posts...

I have been invited to write a series of articles on NHibernate and Fluent NHibernate on http://dotnetslackers.com.

The first part of this series has just been published. I invite you to read it here.

In this series I start from grounds up and will explain to the readers how easy it has become to write an NHibernate based application since Fluent NHibernate is available. I’ll explain the explicit mapping with the fluent syntax as well as the auto-mapping that Fluent NH offers.

This is a total overhaul compared to my first introduction to NHibernate of last year which is still the most popular post of this blog... ;-)

Enjoy.

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

A fluent interface to NHibernate - Part 4 - Configuration

NHibernate's Answers — Tue, 26 Aug 2008 07:07:39 GMT

This is the fourth 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 previous post are

Configuration

In NHibernate we traditionally had several methods how we could configure the database relevant parameters. These are

defining all requested configuration parameters in code
include a special section in the app.config or web.config file
define a hibernate.cfg.xml file
define a custom XML file

With the new mapping framework we have one more possibility by using a fluent interface to configure NHibernate. We can define all parameters in our code using a fluent interface. Let's review the various methods to configure our ORM framework.

Defining requested configuration parameters in code

When initializing the NHibernate framework I can configure all necessary parameters in code. I just instantiate a Configuration object and pass it all requested parameters via the SetProperty method. Having set all necessary connection parameters I can now define where my domain model is. In the sample below I take the AddAssembly method to tell NHibernate that all my model classes are to be found in the assembly where the class Blog is defined. NHibernate will then parse the whole assembly for embedded mapping files (e.g. Blog.hbm.xml etc.). In the last line of code I create the session factory. This factory instance I'll then use each time I need a connection to the database.

var cfg = new Configuration();

cfg.SetProperty("connection.provider", "NHibernate.Connection.DriverConnectionProvider");

cfg.SetProperty("connection.driver_class", "NHibernate.Driver.SQLite20Driver");

cfg.SetProperty("dialect", "NHibernate.Dialect.SQLiteDialect");

cfg.SetProperty("connection.connection_string", "Data Source=:memory:;Version=3;New=True;");

cfg.SetProperty("connection.release_mode", "on_close");

cfg.SetProperty("show_sql", "true");

cfg.AddAssembly(typeof (Blog).Assembly);

ISessionFactory factory = cfg.BuildSessionFactory();

In the above sample I'm using SqLite as my database and the connection string is configured such as that the database is in in-memory mode, that is the schema and the data is not written to disk but always kept in memory. I also have told NHibernate to output all SQL sent to the database to the console (for debugging purposes). This is the typical configuration I tend to use in my unit tests.

The app.config or web.config

This is an example of how to specify the database connection properties inside a web.config:

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

<configuration>

  <configSections>

    <section name="hibernate-configuration"

             type="NHibernate.Cfg.ConfigurationSectionHandler, NHibernate" />

  </configSections>

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

    <session-factory>

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

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

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

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

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

    </session-factory>

  </hibernate-configuration>

  <!-- other app specific config follows... -->

</configuration>

You first have to define a section for NHibernate in the configSections part of the config file. The content of the NHibernate section is then the same as when you use the hibernate.cfg.xml file (see below). In this sample I'm using an SQL Server 2005 database which is installed on the local machine. The connection to the SQL Server uses integrated security. I also have told NHibernate to output all SQL sent to the database to the console.

Now I can initialize NHibernate with the following code

var cfg = new Configuration();

cfg.AddAssembly(typeof (Product).Assembly);

ISessionFactory factory = cfg.BuildSessionFactory();

Note that the necessary configuration parameters are automatically picked up by NHibernate from the app.config or web.config file.

The hibernate.cfg.xml file

Below I present a typical configuration file. Again this sample assumes SqLite as my database.

<?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.SQLiteDialect</property>

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

    <property name="connection.connection_string">Data Source=:memory:;Version=3;New=True;</property>

    <property name="connection.release_mode">on_close</property>

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

  </session-factory>

</hibernate-configuration>

This file must be present in the same directory as the application that uses it. Then NHibernate can automatically pick it up when you initialize the framework.

var cfg = new Configuration();

cfg.Configure();

cfg.AddAssembly(typeof (Blog).Assembly);

ISessionFactory factory = cfg.BuildSessionFactory();

We have to instantiate a NHibernate Configuration object and call the method Configure. When doing this the default behavior is that NHibernate looks for a file called hibernate.cfg.xml in the application directory an opens it if available.

A custom XML file

The content of the file must be structured the same way as in the hibernate.cfg.xml presented above. But you can name the file however you want and you are also free to choose it's location. When you initialize NHibernate you have to provide the respective information about your configuration file.

You can pick a different XML configuration file using the following syntax

var cfg = new Configuration();

cfg.Configure(Path.Combine(AppDomain.CurrentDomain.BaseDirectory,"my_config_file.xml"));

cfg.AddAssembly(typeof(Product).Assembly);

ISessionFactory factory = cfg.BuildSessionFactory();

The method Configure accepts a parameter indicating the full path to my custom XML file.

Use a fluent interface to configure NHibernate

All the above samples are not really complicated but have the disadvantage that we have to deal with strings (configuration in code) or with XML. XML is not really nice to read and certainly not wrist friendly. Also there is no compile time error checking. Any typos introduced will only be detected during runtime.

Comes the fluent interface to the rescue. I can now configure NHibernate in a strongly typed fashion. Have a look at the following code

var cfg = new MyConfiguration()

    .ShowSql()

    .Driver<SQLite20Driver>()

    .Dialect<SQLiteDialect>()

    .ConnectionString.Is("Data Source=:memory:;Version=3;New=True;")

    .Raw("connection.release_mode", "on_close");

A few remarks to this code

no need to define a connection provider (it's always and has always bee NHibernate.Connection.DriverConnectionProvider and thus this is configured implicitly by the framework)
all commonly used parameters can be configured using strong typing
generic methods are used wherever flexibility is needed (e.g. the method .Driver<T>() where T represents the concrete driver you want to choose)
the method Raw can be used whenever we need to configure non-standard (that is database specific) parameters. In the sample above I define the connection release mode for the SqLite database.
The connection string can either be defined in place (as in the above sample) or

be retrieved from the appSection in the web.config or app.config file
.ConnectionString.FromAppSetting("MyConnectionString")
be retrieved from the connectionStrings section in the web.config or app.config file
.ConnectionString.FromConnectionStringWithKey("MyConnectionString")

There are other methods we can use to further configure NHibernate (e.g. UseOuterJoin, MaxFetchDepth and UseReflectionOptimizer)

Now I have to say some words to the MyConfiguration class used in the sample above... This class inherits from the PersistenceConfiguration class of the fluent interface framework and contains no code.

public class MyConfiguration : PersistenceConfiguration<MyConfiguration>

For some databases there are even pre-defined configuration classes that facilitate the job even further. For SqLite I can then write

var cfg = new SQLiteConfiguration()

    .InMemory()

    .DoNot.ShowSql();

Really nice! Please note also the DoNot... syntax to revert some boolean settings like ShowSql or UseOuterJoin, etc.

Now a complete sample how to configure and use NHibernate

var nhibernateConfig = new Configuration();

var cfg = new SQLiteConfiguration()

    .InMemory()

    .ConfigureProperties(nhibernateConfig);

var sessionSource = new SessionSource(cfg.Properties, new MyPersistenceModel());

using (var session = sessionSource.CreateSession())

    var product = new Product { Name = "Product 1", UnitPrice = 10.55m, Discontinued = false };

    session.Save(product);

First I instantiate an object of type NHibernate.Cfg.Configuration. I then instantiate an object of type SQLiteConfiguration which is defined in the mapping framework. With the ConfigureProperties method I tell this object to configure the NHibernate configuration object which I pass as a parameter. Then I instantiate a SessionSource object an pass it the properties of my SqLite configuration object as well as my persistence model. Last I use this session source to create a new session and insert a new product into the database. (Please refer to the previous articles of this series for a description of the persistence model).

Summary

Various methods exists how one can configure NHibernate. None of them is really complicated. But the new mapping framework facilitates the configuration even more and has the following advantages over the other methods

type safety (and thus also re-factor friendly)
good readability
intellisense support

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.

A fluent interface to NHibernate

NHibernate's Answers — Mon, 11 Aug 2008 22:26:38 GMT

Do you like NHibernate? Do you like XML? My answer would be yes for the former and no for the latter. But if you want to map your entities to the underlying database tables you have no other choice than use XML. Ok, you are right, we still have the possibility to use attributes for the mapping (e.g. by using Castle Active Record) but in this case we are "polluting" our nice domain objects with infrastructure related information which definitely does NOT belong into the domain model.

Here comes our salvation. We now have a third player in the field. As first published by Jeremy D. Miller and later on by others (James Gregory, Bobby Johnson, Zachariah Young, etc. ) we can map our domain objects by using a fluent interface which solves the following possible problems

Changing the property names of a domain model can break the NHibernate mapping
Changing the database fields can break the NHibernate mappings

and has the benefit of

we can write the mappings in plain old C#
the mapping is more expressive
the mapping is better testable

You can download the source code for the Fluent NHibernate project from here.

Sample

Let's make a quick sample. You can download it's source here.

In our domain model we have a Product class defined as follows

public class Product

    public virtual long Id { get; set; }

    public virtual string Name { get; set; }

    public virtual Decimal UnitPrice { get; set; }

    public virtual int UnitsOnStock { get; set; }

    public virtual bool Discontinued { get; set; }

This class we can now easily map to the underlying database with this code

public class ProductMap : ClassMap<Product>

    public ProductMap()

        Id(x => x.Id);

        Map(x => x.Name);

        Map(x => x.UnitPrice);

        Map(x => x.UnitsOnStock);

        Map(x => x.Discontinued);

Now let's write a quick test to see whether we can really e.g. add a new product to the underlying database. In our case the database used for tests is the SqlLite database.

Prerequisites

I have to write a helper class which will be my session source. The mapping framework already contains such a session source but its implementation does not fit my needs. Since it is not a complicate class I implement my own one. The session source class has to implement the interface ISessionSource also found in the mapping framework. Here is the code

public class MySessionSource : ISessionSource

    private readonly ISessionFactory _sessionFactory;

    private readonly Configuration _configuration;

    public MySessionSource(PersistenceModel model) : this(null, model)

    public MySessionSource(IDictionary<string, string> properties, PersistenceModel model)

        if(model == null) throw new ArgumentException("Model cannot be null!");

        _configuration = new Configuration();

        if (properties == null)

            _configuration.Configure();

        else

            _configuration.AddProperties(properties);

        Model = model;

        model.Configure(_configuration);

        _sessionFactory = _configuration.BuildSessionFactory();

    public PersistenceModel Model { get; private set; }

    public ISession CreateSession()

        return _sessionFactory.OpenSession();

    public void BuildSchema()

        var session = CreateSession();

        BuildSchema(session);

    public void BuildSchema(ISession session)

        var connection = session.Connection;

        var drops = _configuration.GenerateDropSchemaScript(_sessionFactory.Dialect);

        executeScripts(drops, connection);

        var scripts = _configuration.GenerateSchemaCreationScript(_sessionFactory.Dialect);

        executeScripts(scripts, connection);

    private static void executeScripts(string[] scripts, IDbConnection connection)

        foreach (var script in scripts)

            var command = connection.CreateCommand();

            command.CommandText = script;

            command.ExecuteNonQuery();

I have two overloaded constructors. I can either provide only the persistence model I use or pass the model and the necessary NHibernate configuration as dictionary of properties. In the former case the configuration is loaded from the usual hibernate.cfg.xml configuration file. The constructor then creates a new NHibernate configuration instance and uses the passed persistence model instance to feed the mapping information into the configuration instance.

The class also implements a method the create (or open) an new NHibernate session instance.

Finally we have a BuildSchema method which is overloaded. The second overload is needed when testing with SqlLite as database since when using this database in the in-memory mode (which we do in our unit tests) the database is destroyed whenever the session is closed. So, if I use a session instance to create the schema and then another for the test, then the latter does not have access to the database created by the former.

Base class for unit tests

I now write a base class for all unit test that I'll implement. This base class should be responsible for the (re-)creation of the database schema before each test runs. It should also open a new session object before each test which I can then use in my unit tests. Finally the base class should close an dispose the session after each test. Here is the code

public class FixtureBase

    private MySessionSource _source;

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

        _source = new MySessionSource(new TestModel());

        Session = _source.CreateSession();

        _source.BuildSchema(Session);

        CreateInitialData(Session);

        Session.Clear();

    protected virtual void After_each_test()

        Session.Close();

        Session.Dispose();

    protected virtual void CreateInitialData(ISession session)

Note that the SetUp and TearDown methods just delegate to protected virtual methods Before_each_test and After_each_test respectively. The latter two methods can be overridden in any child class. In the Before_each_test method I use the session source class to a) create a new session instance and b) (re-)build the database schema. A call to the virtual method CreateInitialData is executed and then the session is cleared. The CreateInitialData method can be used in the child classes to setup the respective context for the unit tests.

The After_each_test method just closes and disposes the session.

The first unit test

Finally we can write our first test and verify whether the mapping with the fluent interface really works. First we want to try to add a new Product to the database. With all the prerequisites in place this is now easy. See the code below

[TestFixture]

public class Product_Fixture : FixtureBase

    [Test]

    public void Can_add_product_to_database()

        var product = new Product

                              Name = "Apple",

                              UnitPrice = 0.25m,

                              UnitsOnStock = 1255,

                              Discontinued = false

};

        Session.Save(product);

        // Assertion

        Session.Flush();

        Session.Clear();

        var fromDb = Session.Get<Product>(product.Id);

        Assert.AreNotSame(product, fromDb);

        Assert.AreEqual(product.Name, fromDb.Name);

        Assert.AreEqual(product.UnitPrice, fromDb.UnitPrice);

        Assert.AreEqual(product.UnitsOnStock, fromDb.UnitsOnStock);

        Assert.AreEqual(product.Discontinued, fromDb.Discontinued);

We define a new test class which inherits from our base class FixtureBase. The we define the test which creates a new instance of type Product and populates the various properties with sample data. We then call the Save method of the session and pass the product as a parameter.

Then we flush and clear the session and reload the Product from database. We assert that it has really been loaded from the database and not just taken out of NHibernate's first level cache (to avoid that we have flushed and cleared the session). Then we assert that the values of the properties all match.

Unit test revisited

If we have a lot of entities then we potentially have lot's of repetitive code to implement just to unit test all of our entities as above. Hey but wait a minute. There is a "better" way provided by the mapping framework. We can use the PersistenceSpecification class to eliminate the repetitive work. Let's look how our code will be

[Test]

public void Can_add_product_to_database_revisited()

    new PersistenceSpecification<Product>(SessionSource)

        .CheckProperty(x=>x.Name, "Apple")

        .CheckProperty(x=>x.UnitPrice, 0.25m)

        .CheckProperty(x=>x.UnitsOnStock, 2345)

        .CheckProperty(x=>x.Discontinued, true);

That's a nice reduction in lines of code. No "noise" any more, just the essential is left.

Note: Unfortunately this second approach has a side effect which in my opinion is not nice! The entity must inherit from the base class Entity provided by the mapping framework. This introduces a dependency in the domain model (the domain model must reference the mapping framework) and also is against the principle of POCO (plain old C# object). Maybe I want to provide a different entity base class. Well there is some room for improvement left...

Summary

If you want a clean domain model free from pollution by mapping attributes you had to define the mapping between entities and the underlying database with XML documents. XML is not very wrist friendly and also not very readable. Now there is a third alternative to define the mapping of entities to database - the fluent NHibernate API. One can now define the mapping in C# with a nice and very readable code.

As always you can download the code for the sample here.

Enjoy

How to map a tree in NHibernate

NHibernate's Answers — Wed, 14 May 2008 22:19:37 GMT

Introduction

Lately there have been many questions regarding how to best map a tree structure in NHibernate. In this post I'll try to show you various techniques how one can deal with a tree structure.

The code for this sample you can get from here.

Domain Model

Let's define a very simple domain model for this sample. We have a single class called Equipment that has a parent of type Equipment and 0 to many children of type Equipment. The tree has a single root node. The root node is specific by the fact that it's property Parent is equal to null. On the other hand a tree has leaf nodes. A leaf node is defined to have no children.

You could as well replace the class Equipment by e.g. a Person class. The principles shown here would not change.

Where is my Aggregate?

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

Depending on our Use Cases or User Stories we can define our Aggregate either as

that is, the aggregate includes the equipment (which is the root) and its children.

Or we could define the Aggregate as follows

here only the equipment object is part of the aggregate (it is at the same time the root of the aggregate).

In the following I choose the former aggregate (equipment and children). This corresponds to the use case where I want to edit an equipment and its children in a single business transaction.

Note: Normally one defines a Repository for each Aggregate in the domain model.

Mapping

Let's have a look at the mapping for the Equipment class.

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

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

                   assembly="TreeStructure"

                   namespace="TreeStructure">

  <class name="Equipment">

    <id name="Id">

      <generator class="guid"/>

    </id>

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

    <many-to-one name="Parent" class="Equipment" column="ParentId" />

    <set name="Children" cascade="all-delete-orphan" >

      <key column="ParentId" foreign-key="fk_Equipment_ParentEquipment"/>

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

    </set>

  </class>

</hibernate-mapping>

The name property of the equipment must be defined and unique. The name can be at most 50 characters long.

The parent property is not mandatory (this is the default, i.e. not_null=false) since the root node has Parent equal to null.

I have defined the children collection as a Set, that is an unordered collection of unique objects. I have chosen cascade="all-delete-orphan" to instruct NHibernate that he automatically saves, updates or deletes the children of an equipment too when I save, update or delete the equipment. I also have defined that the foreign key constraint that will be defined on the database between the equipment and its parent has a friendly name (fk_Equipment_EquipmentParent).

Now I can write a unit test to check whether NHibernate can create the correct schema for me. In this sample I use a SQL Server 2005 database (the express edition is ok too) since later on I want to show some specific features only available in SQL Server. The code of the test is

[Test]

public void Can_generate_schema()

    var configuration = new Configuration();

    configuration.Configure();

    configuration.AddAssembly(typeof (Equipment).Assembly);

    // show the schema for debugging purposes

    new SchemaExport(configuration).Execute(true, false, false, false);

    // generate the schema in the database

    new SchemaExport(configuration).Execute(false, true, false, false);

This test runs successfully and generates the following output (SQL script)

if exists (select 1 from sys.objects

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

           AND parent_object_id = OBJECT_ID('Equipment'))

  alter table Equipment  drop constraint fk_Equipment_ParentEquipment

if exists (select * from dbo.sysobjects

           where id = object_id(N'Equipment')

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

  drop table Equipment

create table Equipment (

  Id UNIQUEIDENTIFIER not null,

  Name NVARCHAR(50) not null unique,

  ParentId UNIQUEIDENTIFIER null,

  primary key (Id)

alter table Equipment

add constraint fk_Equipment_ParentEquipment

foreign key (ParentId) references Equipment

The first part of the script drops the database objects if they are already there and in the second part of the script the table Equipment is generated as well as the foreign key constraint between the equipment and its parent. The create script for the table looks exactly like expected.

The Repository

A Repository is defined as "a mechanism for encapsulating storage, retrieval, and search behavior which emulates a collection of objects."

As said above, for each Aggregate in the domain model one defines a Repository. Since we only have one aggregate in our simple domain we also will have only one repository. Let us call it EquipmentRepository.

Now I want to be able to eager load the complete aggregate given the id of the aggregate root. I write the following unit test

[Test]

public void Can_load_aggregate_by_id()

    var equipmentId = ...;    // some id

    var equipment = _repository.GetAggregateById(equipmentId);

    Assert.IsNotNull(equipment);

    Assert.IsTrue(NHibernateUtil.IsInitialized(equipment.Parent));

    Assert.IsTrue(NHibernateUtil.IsInitialized(equipment.Children));

    Assert.AreEqual(3, equipment.Children.Count);

With this test I assert that a) I get an aggregate and b) the aggregate is fully populated. To check whether the aggregate is fully populated I use the NHibernateUtil utility class. The test assumes the existence of a equipment tree fragment in the database. Please refer to the project (here) for any details how I create this tree fragment in the SetUp of the test fixture.

A possibility to eager load an aggregate is by using a HQL query as below

public Equipment GetAggregateById(Guid equipmentId)

    using (var session = SessionManager.OpenSession())

        var sql = "from Equipment e" +

                  " left join fetch e.Parent p" +

                  " left join fetch e.Children c" +

                  " where e.Id = :id";

        var equipment = session.CreateQuery(sql)

            .SetGuid("id", equipmentId)

            .UniqueResult<Equipment>();

        return equipment;

I use left joins since either Parent can be null or the equipment has no children. The SessionManager class is a helper class which I use to provide me session objects. Please have a look at the project which you can find here for any details.

Finding the root aggregate is easy. We just have to look for an equipment whose parent is equal to null

public Equipment GetRootAggregate()

    using (var session = SessionManager.OpenSession())

        var sql = "from Equipment e" +

                  " left join fetch e.Children c" +

                  " where e.Parent is null";

        var equipment = session.CreateQuery(sql)

            .UniqueResult<Equipment>();

        return equipment;

Now some times we want to find all leaf nodes of the tree. Remember that a leaf node has by definition no children. We could use the following code for this

public ICollection<Equipment> GetAllLeafNodes()

    using (var session = SessionManager.OpenSession())

        var sql = "from Equipment e" +

                  " left join fetch e.Parent p" +

                  " where e.Children.size = 0";

        var leafs = session.CreateQuery(sql)

            .List<Equipment>();

        return leafs;

here we use the handy size function for collections provided by HQL. Note that this method delivers all leaf nodes of the tree. To only select the leaf nodes of a sub-tree starting at a given equipment node is trivial now and I leave for you as an exercise.

Eager load ancestors and descendants

To eager load all ancestors or descendants of a given equipment node we have to use native TSQL since HQL (as well as the criteria API) does not provide a generic way of doing it. Fortunately SQL server 2005 provides us the means to achieve the desired result. We have to construct a hierarchical query as below

public ICollection<Equipment> GetAllDescendantsOfEquipment(Guid equipmentId)

    using (var session = SessionManager.OpenSession())

        var sql = "with Hierachy(Id, Name, ParentId, Level)" +

                  " as" +

                  " (" +

                  "   select Id, Name, ParentId, 0 as Level" +

                  "   from Equipment e" +

                  "   where e.Id = :id" +

                  "  union all" +

                  "   select e.Id, e.Name, e.ParentId, eh.Level + 1" +

                  "   from Equipment e" +

                  "   inner join Hierachy eh" +

                  "      on e.ParentId = eh.Id" +

                  " )" +

                  " select Id, Name, ParentId" +

                  " from Hierachy" +

                  " where Level > 0";

        var list = session.CreateSQLQuery(sql)

            .AddEntity(typeof(Equipment))

            .SetGuid("id", equipmentId)

            .List<Equipment>();

        return list;

The last where statement in the SQL assures that the given equipment is not included in the list of descendants.

Analogous we can get the list of ancestors of a given equipment node

public ICollection<Equipment> GetAllAncestorsOfEquipment(Guid equipmentId)

    using (var session = SessionManager.OpenSession())

        var sql = "with Hierachy(Id, Name, ParentId, Level)" +

                  " as" +

                  " (" +

                  "   select Id, Name, ParentId, 0 as Level" +

                  "   from Equipment e" +

                  "   where e.Id = :id" +

                  "  union all" +

                  "   select e.Id, e.Name, e.ParentId, eh.Level + 1" +

                  "   from Equipment e" +

                  "   inner join Hierachy eh" +

                  "      on e.Id = eh.ParentId" +

                  " )" +

                  " select Id, Name, ParentId" +

                  " from Hierachy" +

                  " where Level > 0";

        var list = session.CreateSQLQuery(sql)

            .AddEntity(typeof(Equipment))

            .SetGuid("id", equipmentId)

            .List<Equipment>();

        return list;

Note that we had just to adjust the inner join between the Equipment table and the Hierarchy (temp) table. Again the last where statement in the SQL assures that the given equipment is not included in the list of ancestors.

An alternative approach

We can also choose another approach for the tree problem. The solution I want to show works for any database even if it does not support hierarchical queries. This time our simple domain model looks as follows

Here we have a node object which can have a parent and a collection of children. Additionally we have defined the two collections descendants and ancestors which contain all descendants (children, children of the children and so on) and all parents of the given node.

The code for the Node class is given by

public class Node

    public Guid Id { get; set; }

    public string Name { get; set; }

    public Node Parent { get; set; }

    public ISet<Node> Children { get; set; }

    public ISet<Node> Ancestors { get; set; }

    public ISet<Node> Descendants { get; set; }

The mapping for the node is defined as

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

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

                   assembly="TreeStructure"

                   namespace="TreeStructure">

  <class name="Node">

    <id name="Id">

      <generator class="guid"/>

    </id>

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

    <many-to-one name="Parent" class="Node" column="ParentId" />

    <set name="Children" inverse="true" cascade="all" >

      <key column="ParentId" foreign-key="fk_Node_ParentNode"/>

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

    </set>

    <set name="Descendants" table="NodeHierarchy" inverse="true" >

      <key column="ParentId" foreign-key="fk_HierarchyNode_ParentNode"/>

      <many-to-many class="Node" column="ChildId" foreign-key="fk_HierarchyNode_ChildNode" />

    </set>

    <set name="Ancestors" table="NodeHierarchy" >

      <key column="ChildId" />

      <many-to-many class="Node" column="ParentId" />

    </set>

  </class>

</hibernate-mapping>

Note that we define the descendants and ancestors of a node as a many-to-many relation in the database. So the SQL script created by the SchemaExport class of NHibernate is

if exists (select 1 from sys.objects

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

           AND parent_object_id = OBJECT_ID('Node'))

  alter table Node  drop constraint fk_Node_ParentNode

if exists (select 1 from sys.objects

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

           AND parent_object_id = OBJECT_ID('NodeHierarchy'))

  alter table NodeHierarchy  drop constraint fk_HierarchyNode_ChildNode

if exists (select 1 from sys.objects

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

           AND parent_object_id = OBJECT_ID('NodeHierarchy'))

  alter table NodeHierarchy  drop constraint fk_HierarchyNode_ParentNode

if exists (select * from dbo.sysobjects

           where id = object_id(N'Node')

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

  drop table Node

if exists (select * from dbo.sysobjects

           where id = object_id(N'NodeHierarchy')

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

  drop table NodeHierarchy

create table Node

  Id UNIQUEIDENTIFIER not null,

  Name NVARCHAR(50) not null unique,

  ParentId UNIQUEIDENTIFIER null,

  primary key (Id))

create table NodeHierarchy

  ParentId UNIQUEIDENTIFIER not null,

  ChildId UNIQUEIDENTIFIER not null,

  primary key (ParentId, ChildId)

alter table Node add constraint fk_Node_ParentNode

foreign key (ParentId) references Node

alter table NodeHierarchy add constraint fk_HierarchyNode_ChildNode

foreign key (ChildId) references Node

alter table NodeHierarchy add constraint fk_HierarchyNode_ParentNode

foreign key (ParentId) references Node

we can see here that the script creates a n-to-m mapping table called NodeHierarchy as well as the necessary foreign keys between this table and the table Node.

To account for this special situation I define an AddChild method on the Node class

public virtual void AddChild(Node childNode)

    Children.Add(childNode);

    childNode.Parent = this;

    childNode.Ancestors.AddAll(this.Ancestors);

    childNode.Ancestors.Add(this);

    this.Descendants.Add(childNode);

This method is responsible for the book-keeping when adding a new child node to an existing node.

If I now want to eager load a node given by its id with all collections populated then I can use code similar to this one

public Node GetAggregateById(Guid nodeId)

    using (var session = SessionManager.OpenSession())

        var sql = "from Node e" +

                  " left join fetch e.Parent p" +

                  " left join fetch e.Children c" +

                  " where e.Id = :id";

        var node = session.CreateQuery(sql)

            .SetGuid("id", nodeId)

            .UniqueResult<Node>();

        // load the ancestors

        var sql2 = "from Node e" +

                  " left join fetch e.Ancestors a" +

                  " where e.Id = :id";

        node = session.CreateQuery(sql2)

            .SetGuid("id", nodeId)

            .UniqueResult<Node>();

        // load the descendants

        var sql3 = "from Node e" +

                  " left join fetch e.Descendants d" +

                  " where e.Id = :id";

        node = session.CreateQuery(sql3)

            .SetGuid("id", nodeId)

            .UniqueResult<Node>();

        return node;

For an in depth discussion of how to eager load a complex object graph please refer to this post.

Note that depending on the depth of the tree you should eventually avoid to eager load the descendants collection since this collection can become huge... In may sample I assume a tree with limited depth (e.g. less than 5) and a limited amount of children per node (e.g. less than 5).

Enjoy

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