Firstly, lets look at simplified description of the problem. Those using MySQL have the luxury of limit, which makes paging data sets a breeze, but in SQL Server(and Oracle) things get a bit more “tricky”. The trick is to count the rows on the result set, using RowCount over something, and mix that in with a sub query, but there is a problem with nHibernate T-SQL 2005 Dialect. The RowCount was being used on the sub-query, and not the parent query. Now that I had discovered the problem.

“ROW_NUMBER() OVER(ORDER BY CURRENT_TIMESTAMP) as __hibernate_sort_row” is in the wrong place!

After some research, I found that other people were having this problem too. Marcin Daczkowski has an excellent work-around, that he blogged about, he also describes the problem with some NH generated SQL examples, I won’t repeat myself here, so have a look at his post if you are not sure and check his bug report here.

I found a another solution here too- not sure this one works though, ultimately I had to come up with a solution that suited my project.

There are some reasons why I can’t use Marcin Daczkowski solution.

– Firstly, it does not look like the guys at nHibernate be able to release the patched version of nHibernate any time soon,I guess they are very busy working hard on version 3.0! Can’t wait for that realease! see the comments here.

– Secondly, if I build my own version of nHibernate, I will need to also rebuild all my dependencies, linking them with Marcins patched version. That means FluentNHibernate needs to be rebuilt, NHibernate.Caches.SysCache needs to be rebuilt, NHibernate.ByteCode.Castle needs to be rebuilt, you get the picture?

So after some thought and source code investigation, I came up with the idea of making a customised Dialect, and just use Darcins patched files. Now, I don’t need to build a patched version of my all my open source dependencies, as I have my own SQL dialect set up in the fluent configuration.


_sessionFactory = Fluently.Configure()
      .Database(MsSqlConfiguration
      .MsSql2008
      .ConnectionString(connectionString)
      .CurrentSessionContext("web")
      .Dialect(CustomSQL2008Dialect)
)


My Dialect classes are set up like this:


public class CustomSQL2008Dialect: CustomSQL2005Dialect {
      public GWMsSql2008Dialect () {
            // Duplicate of the contents of MsSsql2008Dialect constructor goes here
      }
}

public class CustomSQL2005Dialect: MsSql2000Dialect {
      // the contents Darcins MsSql2005Dialect file goes here.
      // MsSql2005Dialect at NHibernate JIRA
}


Luckily, I have unit tests set up for all my repository methods, and after seeing the green bar in NUnit, I was more than satisfied with the custom dialect. I hope the guys at NHibernate manage to get things working in their next release, keep up the good work guys! And a special thanks to
to Darcin, for writing the patch.

Here is a copy the Custom Sql 2008 Dialect.

FNH extends NHibernate, and automagically generates XML mapping files for your objects. Unfortunately, to get stored procedures to work, you need to take a step backwards, and create good old fashioned hbm.xml files, doing the mappings manually.

Firstly , let us look at the results of the stored procedure that we want to map.

The class that will use this data is called lookup.

The code for this class is:

 
This object will be used to populate a simple drop down list, so that a user can select their county.

When I started using FluentHNibernate, I wanted to totally avoid using XML mappings, so I skipped chapters 3 and 6 of Hibernate in Action. My first mistake! So for those attempting this, it may be worth your while understanding Hibernate mappings before you proceed. (You may also ask why I have the Java Book and my code is in C#, that is because I am quite used to working in different programming languages, so those who prefer examples in .Net examples check NHibernate in Action.)

Let’s move on to creating the mapping file.

IMPORTANT: When you add the mapping file to your project, make sure you set the Build Action to Embedded Resource!

I have created a Lookup.hbm.xml file, and the source is below:

To put it quite simply, lines 5 to 13 map my Lookup class to the columns in the stored procedure, while lines 16 to 20 map the results from the stored procedure my lookup class. Line 22 names the stored procedure. I am not sure if this is the best way to achieve the mappings, so any feedback would be appreciated.

Once your object is nicely mapped, you then need to update your fluent configuration. All you need to do is tell FNH to load hbmMappings from the current assembly. See the snippet below:

To retrieve the list of lookups, I do the following, which populates my results variable with a list of all my lookups.

And that is it, the results variable now contains the list of lookups that I can use to populate my list control.

Okay, maybe you haven’t seen this screen in particular but apart from the troubleshooting tips you should have seen it.

Few days ago I have discovered the Null object pattern (NOP) and its usefulness. Kick me, punch me or even stone me to death cause I haven’t known it so far :) Still I would like to write a quick note about it as not everyone might be aware of it.

If it’s possible for a variable to be null, you have to remember to surround it with null test code so you’ll do the right thing if a null is present. Often the right thing is same in many contexts, so you end up writing similar code in lots of places – committing the sin of code duplication. – Martin Fowler

What does that exactly mean? It means the following:

if (Product.Creator == null) {

    Debug.WriteLine("unknown");

} else {

    Debug.WriteLine(Product.Creator);

}

