A Subtext Community

Dictionary Adapter 1.1 Released

Craig — Sun, 22 Nov 2009 13:42:28 GMT

It can be downloaded at Sourceforge.

Article series on NHibernate and Fluent NHibernate – Part 3

NHibernate's Answers — Tue, 01 Sep 2009 19: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 03: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.

From a data centric to a domain driven design

NHibernate's Answers — Tue, 03 Feb 2009 08:08:04 GMT

Introduction

Is NHibernate as an ORM tool or framework better suited for a data centric application or for an application developed by applying domain driven design? Well, that should NOT be the question here. NHibernate can serve equally well both approaches. But which one would you choose?

A data centric design

The modeling of the data structure is the center piece of this kind of design. The database is the most important part of our architecture. The DBA plays a very important role.

Data Layer

That's ok for simple problems like managing a collection of customer addresses and nothing more. But it miserably fails as soon as we get into more complicated business. Let's e.g. assume that all of the sudden our address management tool needs to be extended to a full fledged CRM solution.

Possible Problems

Management night mare with possibly hundreds of stored procedures
No clear structure in the data. It seems that each entity (or table) has more or less the same importance
We concentrate to much on the data and not on the business processes and/or functionality

Our principle questions are focused around

Do we have all data that we need (tables and columns there in)?
Did we normalize the data sufficiently?

Instead of

What do we want to automate and why do we want to do so?
How can we measure that we have achieved what we want (criterions!)?

User Interface

On the other hand we concentrate too much on e.g. data binding on the GUI and how to best present (too much) data on the screen for the user.

A sample taken from a real application

This is a sample from a real application (although simplified). At the beginning there was a data model (ERD) which was elaborate by two persons in a "heroic" several men month long effort. Let's show an extract of this data model

It might be clear after staring a while on the ERD that we want to manage employees and their assigned tasks. It's also clear that an employee is a person and that it has an address and two different titles. Further on each employee can have an associated photo. Finally we see that the data regarding an employee is split into two different tables [Employee] and [EmployeeDetails] obviously for scalability reasons. Since photos can become very large (compared to the rest of the data) they are kept in a separate table [EmployeePhoto] which possibly resides in separate database file on another disk.

Stored Procedures

Traditionally Microsoft has suggested us to write stored procedures to access and manipulate the data in the various tables. So usually one would write the following kind of stored procedures for each table (here as an example we use the Address table)

usp_AddressInsert(...)
usp_AddressUpdate(...)
usp_AddressDelet(...)
usp_AddressSelectById(...)

if we look at a table like [Employee] we would probably have many more stored procedures representing various querying scenarios, e.g.

usp_EmployeeSelectAll()
usp_EmployeeSelectActive()
usp_EmployeeSelectByDepartment(...)
etc.

Data access objects (DAO)

Now having the stored procedures in place we write a DAO for each table to produce a object oriented wrapper around the database (the business object should not know anything about the database). We thus will have the following class for e.g. the Address table

public class AddressDAO

    public void Insert(...) {...}

    public void Update(...) {...}

    public void Delete(...) {...}

    public Address GetById(...) {...}

A domain driven design

The modeling of the business processes is the center piece of this kind of design. The so called domain model is the center of our architecture. The domain expert (a representative of the customer with deep knowledge of the domain for which the application is planned) plays a very important role during all the development phases (analysis, design and implementation). The development often is more evolutionary and goes in "cycles". It's often a so called agile application development.

Distilling the ubiquitous language

Together with the domain expert we want to find and use the ubiquitous language which describes best the business we are talking of. In our simple case this ubiquitous language is "hidden" in the following fragments of a discussion

"... So we want to keep track of our employees. Especially we want to know where the employee lives and how we can contact him at home as well as in the office. To better identify an employee (and for other usage as well, e.g. to apply for a business travel visa) we want to have a photo of him in the system. ..."

"... yeah, each employee has a business card of course where he's title and job description is marked... thus I guess we have to store this information - we call it title - in the system as well since the relevant text for a new business card shall be generated automatically... By the way, the titles should be available in German and in English. ..."

"... each employee has a list of tasks to carry out during his daily work. This list should be maintained and updated by the system. Tasks can be produced automatically by the fact that some event occurred, e.g. there is a redemption of a bond. Other tasks are a result of a contact with a customer. And last but not least the group manager can define some tasks for an employee or a group of employees. ..."

