DDD

From a data centric to a domain driven design

NHibernate's Answers — Tue, 03 Feb 2009 16: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

The Repository Pattern

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

Introduction

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

Table data gateway
Row data gateway
Active record
Data mapper

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

What is a Repository

Martin Fowler writes:

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

Implementation

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

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

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

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

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

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

public interface IOrderRepository

    Order GetById(int id);

    void Add(Order order);

    void Remove(Order order);

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

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

public interface IProductRepository

    Product GetById(int id);

    void Add(Product product);

    void Remove(Product product);

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

public interface IRepository<T>

    T GetById(int id);

    void Add(T entity);

    void Remove(T entity);

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

public interface IOrderRepository : IRepository<Order> { }

public interface IProductRepository : IRepository<Product> { }

A fake repository

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

public class Product

    public virtual int Id { get; set; }

    public virtual string Name { get; set; }

    public virtual int ReorderLevel { get; set; }

    public virtual bool Discontinued { get; set; }

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

public class ProductRepositoryFake : IProductRepository

    private readonly Dictionary<int, Product> dictionary;

    public ProductRepositoryFake()

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

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

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

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

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

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

    public Product GetById(int id)

        return dictionary[id];

    public void Add(Product product)

        dictionary.Add(product.Id, product);

    public void Remove(Product product)

        dictionary.Remove(product.Id);

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

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

[TestFixture]

public class FakeRepositoryTester

    private IProductRepository repository;

    [SetUp]

    public void SetupContext()

        repository = new ProductRepositoryFake();

    [Test]

    public void can_load_a_product_by_its_id_from_the_repository()

        var product = repository.GetById(2);

        product.ShouldNotBeNull();

        product.Id.ShouldEqual(2);

    [Test]

    public void can_add_a_new_product_to_the_repository()

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

        // let's try to load this new product

        var product = repository.GetById(99);

        product.Id.ShouldEqual(99);

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

    [Test]

    public void can_remove_an_existing_product_from_the_repository()

        var product = repository.GetById(1);

        repository.Remove(product);

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

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

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

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

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

An implementation for NHibernate

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

public class SessionProvider

    private static Configuration configuration;

    private static ISessionFactory sessionFactory;

    public static Configuration Configuration

get

            if(configuration == null)

                configuration = new Configuration();

                configuration.Configure();                              // A

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

            return configuration;

    public static ISessionFactory SessionFactory

get

            if (sessionFactory == null)

                sessionFactory = Configuration.BuildSessionFactory();

            return sessionFactory;

    private SessionProvider()

{ }

    public static ISession GetSession()

        return SessionFactory.OpenSession();

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

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

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

public class ProductRepositoryNH : IProductRepository

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

    public Product GetById(int id)

        using (var session = GetSession())

            return session.Get<Product>(id);

    public void Add(Product product)

        using (var session = GetSession())

            session.Save(product);

    public void Remove(Product product)

        using (var session = GetSession())

            session.Delete(product);

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

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

The Unit of Work to the rescue

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

public class ProductRepository : IProductRepository

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

    public Product GetById(int id)

        return Session.Get<Product>(id);

    public void Add(Product product)

        Session.Save(product);

    public void Remove(Product product)

        Session.Delete(product);

Unit Tests

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

public class RepositoryFixtureBase<T>

    [TestFixtureSetUp]

    public void TestFixtureSetup()

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

    [SetUp]

    public void SetupContext()

        UnitOfWork.Start();

        new SchemaExport(UnitOfWork.Configuration)

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

        Context();

    [TearDown]

    public void TearDownContext()

        UnitOfWork.Current.TransactionalFlush();

        UnitOfWork.Current.Dispose();

    protected virtual void Context() { }

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

[TestFixture]

public class ProductRepository_Tester : RepositoryFixtureBase<Product>

    private IProductRepository repository;

    private Product[] products;

    protected override void Context()

        products = new[]

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

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

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

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

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

};

        foreach (var product in products)

            UnitOfWork.CurrentSession.Save(product);

        UnitOfWork.CurrentSession.Flush();

        UnitOfWork.CurrentSession.Clear();

        repository = new ProductRepository();

    [Test]

    public void can_load_product()

        var p = repository.GetById(2);

        p.ShouldNotBeNull();

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

    [Test]

    public void can_add_a_product_to_the_repository()

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

        UnitOfWork.CurrentSession.Flush();

        UnitOfWork.CurrentSession.Clear();

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

        prod.ShouldNotBeNull();

    [Test]

    public void can_remove_product_from_repository()

        repository.Remove(products[2]);

        UnitOfWork.CurrentSession.Flush();

        UnitOfWork.CurrentSession.Clear();

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

        prod.ShouldBeNull();

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

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

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

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

A generic base repository

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

public class Repository<T> : IRepository<T>

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

    public T GetById(int id)

        return Session.Get<T>(id);

    public ICollection<T> FindAll()

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

    public void Add(T product)

        Session.Save(product);

    public void Remove(T product)

        Session.Delete(product);

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

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

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

Let's take this as an example

public interface IProductRepository : IRepository<Product>

    ICollection<Product> FindAllDiscontinuedProducts();

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

public class ProductRepository : Repository<Product>, IProductRepository

    public ICollection<Product> FindAllDiscontinuedProducts()

        return Session.CreateCriteria(typeof (Product))

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

            .List<Product>();

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

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

public void can_load_all_discontinued_products()

    var discontinuedProducts = repository.FindAllDiscontinuedProducts();

    discontinuedProducts.Count.ShouldBeGreaterThan(0);

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

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

Code

The code to this post can be found here.

Summary

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

Enjoy

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