There and Back Again : NHibernate

Building NHibernate 1.2.1GA on .NET 3.5

hdierking — Fri, 21 Mar 2008 00:49:14 GMT

I recently reached a point where for reasons that I'm sure you can all relate to, I decided to clean my laptop and rebuild. I therefore did a clean install of Vista with SP1. As a quick aside, SP1 does actually seem to improve performance - particularly when starting up or closing down. Anyway, after I was back up and going again, I setup NAnt and then downloaded the NHibernate 1.2.1 GA source. However, I ran into 2 major problems building, so I thought I would share those, along with how to work around them.

Both problems can be corrected by modifying the markup in the build-common/common.xml file.

The first problem had to do with the fact that the build was expecting the clover library. The solution was simply to add a condition to the property set declaration. I'm not going to spend any more time on this one, because the problem/solution is documented here.

The second problem is that there is no target in the build file for .NET 3.5. On most machines, this isn't a big deal because you've probably upgraded framework versions incrementally, and the build file can target 2.0 with no problem. Because I have a fresh OS/Framework install, I got an error saying that .NET 3.5 is not supported for my build of NHibernate. This can be worked around by adding a target declaring a configuration for .NET 3.5, like so:

<target name="set-net-3.5-framework-configuration">
    <property name="nant.settings.currentframework" value="net-2.0" />
    <property name="current.build.defines" value="${build.defines}NET,NET_2_0" />
    <!-- not using SDK_v2_0 because ndoc throws an exception -->
    <property name="link.sdkdoc.version" value="SDK_v1_1" />
    <property name="merge.targetplatform" value="v2.0" />
</target>

When you get into the config file, you'll see that all I did was create a target with 3.5 declared as a part of the target name, and then coped the body from the 2.0 target inside of my 3.5 target. Initially, I had actually configured the properties to make them specific to .NET 3.5. Unfortunately, I later discovered when I tried to use the compiled assemblies that many of the source files have preprocessing directives that are specific to the defines declared in the build properties. For example, the ISet<T> source code is wrapped with the following directive.

#if NET_2_0

Anways, after making these 2 changes, I was able to build with no problem, and NHibernate continued to work as advertised.

Last Old Blog Code Update

hdierking — Fri, 07 Mar 2008 10:12:00 GMT

Ok - after posting this update, I'll consider myself caught up with regard to picking up the pieces of my old blog. This is the updated code sample for creating custom mapping types in NHibernate. The updated sample provides a loose example of implementing the type object pattern - a pattern where one object instance serves as the type for a set of other object instances. Here, for the sake of simplicity and expediency, I have designed the types such that the type object is also the value container - hopefully when you look at the code, you can see it's a pretty simple process to go a step farther and implement the full pattern.

Anyway, similar to my last post, I've updated the code to use the latest version of NHibernate, and I've added in some LINQ goodness. And of course, all demoware disclaimers apply.

Old TDD Demo Blog - Digest and Code

hdierking — Sun, 02 Mar 2008 10:24:00 GMT

Several of you have emailed me over the past several months asking if I had a copy of the blog text and/or code that I had mentioned in a much earlier blog entry. As it turns out, a good friend of mine found some old archived versions of the site on an Internet cache and set them over to me. Therefore, I have taken the web pages and compiled them into an XPS document so that you can see the thought progression that went along with building a small application, TDD style.

Additionally, I've updated the code samples a bit. Specifically, I've upgraded the version of NHibernate to 1.2.1.GA - and as such, dropped the use of Ayende's NHibernate Generics library. Also, as I was going through my NHibernate mappings, I realized that I had been pretty lazy with regard to semantic accuracy for collection types - I had pretty much completely used <bag> mappings instead <set> mappings for unordered collections so that I could use IList<T>. Therefore, I cleaned that up a bit. Other than that, the only other thing that I did was update some of the looping and conditional code to use LINQ.

Finally, let me emphatically throw out the "Demoware Disclaimer" - The point of the blog and the code samples was to illustrate the thought process and corresponding code behind using TDD to design a domain model. As a result, everything else in the code is the simplest thing that could be implemented to support the overall goal - and nothing more.

NHibernate Custom Mapping Types

hdierking — Tue, 24 Apr 2007 05:36:00 GMT

(originally posted to Absolute Opinion on June 14, 2006)

As you should know by now, NHibernate is an object-relational mapping (ORM) tool that uses XML metadata files to marshal data between an object-oriented domain model and a relational database. Now, in the majority of use cases, the default support provided by NHibernate will be sufficient for saving and fetching your domain objects. However, there are cases where additional capabilities are required. Fortunately, NHibernate provides lots of extension points. I’m going to discuss 2 scenarios in this article – both of which take advantage of creating custom NHibernate mapping types.

Scenario 1:

You have an implementation of the Type Object Pattern. Simply put, you have a class to represent the type of an object, and then a class the references your type object. The static model looks like the following.

Now, let’s take this a step further and say that your type class takes a pretty large amount of time to construct and initialize. Therefore, you decide to implement a flyweight factory in order to minimize the performance impact on your application in terms of the number of type class instances that must be constructed. Fantastic! Now, let’s look at the ramifications on persistence.

From the object persistence perspective, the problem you are now facing is that you do not want to persist the object state for your TypeClass instance (since you are trying to control the number of instances for that class). However, you do want to persist enough information about the TypeClass instance so that when you load an instance of ActualClass from the database, you can get the correct TypeClass instance from the flyweight factory and apply it to your reconstructed ActualClass instance.

Now in a world without NHibernate (oh what a sad world!), we would create a data access class for ActualClass and add methods for setting and fetching ActualClass instances. Since the TypeClass reference exists outside of the database scope, we would add the association in the data access class. For example, your data access class may have code that looks like the following.

   1:  public static class ActualClassRepository {

   2:    public static void Save(ActualClass actualClass) {

   3:      IDbCommand cmd = null;

   4:      IDbDataParameter param;

5:

   6:      //build the sql command and parameters...

   7:      param = cmd.CreateParameter();

   8:      param.ParameterName = "@typeClass";

   9:      param.DbType = DbType.String;

  10:      param.Value = actualClass.Type.Name;

  11:    }

12:

  13:    public static ActualClass Get(int id) {

  14:      IDataReader rdr = null;

15:

  16:      //build the sql command to and get a data reader...

  17:      if (rdr.Read()) {

  18:        ActualClass ret = new ActualClass();

  19:        ret.Data = rdr.GetString(0);

  20:        TypeClassFactory factory = new TypeClassFactory();

  21:        ret.Type = factory.GetTypeClass(rdr.GetString(1));

  22:      }

23:

  24:      return null;

  25:    }

  26:  }

If you pay attention to the code shown in bold for both the get and set methods, you can see how your data access class might handle the setting and fetching of an object and its associated type object. When saving the ActualClass object, the data access object saves the name of the associated TypeClass object to the database. When the ActualClass object is restored from the database, the name of the TypeClass is retrieved and passed to our flyweight factory where the object instance can be acquired and set on the ActualClass object being built.

Now, this works fine in very simple cases like the one mentioned above. However, most object models have many more complex sets of associations. It is in cases like this where NHibernate reveals a great deal of strength – and it would be advantageous to be able to use NHibernate to solve our type object problem.

Enter the custom mapping type.

In NHibernate, a custom mapping type is a class that derives from either the IUserType or ICompositeUserType interfaces. These interfaces contain several methods that must be implemented, but for our purposes here, we’re going to focus on 2 of them. Consider the following.

   1:  public class TypeClassUserType : IUserType

   2:  {

3:

   4:    ...

5:

   6:    object IUserType.NullSafeGet(IDataReader rs,

   7:      string[] names,

   8:      object owner) {

9:

  10:      string name = NHibernateUtil.String.NullSafeGet(rs,

  11:        names[0]) as string;

12:

  13:      TypeClassFactory factory = new TypeClassFactory();

  14:      TypeClass typeobj = factory.GetTypeClass(name);

  15:      return typeobj;

  16:    }

17:

  18:    void IUserType.NullSafeSet(IDbCommand cmd,

  19:      object value,

  20:      int index) {

21:

  22:      string name = ((TypeClass)value).Name;

  23:      NHibernateUtil.String.NullSafeSet(cmd, name, index);

  24:    }

  25:  }

Having created this class, I can now explicitly map the association between ActualClass and TypeClass as a simple property on the ActualClass mapping.

<property
  name="Type"
  column="TypeName"
  type="Samples.NHibernate.DataAccess.TypeClassUserType, 
    Samples.NHibernate.DataAccess" />

As NHibernate is in the process of saving an instance of ActualType, it will load and create a new instance of TypeClassUserType and call the NullSafeSet method. As you can see from the method body, I am simply extracting the name from the mapped property (passed in as the value parameter) and setting the extracted name as the value of the parameter to be set in the database. The net result is that although the Type property of ActualClass is TypeClass in the domain model, only the Name property of the TypeClass object gets stored in the database. The converse is also true. When NHibernate is loading an instance of ActualType from the database and the finds a property of my custom mapping type, it loads my custom type and calls the NullSafeGet method. As you can see, my method gets the name from the returned data, calls my flyweight factory to get the correct instance of TypeClass, and then actually returns that instance. The type resolution process happens transparently to my data access classes (and even to NHibernate itself for that matter).

Scenario 2:

As a part of your object model, you have a standard IDictionary implementation (Oh my goodness – untyped collections!!! Yea – it still happens sometimes!) that looks as follows.

private IDictionary _values = new Hashtable();