"... as an employee I want to see a list of my open tasks. I want to also see if tasks are over due and which tasks will occur in the near future. ... I also want to see the priority of each task and what it's current status is. ..."

I have marked in bold the key terms for our simplified domain. These nouns will be good candidates for entities or value objects.

A first model of our domain

We can immediately locate two hot candidates for entities. These are employee and task. We also immediately grasp that a employee might have a list of associated tasks. Every thing else is just detail for the moment. So let's draw a nice diagram

Refining the model

Up to now our model does not contain much structure and business logic. Let's start with the question how we could better model the employee entity. At the moment the employee contains just a bunch of properties and no clear internal structure is visible. To find out e.g. whether an instance of employee is in a valid state is rather cumbersome. Comes the value object to the rescue! What about this?

In the above model I have tried to group properties which belong together. Let's take as an example the address. A valid address is represented by an address line, a postal code and a city (in the real world we would also have a link to a country there). An address line alone does not really make sense. Again: we can validate an address only if we have the whole group of relevant properties at hand. On the other hand it does not really make sense to put the address validation logic into the employee entity itself. Thus the extraction of a new class - the address class - is certainly an improvement. In the terminology of DDD the address is now a value object. It has no identity by itself and belongs to and characterizes an entity (the employee). A value object can be recreated any time by just copying the content of its properties. Further on a value object is immutable. Once created it cannot be changed. Two instances of a value object are equal if the content of their fields match. A value object can never be in an invalid state.

Let's have a look at the code of the address class then

public class Address : IEquatable<Address>

    public Address(string addressLine1, string addressLine2, string postalCode, string city)

        if(addressLine1==null)

            throw new ArgumentException("Address line 1 cannot be undefined.");

        if(postalCode==null)

            throw new ArgumentException("Postal code cannot be undefined.");

        if(city==null)

            throw new ArgumentException("City cannot be undefined.");

        AddressLine1 = addressLine1;

        AddressLine2 = addressLine2;

        PostalCode = postalCode;

        City = city;

    public string AddressLine1 { get; private set; }

    public string AddressLine2 { get; private set; }

    public string PostalCode { get; private set; }

    public string City { get; private set; }

    public bool Equals(Address other)

        if(other==null) return false;

        return AddressLine1 == other.AddressLine1 &&

               ((AddressLine2==null && other.AddressLine2==null) ||

               (AddressLine2 != null && AddressLine2 == other.AddressLine2)) &&

               PostalCode == other.PostalCode &&

               City == other.City;

    public override bool Equals(object obj)

        return Equals(obj as Address);

    public override int GetHashCode()

        return string.Format("{0}|{1}|{2}|{3}",

            AddressLine1, AddressLine2, PostalCode, City).GetHashCode();

Note that all properties are read-only to account for the fact that a value object is immutable. Thus an address can only be constructed through its constructor. Note also that I have implemented the interface IEquatable<T> and overridden the two methods Equals and GetHashCode to be able to compare two instances of type Address for equality. Pay attention on the special treatment of the AddressLine2 property in the Equal method. It's the only property that can be null. All others properties cannot be null. This requirement is enforced in the constructor where I check each non-nullable parameter and throw an exception if the requirement is not met.

The above code is a typical sample of how one would implement a value object.

I think it makes sense that also the Employee entity is always in a valid state. A possible solution how to achieve that is to also make all properties of the entity read-only and force any modification to use dedicated methods. I would also provide a constructor which expects all mandatory values, e.g.

public Employee(Name name, Title title1, Address homeAddress, Address officeAddress,

    Contact homeContact, Contact officeContact)

    if (name == null)

        throw new ArgumentException("Name of employee cannot be undefined.");

    if (title1 == null)

        throw new ArgumentException("Title 1 of employee cannot be undefined.");

    if (homeAddress == null)

        throw new ArgumentException("Home address of employee cannot be undefined.");

    if (officeAddress == null)

        throw new ArgumentException("Office address of employee cannot be undefined.");

    if (homeContact == null)

        throw new ArgumentException("Home contact of employee cannot be undefined.");

    if (officeContact == null)

        throw new ArgumentException("Office contact of employee cannot be undefined.");

    Name = name;

    Title1 = title1;

    HomeAddress = homeAddress;

    OfficeAddress = officeAddress;

    HomeContact = homeContact;

    OfficeContact = officeContact;