If we have a Creator property of a Product and it may be null (to indicate an unknown creator) we need to do a null check everywhere we wanna display the creator. I would call it boring code duplication. And that’s where the NOP joins our game.

Let’s create a user instance which represents the actual “unknown” user so we can get rid of the odd null check. Best to achieve that is to sub class our User into an Unknown user. The following diagram illustrates this simple approach. btw see Customers equal to users :))

Figure 1 – Patterns of Enterprise Application Architecture, Martin Fowler

As you can see we are even able to provide different types of “null” users such as “Missing” and “Unknown”. That allows us to assign a human readable name to those users (e.g. assign in the sub class’ constructor) and we are still able to check if a given user is unknown (if necessary):

if (Product.Creator is UnknownUser)

Okay, enough general theory about the pattern itself. You might ask how does the whole thing fit into NHibernate? Persistence is the magic word. If our users are persisted then the “unknown” users gets persisted as well. That’s probably not what we want. We wanna keep our data storage clean containing only “real” users. Michael Cromwell points that out in one of his articles:

This then has its own problems because if it’s a user editable object you don’t really want them to be able to change/delete this data so it becomes a special case that will need to be locked for editing/deleting. – NHibernate & Null Object Pattern: The Options, Michael Cromwell

Correct! We don’t want to exclude this user in all our queries and take care of these “special case users”. What he suggests is to handle that case directly in the getter and setter of the property. In case a null is assigned he returns an “NotAssigned User”. In our particular example the solution would look the following:

protected User _creator;

public User Creator {

    get {

        return _creator ?? new UnknownUser();

    }

    set {

        if (value is UnknownUser)

            _creator = null;

        else

            _creator = value;

    }

}

I am happy! This looks like a nice OO solution to me. The “unknown user” won’t be persisted, a null reference will be stored instead. Important: This works fine for one “unknown user type”. However, keep in mind that if we have more than one “unknown user type” (see Figure 1) than it might be necessary to persist those users in order to be able to differentiate between them.

Haven’t used it so far but will in my next projects. Anyone who is interested into more practical details might read How to avoid “!= null” statements in Java?.

Let’s start with a brief description of the problem before digging through the possible solutions. The applications architecture is based on the NHibernate Best Practices with ASP.NET, 1.2nd Ed. by Billy McCafferty. I guess it’s a must read for all who deal with Nhibernate and asp.net. So please read it before moving on, as it helps you to understand the approach I am talking about.

Problem:

1. Many domain objects have different properties which are in need of translations. E.g. A Product may contain a Name and a Category property which needs to be translated into the applications supported languages.
2. It should be easily possible to update the translations of an object before persisting it.
3. After getting a persistent entity it should be possible to get a given property in the applications current language.
4. Querying entities according to the translation must not be a big problem. E.g. Getting a list of products ordered by its name in the current selected language.

1st Solution:

The first solution I tried was the approach from Ayende (Localizing NHibernate: Contextual Parameters) – whose Blog I strongly recommend for all NHibernaters. The approach he describes is having a simple string property on your domain object and mapping it using a filter with the current selected language (culture).

Pros:
- quickly to implement
- Domain objects property stays unchanged (still a string)

Cons:
- Each property would result in an own table
- “ugly” sql queries in your mapping files
- Can’t easily access all translations
- Querying entities is not straightforward (e.g. fulltext search)

2nd Solution (my preferred):

Due to the cons I could not really use the 1st approach within the project and decided to build an own solution. Here is my suggestions…
We create a Domain object called PhraseDictionary acts as a generic container for translation phrases. It can be bound to any property of any of our domain objects. I have added its class diagram to show its members:

That type can be used now for each of our domain properties which require translation. The Name property helps us to differentiate all the different phrases we will have in the DB (you can skip it if you want – though it’s nice if you browse the data directly). The SetPhrase() method sets a phrase for a given LCID and getPhrase() gets a phrase translation for the requested LCID. Both methods return the instance itself to make method chaining possible.
For easier usage there is a Phrase property which does the same but always for the current domain culture (Domain culture could be handled in a DomainCulture class – which gives us the ability to get the current culture and/or switch it). All Phrases are stored in a Dictionary with LCID as key and the actual translation as the value.

As we are going to persist it, thats the resulting mapping file:

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

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

  <class name="MyProject.Core.Domain.PhraseDictionary, MyProject.Core" table="dictionary">

    <id name="ID" unsaved-value="0">

      <generator class="identity" />

    </id>

    <property name="Name"></property>

    <map name="Phrases" 

      access="nosetter.camelcase-underscore" 

      table="phrase" 

      cascade="all-delete-orphan">

      <key column="dictionary_id"></key>

      <index column="culture_id" type="Int32"></index>

      <element column="phrase" type="String"></element>

    </map>

  </class>

</hibernate-mapping>

The most important part here is the Dictionary (map) which stores the LCID as key and the translation as value. Thoses “phrases” are fully cascaded as it makes no sense for them to live without the PhraseDictionary.

