Last week I started work at my new client and joined their development team and it has been a real experience. I joined in the middle of a deployment cycle on a project that was developed a new framework, which at times made me feel like Alice in wonderland trying to follow the yellow brick road.

This new project is using a service bus architecture, with objectives including being highly scalable and highly reliable. The current architecture allow us to literally scale up our nodes to any level to compensate for demand and also handle failover scenarios. All of this being handled using a service bus implementation that I must say “just works” and is very impressive.

In future posts, apart from my regular posts on DDD, NCommon and Rhinestone I'll be posting on how you can implement a distributed and async service bus approach to your applications. I used to believe that service bus implementations are best suited for backend async batch operations, but looking at this new architecture, I believe even applications that today use a request response synchronous approach can benefit with a look at using a service bus.

I’ll be focusing on Rhino Service Bus (and some of its more interesting features such as load balancing and DHT) since that’s that I’ll be using in this project, but the same techniques can be applied when using MassTransit or NServiceBus (or the service bus of your choice).

I have to give a big Kudos to the development team here though, even though I had joined in the middle of a deployment cycle, they were very kind enough to fill me in as much as they could on the project and framework implementation.

Bottom line, I’m looking forward to working with this new client, and if last week is any indication, the following months are going to be not only challenging but a lot of fun as well.

This is part of a continuing series of posts on Fluent NHiberate.

• Using Fluent NHibernate in Rhinestone – Part I

In this part I’ll show how you can map custom user types using Fluent NHibernate.

In a previous post I had discussed the need to use custom user types in Rhinestone and had ended with a promise to have a follow up post on the details on implementing the custom user type and provide mappings for using that custom user type in NHibernate.

Revisiting the previous post, the need arises for a customer user type because the Project domain entity contains properties such as Owner that return a IUser instance and also the Members association that contains a list of IUser types representing members of the project.

The first obvious issue is that Rhinestone doesn’t have any knowledge of an identity and authentication system. It merely stores the username associated with the IUser instance. So when retrieving a Project instance from the data store, we need a way to somehow hydrate the stored username string to a IUser instance.

IUser instances can be resolved via the IUsersService domain service. So first thing to do is to start with an implementation of ICompositeUserType that will provide logic to convert the underlying username string to a IUser instance, by using the IUsersService domain service, and vice versa.

Why ICompositeUserType as opposed to IUserType?

NHibernate provides two ways of defining custom types, one is by providing an implementation that inherits from IUserType and the other is ICompositeUserType. The advantage of ICompositeUserType over an IUserType interface is that types that implement ICompositeUserType allow them to be used in advanced query scenarios where you can query based on the individual properties of the custom type that the ICompositeUserType handles.

The additional benefit is that you can map multiple columns that a single user type using the ICompositeUserType. For example a Money user type could contain two columns in the table, one Amount and one Currency, the ICompositeUserType interface allows you to map both columns to a Money type.

Implementing a abstract base class for implementing ICompositeUserType