Once an employee exists in the system and I want to e.g. change its home address then I use a dedicated method of the employee class

public void ChangeHomeAddress(Address newHomeAddress)

    if (newHomeAddress == null)

        throw new ArgumentException("Cannot change home address of employee to undefined.");

    HomeAddress = newHomeAddress;

This method again asserts that after the updating the employee instance is again in a valid state.

Summary

For me it's obvious that the domain driven approach is definitely the better way to go when implementing an application which models complex business processes. A more data centric approach may still make sense when dealing with a forms-over-data type application which does not involve complex business processes. But even when implementing a data centric application I would certainly never ever use stored procedures to access the data. I would instead use an ORM tool like NHibernate to access the database. The only exception I can see for justifying the use of stored procedures is in reporting scenarios where some massive data mapping, filtering and/or aggregation might be needed which is best done directly on the database server (in-process for maximum speed).

Enjoy

I'm a "Los Techies" member now

NHibernate's Answers — Wed, 21 Jan 2009 05:30:58 GMT

I just wanted to inform you that I have been invited to be a member of Los Techies which is a big honor for me.

If you like my posts then you might as well have a look at my blog at LosTechies. There I'll publish posts that do not necessarily have anything to do with NHibernate. To start with I have posted an article about the single responsibility principle (SRP) which I personally consider to be one of the most important principles for my daily development!

Don't be afraid, I'll continue to publish NHibernate related articles in this blog. So keep tuned.

Type analyzer - Interesting findings

NHibernate's Answers — Mon, 01 Dec 2008 01:39:14 GMT

When reading this post from Ayende I was getting curious what this site would tell about my blogging style here. The result is amusing me a lot.

INTJ - The Scientists

The long-range thinking and individualistic type. They are especially good at looking at almost anything and figuring out a way of improving it - often with a highly creative and imaginative touch. They are intellectually curious and daring, but might be physically hesitant to try new things.
The Scientists enjoy theoretical work that allows them to use their strong minds and bold creativity. Since they tend to be so abstract and theoretical in their communication they often have a problem communicating their visions to other people and need to learn patience and use concrete examples. Since they are extremely good at concentrating they often have no trouble working alone.

I would be very pleased if you could provide some feedback about what you are thinking of this findings... Especially interesting is the question whether

I am too abstract or theoretical
I can communicate my visions to you
My examples are concrete enough

Linq to NHibernate

NHibernate's Answers — Wed, 26 Nov 2008 09: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

Legacy DB and one-to-one relations

NHibernate's Answers — Wed, 19 Nov 2008 02:17:35 GMT

When dealing with a legacy database one often encounters the situation that the database schema defines one-to-one relations between two entities. A typical example might be the following schema fragment

with a one-to-one relation between person and address, that is: each person can have an address and an address can only belong to a single person. To guarantee that a single person can only have zero or one address the foreign key column PersonId in the Address table is set to be unique.

Such a construct is not straight forward to map in NHibernate! I want to show you one possible solution. The solution works but is not free from certain hick-ups! Let's first model the domain

The domain model

the code for the above model is straight forward. Nothing magic

public class Person

    public virtual int Id { get; set; }

    public virtual string FirstName { get; set; }

    public virtual string LastName { get; set; }

    public virtual Address Address { get; private set; }

    public virtual void AssignAddress(Address address)

        Address = address;

        address.Owner = this;

public class Address

    public virtual int Id { get; set; }

    public virtual string AddressLine1 { get; set; }

    public virtual string AddressLine2 { get; set; }

    public virtual string PostalCode { get; set; }

    public virtual string City { get; set; }

    public virtual Person Owner { get; set; }

Note that I have defined the setter method of the Address property in the Person entity as private such as that the consumer of the code is forced to use the AssignAddress method which sets up the bi-directional relation.

The mapping

And now we try to find a working mapping. I use the Fluent NHibernate framework for the mapping (please refer to my previous posts for an introduction to this framework: part 1, part 2, part 3, part 4)

public class PersonMapper : ClassMap<Person>

    public PersonMapper()

        LazyLoad();

        Id(x => x.Id);

        Map(x => x.FirstName);

        Map(x => x.LastName);

        HasOne(x => x.Address)

            .PropertyRef(p => p.Owner)

            .Cascade.All()

            .FetchType.Join();