Now, here’s the basic problem with this implementation when persisting to a database. By design, this data structure can contain – well – anything. So how do you persist it to the database in a meaningful way? One technique that can be used is to store the value as a string in one column and store the type identifier as a string in a different column. The problem here is that many times (especially when you think about it from the database point of view) you end up with a clunky object model because there is no real reason to store the type as an additional piece of data. Fundamentally, the database requires 2 pieces of information to make sense of 1 piece of domain model information (value + type). It would be really great if we could hide this splitting and merging of data in the mapping layer…

…and we can – using a composite custom mapping type. Take a look at the following.

   1:  public class Object2StringUserType : ICompositeUserType

   2:  {

3:

   4:    ...

5:

   6:    object ICompositeUserType.NullSafeGet(IDataReader dr,

   7:      string[] names,

   8:      ISessionImplementor session,

   9:      object owner) {

10:

  11:      string val = (string) NHibernateUtil.String.NullSafeGet(dr,

  12:        names[0],

  13:        session,

  14:        owner);

15:

  16:      string valTypeString =

  17:        (string) NHibernateUtil.String.NullSafeGet(dr,

  18:          names[1],

  19:          session,

  20:          owner);

21:

  22:      if (val == null || valTypeString == null)

  23:        return null;

24:

  25:      Type valType = Type.GetType(valTypeString);

  26:      return TypeDescriptor.GetConverter(valType).ConvertFrom(val);

  27:    }

28:

  29:    void ICompositeUserType.NullSafeSet(IDbCommand cmd,

  30:      object value,

  31:      int index,

  32:      ISessionImplementor session) {

33:

  34:      string valString = TypeDescriptor.GetConverter(

  35:        value.GetType()).ConvertToString(value);

36:

  37:      string valTypeString = value.GetType().AssemblyQualifiedName;

  38:      NHibernateUtil.String.NullSafeSet(cmd, valString, index, session);

  39:      NHibernateUtil.String.NullSafeSet(cmd,

  40:        valTypeString, index + 1, session);

  41:    }

42:

  43:    string[] ICompositeUserType.PropertyNames {

  44:      get { return new string[] {"val", "valType"}; }

  45:    }

  46:  }

As you can see, this interface fragment looks similar to that of our regular custom mapping type. However, it has several additional members which allow the custom type to actually map a given domain model value onto multiple database columns. In this example, I have used the type to split the value of my IDictionary object over 2 columns in my database table: Value and ValueType. When my dictionary is persisted, my mapping type converts the dictionary value to a string and then persists that value along with the fully qualified name of the value’s original type to 2 columns in the database. Those columns are identified in NHibernate mapping file and mapped to property names (in this case val and valType) based on the order in which they appear in the mapping file. The NHibernate mapping XML looks as follows.

<map name="_values" access="field" table="Values"> 
  <key column="ID_Parent"></key> 
  <index column="Key" type="String"></< SPAN>index> 
  <element type="Samples.NHibernate.DataAccess.Object2StringUserType, 
       Samples.NHibernate.DataAccess"> 
    <column name="Value" /> 
    <column name="ValueType"/> 
  </element> 
</map>

Again, all of this happens behind the scenes as NHibernate is setting and fetching your objects from the database. All you know is that for any type that you put into the your dictionary, you can expect the same type to be in the dictionary for that item, even after saving and loading it from the database.

In conclusion, I hope that this has illustrated the flexibility that can be found within NHibernate as it relates to some more advanced mapping scenarios. If you have any questions or ideas for custom mapping types, please share!

Designing a Domain-Driven Data Access Layer

hdierking — Tue, 24 Apr 2007 05:35:57 GMT

(originally posted to Absolute Opinion on June 4, 2006)

I had started writing a post about best practices for using the different NHibernate collection mapping types when it dawned on me that I may be assuming too much in thinking that we all look at data access layers in the same way. In fact, I think that it is fair to say that most folks who came through the ADO school of data access were trained to think of the data access layer as little more than a set of helper classes used to connect “business objects” to SQL Server stored procedures.

Now, for those of you who still view the data access layer in the way that I described above, this article is not to convince you that you are wrong (even though you are). However, I think it may be fair to say that you may have trouble fitting what I’m going to describe into your way of thinking.

So let’s start with a few very basic goals for a data access layer (DAL).

The DAL should completely hide the underlying data access technology, whether it be an ORM tool like NHibernate, hand-generated inline SQL, calls to stored procedures, or anything else.
The DAL should not place any significant constraints on the design of the domain model.
The entire layer should be replaceable with minimal impact (or minimal risk for you PM folks).

Now, all of the aforementioned goals can be summarized with one word: decoupling. This is a great word – it’s a word that we keep hearing over and over again with every architecture talk and every article. In fact, didn’t the introduction of component programming give us decoupling without any effort on our parts?