[Disclaimer: I got the idea for a generic ICompositeUserType implementation for this blog post: http://geekswithblogs.net/opiesblog/archive/2006/08/13/87880.aspx.]

Since there are many times I have had to implement either a IUserType or ICompositeUserType in my projects I’ve decided to add a base class to NCommon.NHibernate project called CompositeUserTypeBase to ease some of the pain in implementing custom type mapping for NHibernate. I’ll list some of the implementation details of this base class here and how you can use it to implement your own mappings for your custom types.

One functionality I wanted to implement in the CompositeUserTypeBase class is to use expressions to specify the mapped properties rather than strings. Doing so while allow me to avail compile time checking and also refactoring support where if I rename my properties, the mappings specified in my CompositeUserTypeBase implementations will also change. Hence reducing the surface areas for errors.

So let me start by explaining how you can use CompositeUserTypeBase to provide mapping for your custom type and later on I’ll get into the guts of the CompositeUserTypeBase and how it is implemented. Lets say you have a money data type, very common for commerce based applications, and you want to map that data type to a set of columns in the database. A money instance is made up of the amount and currency. These values are stored as separate columns in the database.

Here’s the Money class:

Lets start implementing a user type mapping for Money. Lets create a new class called MoneyUserType that will inherit from CompositeUserTypeBase class:

The type specified as the generic parameter of the ComposteUserTypeBase is the type that will be returned. Right off the bat you’ll notice three members that must be overriden by inheritors of CompositeUserTypeBase class. I’ll get to those in a bit, but first lets see how you can specify what properties are mapped. To map the properties of the data type that will be queried upon, you can use the MapProperty method in the default constructor.

In the above code snippet I am using lambdas to specify that both the Currency and Amount property should be mapped.

The first method that the CompositeUserTypeBase class you must override is CreateInstance. This method is given an array of objects containing the values read from the underlying data store and it’s the child class’s responsibility to construct an instance of the underlying data type and return that instance. The reason CompositeUserTypeBase class doesn’t attempt at constructing an instance on it’s own is because there are many scenarios where custom actions need to take place before returning an instance (Rhinestone has this requirement). So instead the CompositeUserTypeBase class offloads the responsibility of constructing instances to the child class.

The next method to override is PerformDeepCopy. Basically this method is called whenever NHibernate calls the DeepCopy method on IComposuteUserType. This method is called whenever NHibernate needs a clone of the current data type (mostly for change tracking I believe, but I could be wrong here).

And last but not least is the IsMutable property.

That’s it.

So what does CompositeUserTypeBase base do?

The CompositeUserTypeBase class implements the ICompositeUserType interface provided by NHibernate and implements some of the repeated logic required for implementing the interface (keeping DRY principle in check). First lets look at the MapProperty method that was used by MoneyUserType in the constructor to provide property mappings.

MapProperty basically accepts a Expression<Func<T, bool>> instance that represents the property of the underlying type that should be mapped. What this method does is uses a specialized ExpressionVisitor, MemberAccessPropertyInfoVisitor in NCommon, and stores the underlying PropertyInfo in an internal list. These properties come into play in other methods and properties.

All other members of the base class are implementation of ICompositeUserType interface.

ICompositeUserType.ReturnedClass

The ICompositeUserType.ReturnedType property should return the type that your ICompositeUserType will map the underlying column(s) value(s) to. CompositeUserTypeBase basically returns the type of the specified generic parameter.

ICompositeUserType.PropertyNames

This property should return an array of strings containing all the properties that will participate in a query. CompositeUserTypeBase builds this array of strings by enumerating over the list of PropertyInfo instances that were stored in an internal list when the child class called MapProperty.

ICompositeUserType.PropertyTypes

This property should return the data types of the properties returned by the PropertyNames property. And just like in the PropertyNames implementation, CompositeUserTypeBase class uses the internal PropertyInfo list to build the array. It uses NHibernateUtil.GuessType to guess the underlying type. [This may not be ideal in all scenarios and that’s why PropertyTypes is marked virtual so that you can override the default behavior if you need to]

ICompositeUserType.GetPropertyValue

This method is called to retrieve the value of a mapped property. The property parameter contains the ordinal value of the property in the array of property names passed by the PropertyNames property. CompositeUserTypeBase basically retrieves the underlying PropertyInfo from the internal list and calls GetValue on it.

ICompositeUserType.SetPropertyValue

Just like GetPropertyValue, SetPropertyValue sets the value of a property for the underlying data type.

ICompositeUserType.Equals

CompositeUserTypeBase basically delegates equality comparison the underlying type since it cannot make any guarantees about equality. Unless the both objects have the same reference pointer, this method calls the underlying data type’s Equals implementation. Remember to override Equals in your data type to ensure proper equality comparison.

ICompositeUserType.NullSafeGet

Now we come to the meat of the ICompositeUserType interface. This method is called by NHibernate to construct the underlying data type based on the data retrieved from the database. The key here is the names parameter passed to NullSafeGet. The names parameter contains an array of strings that represent the column names specified in the mappings file and they are specified in the same order. This order should be remember because that same order is expected by CompositeUserTypeBase when mapping properties.

For example, if your mapping file specifies the Amount column first and then Currency, then the child class should call MapProperty (prop => prop.Amount) and then MapProperty(prop => prop.Currency) to make sure that both mappings are in the same order.

Here’s the implementation.

ICompositeUserType.NullSafeSet

NullSafeSet is the opposite of NullSafeGet where NullSafeSet is called to update the underlying data store with the values in the data type. Just like NullSafeGet, the ordinal values of the property names and column mappings are important.

ICompositeUserType.Assembly, Disassemble and Replace

These three methods simply return the result from DeepCopy. They are virtual so if you need to provide any custom logic you can override them in your child class.

That’s about it for the CompositeUserTypeBase class. Full source and tests are part of NCommon so you can get the source code from codeplex.

Enough of ICompositeUserType nonsense, what about the mappings?

Okay, so I’ve taken the topic of custom user types in NHibernate as far as I can. Now that I have a base class for implementing user types, here is the child class for implementing a custom type for IUser in Rhinestone.

So basically at the time of CreateInstance I am resolving a IUsersService and using the FindUserByName method to get an instance of that user.

Mapping couldn’t be simpler via Fluent NHiberante. Below are the mappings in both xml and ClassMap.

Using Fluent NHibernate you can specify the custom type of a property using the CustomTypeIs method. Similarly, for mapping a list of custom elements, you can use the HasMany method and specify the custom type using the generic overload of the HasMany method. The generic overload of HasMany specifies that the mapping will return the type specified as the generic parameter, instead of the type being inferred from the property as expressed by the lambda.

In the next post I’ll continue to provide mappings for Rhinestone and also show some additional mapping techniques using Fluent NHibernate and finally go into how you can use Fluent NHibernate inbuilt testing functionality to test your mappings.

[You can catch up with previous posts on Rhinestone here.]

Okay, so based on my last post a rough domain model was defined as well as the database model. I’ve removed the previous Rhinestone.Shared project, and it’s related test project, as that has now been encapsulated in NCommon.

So the next step is to setup the mapping layer between the ORM framework of my choice and the database model. Since we I am going to use NHibernate in Rhinestone that involves setting up NHibernate and the mappings that will allow NHibernate to hydrate result sets returned from the database as our domain entities and in the inverse direction serialize our domain entities as records in the database, with their relationships and all.

What is Fluent NHibernate:

You can read the excellent getting started article on Fluent NHibernate here. Basically Fluent NHibernate is an alternateive way, an excellent alternative, to traditional xml mapping and configuration files that are used by NHibernate. The biggest advantage of Fluent NHibernate is that it provides a compile time checking that was not possible with Xml mapping files (although addins are available, especially for resharper, that perform a design time check). If you referenced a field name “Name” in your xml mapping file and that property was then renamed to FirstName and you forgot to update the mapping, that would not give you any kind of notification at compile time, in fact the .net compiler would happily build your binaries and the error would surface only at run time.

Now that I have provided enough of a marketing pitch for the Fluent NHibernate project, it must be noted that it’s very much in development (as of this writing). There are no binary releases as yet and if you want to get started using Fluent NHibernate you must get the latest source code and build it yourself. You might encounter bugs and if you do please do let the development team know, but the project is stable enough so that you could (and should) give it a try.

Defining a simple mapping with Fluent NHibernate:

After getting the source, building it and then referencing it in your project, starting to define mappings for your entities is very straight forward. I’ve created a new project called Rhinestone.Domain.Mappings (class library) and this referenced FluentNHibernate.dll. In this project I’ll define all the mappings for my domain model. The reason I am doing this is because I want to be flexible enough where if I want to use another ORM framework, then all I have to do is provide a new set of mappings that target the new framework and I’m golden. Besides, mappings don’t really belong under the domain model anyways.

So lets start defining a mapping for the Project domain entity. You start out defining a mapping be creating a class that inherits from ClassMap:

Basically ClassMap forms the root of all mappings defined for a single entity, in this case the Project entity. When you inherit from ClassMap, mappings are defined in the constructor of your inherited class. Now, I’ll step through showing the same mappings defined in xml and then defined via ClassMap in Fluent NHibernate. A normal xml mapping file starts like so:

Now, the table in the database that we need to map the Project entity is called Projects. So here is the mapping for the Project entity in xml and then in PorjectMap:

The WithTable method basically sets the underlying table name that the entity maps to.

Now, the first mapping that is normally provided in NHibernate is the identity property. This mapping defines what is the field / property that acts as the identity property of the entity and it’s mapping. In the Project class the identity field is ProjectID, which has only a getter so we need to define that NHibernate should access the underlying field instead of the field when setting it’s value. ProjectID is also an auto-generated filed which must also be specified in the mapping. Below is the xml mapping and after that the same mapping defined in ProjectMap:

The Id method in ClassMap provides a way to define the property that acts as the identity property and then uses a fluent dsl to define additional details on the mapping. Fluent NHibernate uses lambdas to specify mappings, in the code above Id(prop => prop.ProjectID) tells fluent NHibernate to map the ProjectID property as the identity property of the entity. Using lambdas to define mappings instantly gives us an added benefit that if the underlying property is renamed, the mappings will be renamed as well (or at least give a compile time error).

Additionally, you can use the fluent DSL methods provided by Fluent NHibernate to provide additional details on the mapping, like in the example above the Access property. In the code snippet above, Access.AsReadOnlyPropertyThroughCamelCaseField instructs NHibernate to access this properties field that should have the name that matches the camel case underscore format. The thing to note here is that Fluent NHibernate already provides all available access strategy options which is nice because when I started out with NHibernate I always had to go back to the documentation to figure out the exact string format that should be used in the access attribute in the xml mapping file.

Okay moving on, mapping properties to the underlying columns is also fairly straight forward. You can do that using the Map function in ClassMap.

It’s that straight forward. In case the name of your property doesn’t match the underlying column name you can also use an overload of Map that accepts the column name that the property is mapped to:

In the next post I’ll complete the mapping for the Project entity by specifying mappings for a custom user type in NHibernate.

I’ve been thinking about providing a reference application for NCommon and started to work on the NCommonSampleWebsite currently up at CodePlex when I realized I already had a project that I could use as a reference application for NCommon.

It’s been a while since I’ve touched Rhinestone so I will be dusting off the cobwebs on that project and re-focus on finishing Rhinestone as reference DDD web application.

One of the additions to NCommon I haven’t blogged about yet is an implementation of a fetching strategy in NCommon

First a brief background on Lazy / Deferred Loading:

Most ORM’s provide a concept called lazy loading of related entities. The concept of lazy loading should be well known but if you’re unfamiliar with it here’s a brief overview. Lazy loading, a.k.a deferred loading, is the concept of loading associated entities from the database at the time of access.

Meaning that say you have an Order object that has a list of OrderItem entities that represent the items being ordered. When you load the Order entity, the OrderItems associated with those entities are not loaded as well. Only when you access the property of the Order entity that exposes the OrderItems property will the entity then go to the database and fetch items OrderItems.

The advantage of lazy loading is that you don’t load the entire object graph at the time the aggregate root entity is loaded. Take for example a Customer object normally has a list of Orders association, represented maybe by a ICollection<Order> Orders property. If you just want to read the contact information of the Customer entity, you don’t really need to load all the Orders of the customer as well. So lazy loading helps by just retrieving the Customer record from the database, and when and if you require the Orders collection of the Customer entity, a query will be made at that time to load the list of orders.

The need for a Fetching Strategy:

Most of the times Lazy / Deferred Loading is a real advantage, but it can also be a performance nightmare in certain scenarios. Take for example the model below:

The model is pretty straight forward. There is a Customer class that holds a collection association to Order entities representing all the orders for a Customer. There’s a Order class that holds a reference to the Customer for which this order was generated and a collection association of OrderItem instances representing the items being ordered. Each OrderItem in turn has a reference to a Product entity that represents the product being ordered.

Lets say you were to now to show a list of all products (unique) that has been ordered and shipped by a customer within a 2 month period.

What the above code is going to do is first fetch all the orders for the specified customer that has a ship date between that 2 months window. Next at every iteration of an order, it’s items will be loaded from the database and for each OrderItem, the associated product will be loaded.

So if the customer has 10 orders, each with 10 order items and each order item referencing a unique product, that would result in 111 queries to the database to get the result.

That's a colossal waste of resources.

So what is a fetching strategy anyway?

A fetching strategy simply put allows you to define at the time of loading the aggregate root, what all associated entities will also be queried for and loaded in the object graph. The fetching strategy is an explicit pattern which tells the ORM framework to pre-fetch objects within the graph and not perform lazy loading for the entities specified in the strategy.

Defining a fetching strategy would allow us to specify that the data required for the above code to work should be fetching in one single query to the database. That allows efficient use of the database resources as well as avoiding round trips back to the database.

Fetching strategies and Adaptive Domain models:

Fetching strategies normally are not static, and based on the context your code is operating under you would want to use different fetching strategies. For example in the above code snippet that gets all the products shipped to a customer, you would want to define a fetching strategy that gets the entire object graph of Order, it’s OrderItems and each OrderItem’s referenced Product entity.

Lets say someplace else in your application you want to calculate the sum total of all orders placed within the last two months for a customer.

Very similar to the first example, but this one doesn’t require the OrderItem’s associated Product references to be pre-fetched. (I know the correct way to calculate the total value for an order would be to have a TotalValue() method on the order that iterates the Items internally and sums up the total. I needed to be explicit in this example to show the graph that was accessed)

This is somewhat the basis of an adaptive domain model where the fetching strategy for domain entities are based on the current execution context. A lot has been talked about on Adaptive Domain models by Udi Dahan here and here and even Oren Eini (Ayende) here. I suggest you take a look at their posts, if you haven’t already.

Fetching strategy in NCommon

If you’ve note read the posts (links above) by Udi and Oren, I would urge you to do so because what follows relies heavily on the assumption that you have read and understood fetching strategies and the solutions proposed by Udi and Oren.

Okay, so let me start by saying that I agree 100% with Udi and Oren on their implementation of how fetching strategies are defined. That being said, in NCommon there is a slight modification of how fetching strategies are defined and consumed by the framework. The difference is in how the repository is configured to use fetching strategies.

In Udi’s implementation, a repository is created to return IOrderCalculator instances, which is implemented by the Order entity (or can be implemented by a completely different entity) and based on that the repository will auto configure what ever fetching strategies are defined for an IOrderCalculator.

I don’t necessary like that approach is because, a) additional configuration/mappings need to be defined to allow the repository to return IOrderCalculator instances, b) the service is now working with IOrderCalculator instances rather than Order instances (even though Order implements IOrderCalculator).