public class AddressMapper : ClassMap<Address>

    public AddressMapper()

        LazyLoad();

        Id(x => x.Id);

        Map(x => x.AddressLine1);

        Map(x => x.AddressLine2);

        Map(x => x.PostalCode);

        Map(x => x.City);

        References(x => x.Owner)

            .WithUniqueConstraint()

            .TheColumnNameIs("PersonId")

            .LazyLoad()

            .Cascade.None();

Unit Tests

What does the above mapping derive as database schema? Let's implement a test. First I have to define what is my model (or: where are my mappings to be found)

public class TestModel : PersistenceModel

    public TestModel()

        addMappingsFromAssembly(typeof(Person).Assembly);

I then use the following code to generate the schema

[TestFixture]

public class when_creating_the_schema

    [SetUp]

    protected void Context()

        var model = new TestModel();

        var config = new Configuration();

        config.Configure();

        model.Configure(config);

        var factory = config.BuildSessionFactory();

        var session = factory.OpenSession();

        new SchemaExport(config).Execute(true, false, false, false, session.Connection, null);

    [Test]

    public void smoke_test()

        true.ShouldBeTrue();

when using an SQLite database (in-memory mode) the output generated by the smoke test is

let me reformat the create table scripts a little bit

create table [Person] (

  Id  integer,

  LastName TEXT,

  FirstName TEXT,

  primary key (Id))

create table [Address] (

  Id  integer,

  AddressLine1 TEXT,

  AddressLine2 TEXT,

  PostalCode TEXT,

  City TEXT,

  PersonId INTEGER unique,

  primary key (Id))

we can clearly see that the schema created from the model is indeed equal to the schema in the legacy database. Especially note that the PersonId foreign key in the Address table is set to be unique. Now that is a good start...!

Let's see how the creation of a new person with an associated address works (if ever). I have implemented the following unit test

[TestFixture]

public class when_adding_a_new_person_with_an_address : Person_Fixture

    private Address address;

    private Person person;

    protected override void Context()

        base.Context();

        address = new Address

                          AddressLine1 = "Some Street 1",

                          PostalCode = "8000",

                          City = "Zurich"

};

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

        person.AssignAddress(address);

        Session.Save(person);

        Session.Flush();

        Session.Clear();

    [Test]

    public void smoke_test()

        true.ShouldBeTrue();

in the context I create a new person entity and assign it a new address. Then I save the person, flush and clear the session. The smoke test just verifies that the context can be set up without throwing an exception. Let's run the test and analyze the output

and indeed this works as expected. First a person record is created and the the associated address is created.

Now let's have a look what happens when we query for this person. I add this test to the above test class

[Test]

public void should_add_person_to_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 first line I load the person entity which I have previously created from database. I then assert that the entity does indeed exist and has the expected properties. The following test output is generated

The interesting part is the one outlined by the red rectangle. When I load a person two select statements are generated. One to load the person record and the second to load its associated address.

Problems with this implementation

When loading a single person entity this is no problem but it starts to be a problem when I try to load a list of persons, as I do in the following test

public void can_load_all_persons()

    var list = Session.CreateQuery("from Person").List<Person>();

the output generated is

In this test I have 3 persons (each having an address) in the database. The problem is that although only one select statement is generated for the Person table there are 3 select statements for loading the corresponding addresses. We have a typical select (n+1) problem which is BAD.

A possible solution to avoid the select n+1 problem

A possible solution to this problem is shown below

[Test]

public void can_load_all_persons_revisited()

    var list = Session.CreateQuery("select p.Id, p.LastName from Person p").List();

here I explicitly select the fields I want to retrieve from database. And indeed the result of the test is only one select statement

We can use this method when we need a lookup list with all or some persons in the database.

Code

The code accompanying this post can be found here.

Summary

I have shown a possible solution how one can map a one-to-one relation implied by a pre-existing legacy database with NHibernate. For the mapping I have used the Fluent NHibernate framework. There is a select (n+1) problem with this implementation. But this problem can be avoided by using customized queries.

Enjoy.

Lazy loading BLOBS and the like in NHibernate

NHibernate's Answers — Mon, 17 Nov 2008 04: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