In case you were wondering about that last one, the short answer is – no.

So what should a decoupled DAL look like? In .NET programming terms, the answer lies in the references. Given our stated DAL goals, we need to be able to pull out our entire DAL and replace it with another (say one that persists our objects to and from the file system rather than a RDBMS) without causing any impact on the rest of the system. We therefore can’t have our business layer (henceforth called domain model) having any knowledge that a DAL even exists. This is due to the fact that our domain model is designed to be the very core of our system. The objects contained within the domain model form the basic language that our software system uses to describe a real world problem. Put another way, our domain model is (or, should be) a neutral layer in terms of technology concerns. The last thing that we should want to do is create a dependency on a layer whose sole focus is a technology-specific concern (persistence).

So, getting back to observing decoupling through references, what can we deduce from my tangential diatribe above? Firstly, the DAL assembly should hold a reference to the domain model assembly – the domain model assembly should not reference the DAL in any way. Secondly, all other assemblies that need to interact with a persistent store to get and set domain objects will hold a reference to both the domain model assembly and to the DAL assembly. To pull from the SARK Classic project, such a relationship looks as follows:

Now that we have an architectural view of what the DAL should look like, what should it look like at the code level? Firstly, DAL classes should be defined not in terms of “1 DAL class per 1 domain model class” but rather in terms of domain model aggregates. The term aggregate was defined by Eric Evans in his book Domain Driven Design as follows.

“An AGGREGATE is a cluster of associated objects that we treat as a unit for the purpose of data changes. Each AGGREGATE has a root and a boundary. The boundary defines what is inside the AGGREGATE. The root is a single, specific ENTITY contained in the AGGREGATE.”

So you may be wondering why the terms “aggregate” and “entity” are typed in caps – well, me too – that’s just the way the book was written.

Let’s apply that definition to the SARK Classic sample project. A golf course has a specified number of holes – and each hole has a par value. However, the unit of change from the data perspective is always the course – i.e. – there is never a time when you would access a specific hole directly – you would always access a hole through the course. Therefore, we can say that the Course Aggregate consists of 2 classes: Course and Hole. That is the aggregate boundary. Additionally, Course is the aggregate root. In support of the aggregate boundary, DAL objects should be defined for aggregates – not specifically for domain objects.

Once you have defined aggregate boundaries, you will hopefully find that persistence concerns can be dealt with at a more coarsely granular scope. Dealing with aggregates rather than objects may also help reduce decoupling even within the domain model. I’ve seen that many domain models have unnecessary associations between objects simply for the purpose of pulling down the entire object graph during persistence. In thinking of persistence in terms of aggregates rather than domain objects, you may also see opportunities to get rid of some of these associations and instead simply create additional query methods on the DAL object for the associated aggregate. This idea is also discussed in Eric Evans’ book, so for additional research on the topic of aggregates, it is a must.

Now, when talking about DALs that are written in terms of a domain model rather than a technology like DataSets, critics typically raise a very good point: Why is this design technique worth losing all of the wonderful support that Visual Studio provides for RAD development? In short, it’s not. A colleague once said something very profound – it was something I was already doing, but I like the way that he said it, so I’m going to attempt to quote him. He said, “Render unto the DAL that which is the DAL’s – render unto the DataGrid that which is the DataGrid’s”. Ok, he was talking about NHibernate – and I’m generalizing a bit more – I’m certain that he will forgive me. If you’re building an ASP.NET application using a GridView, you should use the data source providers in the .NET framework to populate that GridView. Your DAL should not be concerned with dealing with tabular data (especially now that the data source providers are in the .NET Framework). Your DAL is concerned with getting and setting domain objects. See? You can have your cake and eat it too!

Finally, let’s spend a few minutes dealing with DAL design as it relates to NHibernate. Again, I want to quickly reiterate that the DAL design style that we’ve been discussing in no way relies on NHibernate. However, there are some major benefits to using NHibernate inside of your DAL.

Reflection based mapping allows complete encapsulation of object state, as it can reflect over private members.
NHibernate keeps track of the mapped id of an object and can determine whether it is a new object (known as a transient entity) or whether it is an existing persistent object. The NHibernate API then allows you to simply call a method “SaveOrUpdate(object)” – and NHibernate will determine the type of query that needs to be run.
NHibernate keeps track of the dirty state of object members.
For object graphs where there are several associations, NHibernate can be optimized to use outer joining so that only one query needs to be run rather than running a query for the aggregate root’s data, then running subsequent queries for the other members of the aggregate.
Caching anyone?
NHibernate supports multiple RDBMSs right out of the box (or zip file)

These are just some of the many benefits to using NHibernate as your data access technology. Over the next couple weeks we will dive into some of the specifics of using NHibernate. However, like I said at the beginning, I want to make sure that we’re all on the same page architecturally before getting into the details.