This page is converted from the old nhforge.org Wiki. First published by: gabriel.schenker on 09-06-2008, Last revision by: MarkCranness on 07-08-2011
In this article I want to discuss the lazy loading mechanism provided by NHibernate. It is recommended for maximum flexibility to define all relations in your domain as lazy loadable. This is the default behavior of NHibernate since version 1.2. But this can lead to some undesired effects if querying your data. Let's discuss these effects and how to avoid them.
In my previous posts I showed how to prepare your system for NHibernate and how to implement a first NHibernate base application. This post is based on those two articles.
Let's first define a simple domain. It shows part of an order entry system. I keep this model as simple as possible (a real domain model would be more complex) but it contains all aspects we want to discuss in this post. Below is the class diagram of our model
We have an order entity which can be placed by a customer entity. Each order can have many order line entities. Each of the three entity types is uniquely identified by a property Id (surrogate key).
We have to write one mapping file per entity. It is recommended that you always have one mapping per file. Don't forget to set the Build Action of each mapping file to Embedded Resource. People often tend to forget it and the subsequent errors raised by NHibernate are not always obvious. Also do not forget to give the mapping files the correct name, that is *.hbm.xml where * denotes the placeholder for the entity name.
The mapping for the Order entity might be implemented as follows
<?xml version="1.0" encoding="utf-8" ?> <hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" assembly="LazyLoadEagerLoad" namespace="LazyLoadEagerLoad.Domain"> <class name="Order" table="Orders"> <id name="Id"> <generator class="guid"/> </id> <property name="OrderNumber"/> <property name="OrderDate"/> <many-to-one name="Customer" /> <set name="OrderLines" cascade="all-delete-orphan" > <key column="OrderId"/> <one-to-many class="OrderLine"/> </set> </class> </hibernate-mapping>
Analogous you can implement the mappings for the Customer entity
<?xml version="1.0" encoding="utf-8" ?> <hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" assembly="LazyLoadEagerLoad" namespace="LazyLoadEagerLoad.Domain"> <class name="Customer"> <id name="Id"> <generator class="guid"/> </id> <property name="CompanyName"/> </class> </hibernate-mapping>
and finally the mapping for the OrderLine entity.
<?xml version="1.0" encoding="utf-8" ?> <hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" assembly="LazyLoadEagerLoad" namespace="LazyLoadEagerLoad.Domain"> <class name="OrderLine"> <id name="Id"> <generator class="guid"/> </id> <property name="Amount"/> <property name="ProductName"/> </class> </hibernate-mapping>
To test the mapping we use the following test method
First we create a new instance of the NHibernate Configuration class and tell it to configure itself. Since we don't provide any explicit configuration here in the code NHibernate looks out for an adequate configuration file. I have included such a file (called hibernate.cfg.xml) in my project. Please consult this previous post for further details about the configuration file.
To avoid repetitive task (DRY principle) we implement the following base class.
When the test fixture is started, the base class configures NHibernate and creates a session factory (TestFixtureSetUp). When the whole test fixture is ended the session factory is closed (TestFixtureTearDown).
Before each test in the fixture is run the database schema is (re-) created and the virtual Before_each_test method is called. After each test in the fixture is finished the virtual After_each_test method is called. The two virtual methods can (but must not necessarily) be overridden in a child class.
All our test fixtures we implement will derive from this base class.
To be able to test the loading behavior of NHibernate we need some test data in our database. We create this test data every time a test is run (just after the database schema is re-created). We add a new class Order_Fixture to our test project and inherit from the TestFixtureBase base class. Then we override the Before_each_test method and call a helper method which creates our initial data. We create just the absolute minimum of data we need (again -->DRY). That is: one customer placing one order with two order lines.
The CreateInitialData method is run before each test. With this we guarantee that each test is side effects free.
When loading an order entity from database the default behavior of NHibernate is to lazy load all associated objects of the order entity. Let's write a test to verify this. For the verification we use a utility class provided by NHibernate (NHibernateUtil) which can test whether an associated object or object collection is initialized (i.e. loaded) or not. The class can also force the initialization of an un-initialized relation.
The test succeeds and NHibernate generates SQL similar to this one
Now we have a problem: If we want to access the order line items (after the session has been closed) we get an exception. Since the session is closed NHibernate cannot lazily load the order line items for us. We can show this behavior with the following test method
Note: the above test only succeeds if the method throws the expected exception of type LazyInitializationException. And this is just what we want to show!
Another problem is the n+1 select statements problem. If we access the order line items after loading the order we generate a select statement for each line item we access. Thus if we have n line items and want to access them all we generate one select statement for the order itself and n select statements for all line items (result: n+1 select statements). This can make our data fetching rather slow and put a (unnecessary) burden onto our database.
We can simulate this behavior with this test method
NHibernate will generate SQL similar to the following
This time we have been lucky! NHibernate has automatically generated an optimized query for us and has loaded the 2 order line items in one go. But this is not always the case! Imagine having a collection with several 100 items and you only need to access one or two of them. It would be a waste of resources to always load all items.
But fortunately we have a solution for these kind of problems with NHibernate. It's called eagerly loading.
If you know you need have access to related objects of the order entity you can use the NHibernateUtil class to initialize the related objects (that is: to fetch them from the database). Have a look at this test methods
With this utility class you can initialize single objects as well as collection of objects. In each case NHibernate will send 2 select statements to the database. One to select the order and one to initialize the related object(s).
If you know that you want to load all order items of a given order then you can tell NHibernate to do so and eagerly load all order lines together with the order in one go. The following test method shows how you can formulate a HQL query which not only loads the order but also the associated customer and order lines.
The resulting sql generated by NHibernate is then similar to this one
NHibernate has created an SQL select statement which joins the 3 tables involved, namely Orders, Customer andOrderLine. The returned (flat) set of records is then used by NHibernate to build up the object tree with the order entity as a root.
DDD defines the concept of aggregates. A short definition of an aggregate is "A cluster of associated objects that are treated as a unit for the purpose of data changes.". An aggregate always has a root. In this context we can define the following aggregate in our domain
The order entity is the root and the order lines belong to the aggregate (can be regarded as children of the root). When creating a new order or changing an existing one we only want to modify either the order itself or its order lines. We certainly do not want to change the customer entity because this would be a completely different use case and does not belong to the order management use case.
So, when dealing with aggregates we often want to load the complete aggregate in one go! This is the perfect example for using eager loading techniques.
I have introduced the concept of lazy loading as provided by NHibernate. I have discussed the consequences and shown how to avoid negative side effects by using different techniques of so called eager loading.