Okay lets dig into the actual implementation…

using System;

using System.Collections.Generic;

using System.Text;

using System.Threading;

namespace MyProject.Core.Domain {

    public class PhraseDictionary : DomainObject<int> {

        /// <summary>

        /// required for NHiberante

        /// </summary>

        protected PhraseDictionary()

            : base() {

            Phrases = new Dictionary<int, string>();

        }

        /// <summary>

        /// 

        /// </summary>

        /// <param name="name">internal name only</param>

        public PhraseDictionary(string name)

            : this() {

            Name = name;

        }

        private IDictionary<int, string> _phrases;

        private string _name;

        /// <summary>

        /// Name of the dictionary. 

        /// - only for internal use. Eases browsing data directly in database

        /// </summary>

        public virtual string Name {

            get { 

                return _name; 

            }

            set { 

                _name = value; 

            }

        }

        /// <summary>

        /// Stores all phrases for a lcid

        /// </summary>

        public virtual IDictionary<int, string> Phrases {

            get { 

                return _phrases; 

            }

            private set { 

                _phrases = value; 

            }

        }

        /// <summary>

        /// Adds a phrase for a given lcid

        /// - if the lcid exists then the phrase is updated

        /// - empty strings are considered as "not available". 

        ///     Thus adding an empty phrase might remove an existing if already existed

        /// </summary>

        /// <param name="lcid"></param>

        /// <param name="phrase"></param>

        /// <returns>Returns itself. Useful for method chaining.</returns>

        public virtual PhraseDictionary SetPhrase(string phrase, int lcid) {

            if (Phrases.ContainsKey(lcid)) {

                if (string.IsNullOrEmpty(phrase)) {

                    Phrases.Remove(lcid);

                } else {

                    Phrases[lcid] = phrase;

                }

            } else if (!string.IsNullOrEmpty(phrase)) {

                Phrases.Add(lcid, phrase);

            }

            return this;

        }

        public virtual PhraseDictionary SetPhrase(string phrase) {

            return SetPhrase(phrase, Thread.CurrentThread.CurrentUICulture.LCID);

        }

        /// <summary>

        /// Gets a phrase for a given lcid

        /// - returns empty string if it does not exist

        /// </summary>

        /// <param name="lcid"></param>

        /// <returns></returns>

        public virtual string GetPhrase(int lcid) {

            if (Phrases.ContainsKey(lcid)) return Phrases[lcid];

            return string.Empty;

        }

        public virtual string GetPhrase() {

            return GetPhrase(Thread.CurrentThread.CurrentUICulture.LCID);

        }

        /// <summary>

        /// Gets the phrase for the current UI culrute

        /// </summary>

        public virtual string Phrase {

            get {

                return GetPhrase();

            }

            set {

                SetPhrase(value);

            }

        }

        public override int GetHashCode() {

            return Phrases.GetHashCode();

        }

        public override object Copy() {

            PhraseDictionary d = new PhraseDictionary();

            d.Name = Name;

            d.Phrases = new Dictionary<int, string>(Phrases);

            return d;

        }

        public override string ToString() {

            return Phrase;

        }

    }

}

And here is how we would hook it up onto e.g. the Name property of a Product domain object.

public interface IProduct {

    // contains all name translations

    // AllNames.Phrase gets/sets the translation for the current domain culture

    PhraseDictionary AllNames { get; set; }

}

This would allow us to set/receive the translation of name property conveniently as follows:

// set the culture to US english

Thread.CurrentThread.CurrentUICulture = new CultureInfo("en-US");

IProduct p = new Product();

// sets product name in english

p.AllNames.Phrase = "Book";

// switch domain culture to german

Thread.CurrentThread.CurrentUICulture = new CultureInfo("de-DE");

// sets product name in german

p.AllNames.Phrase = "Buch";

// both translations have been stored

Debug.Assert(p.AllNames == 2);

// the current one should be german

Debug.Assert(p.AllNames.Phrase == "Buch");

To keep everything together. Here is the part you require in your Product mapping file:

<many-to-one name="AllNames"

  cascade="all-delete-orphan">

    </many-to-one>

One requirement was an easy use of the translations within HQL query. Here is an example of how we would fet all products sorted by the name of the current culture:

// Gets all products sorted by the name of the current culture

IList<Product> GetAllSortedByName() {

    string query = @"

        from Product product

        left outer join product.AllNames allNames 

        where index(allNames) = :lcid 

        order by allNames";

    IQuery q = NHibernateSession.CreateQuery(query);

    q.SetParameter("lcid", Thread.CurrentThread.CurrentUICulture.LCID);

    return q.List<Product>();

}

That was it. Thanks for having the read and I am looking forward to lots of feedback which could improve that approach.

Here are some quick remarks:
- I strongly recommend creating a DomainCulture class which encapsulates the current culture and how it is stored.
- Probably it would be useful to make the PhraseDictionary.Phrases readonly to the public.