What I would really like is to have the repository instances return Order instnaces which are configured with fetching strategies for IOrderCalculator. That’s where NCommon differs from the above fetching strategy design.

In NCommon, the IFetchingStrategy interface, used to define a fetching strategy, looks like this:

There’s just one Define method to which the repository instance is passed that the fetching strategy should configure. Below are examples of fetching strategies; one defined for IOrderCalculator and one for IOrderProductListing, both are defined for configuring a repository that returns Order entities:

Here are the IOrderCalculator and IOrderProductLister interfaces

Now I can implement these interfaces on either the domain entities or on domain services. For example, the Order entity implements the IOrderCalculator interface to provide the total value of the order and a OrdersService domain service implements the IOrderProductLister interface to provide the logic of listing all products ordered by a customer for the last x number of months.

So now that I have my fetching strategies defined and defined the context that specifies what strategy (or strategies as there could be multiple) are to be used, the next is how to instruct the repository to use what fetching strategy. This is done by calling the For method on the IRepository instance.

In the ListOrderedProducts method, the repository is configured to use the fetching strategies defined for IOrderProductLister for the Order entity, and in the second case the GetTotalOrderAmount instructs the repository to use all fetching strategies defined for the IOrderCalculator interface.

The For method is implemented by the abstract RepositoryBase base class which allows all implementations that inherit from RepositoryBase to automatically take advantage this fetching strategy pattern. In the For method implementation in RepositoryBase, it simply attemps to resolve all IFetchingStrategy instances defined for the domain entity and the specified context. Then in a tight loop calls the Define method on each strategy found by passing itself as the repository instance.

And thats about it. This way I get the flexibility of defining my context interfaces, which are the IOrderCalculator and IOrderProductLister, on either the domain entity or domain services while still maintaining one mapping configuration for my domain entities and working directly with my domain model.

Well I had planned to focus more on my blog since the my last post, but obviously that hasn’t worked out. The last few weeks have I’ve been pretty busy at work, wrapping up my current project and getting ready for the transition.

Along with the transition, there were some pretty major issues related to SharePoint and our servers last week that required my attention full time. Now that things seem to be back in control, hopefully I will have more time to devote to my blog.

In short, new content coming soon :)