There is nothing you need to do to enable lazy behavior on collections. All collection mappings are lazy by default. With lazy loading enabled, when an entity is loaded, NHibernate sets all the collection properties on this entity to a special collection type implemented by NHibernate. This special collection type is capable of loading entities in the collection when the collection is accessed (on demand). Let's take an example and see how this works.

In the following test, we are loading the Employee entity having first name as John:

[Test]
public void QueryEmployeeByName()
{
  IList<Employee> employees = null;
  using (var transaction = Database.Session.BeginTransaction())
  {
    employees = Database.Session.CreateCriteria<Employee>()
                        .Add(Restrictions.Eq("Firstname", "John"))
                        .List<Employee>();

    transaction.Commit();

  }
Assert.That(employees.Count, Is.EqualTo(1));
}

If you look at the SQL generated for the preceding code then you would notice that NHibernate has not generated any SQL to load the Benefits and Communities collection. As shown in the following image, on inspection of the loaded employees collection, we can see that the Benefits and Communities collection on these entities is set to a special type NHibernate.Collection.Generic.PersistentGenericSet<T>:

PersistentGenericSet<T> is a special type that NHibernate implements. This is commonly referred to as collection wrapper. Let's take a close look at definition of this type.

public class PersistentGenericSet<T> : AbstractPersistentCollection,
ISet<T>,

PersistentGenericSet<T> is NHibernate's persistence-aware implementation of ISet<T>. Whenever you access the collection property in your code, PersistentGenericSet<T> will issue required SQL statements to load the items in the collection. There are several implementations of collection wrappers in NHibernate. Depending on the type of the collection, NHibernate chooses the right collection wrapper. In our case, since the Communities collection property on the Employee class is of type ICollection<T> and ISet<T> inherits from ICollection<T>, NHibernate chooses to use PersistentGenericSet<T>. For other collection types, other implementations are available. As a user of NHibernate, you do not need to know what those types are. NHibernate manages this transparently for you.

Set(e => e.Benefits,mapper =>
{
  //… other mappings…//
  mapper.Lazy(CollectionLazy.NoLazy);
  },
relation => relation.OneToMany(mapping => mapping.Class(typeof(Benefit))));

Single-ended associations are the other end of collection type of association. In mapping, these are represented by many-to-one element. Similar to lazy collections, lazy behavior for these type of associations is enabled by default. But unlike lazy collections, lazy behavior setting takes different values indicated as follows:

Let's look into an example to see how lazy loading for single-ended associations works. We will use the association from Benefit to Employee to explore this topic. Following image from Chapter 3, Let's Tell NHibernate About Our Database, summarizes this association briefly:

Following code listing from the mapping of the Benefit entity shows how to explicitly enable lazy behavior on the Employee property of the Benefit class:

ManyToOne(a => a.Employee, mapper =>
{

  mapper.Column("Employee_Id");
  mapper.Class(typeof (Employee));
  mapper.Lazy(LazyRelation.Proxy);
});

In the preceding code, we have told NHibernate that Employee association on Benefit should be treated as lazy and in particular, Proxy type.

Next, we will write a test to load all the SeasonTicketLoan benefits having amount greater than 1000:

[Test]
public void LoadSeasonTicketLoanBenefitsHavingAmountGreaterThan1000()
{
  using (var transaction = Database.Session.BeginTransaction())
  {
    var seasonTicketLoans = Database.Session
                                   .QueryOver<SeasonTicketLoan>()
                                   .Where(s => s.Amount > 1000)
                                   .List<SeasonTicketLoan>();
    Assert.That(seasonTicketLoans.Count, Is.EqualTo(1));
    Assert.That(seasonTicketLoans[0].Employee, Is.Not.Null);

    transaction.Commit();
  }
}

If we inspect the actual value of the Employee property on the previous seasonTicketLoans[0] then we can see that it is of type EmployeeProxy, which is a type generated by NHibernate at runtime.

Proxy versus NoProxy

To understand the difference between Proxy and NoProxy, we will have to assume that Employee has one more entity inheriting from it. Suppose we have FormerEmployee inheriting from Employee. If we also consider the NHibernate's dynamically generated EmployeeProxy type, then we get the following class diagram:

When a benefit entity is loaded, the Employee association is lazily loaded and set to an instance of type EmployeeProxy. NHibernate has not yet gone to database to check whether the actual entity is of the Employee type or the FormerEmployee type. If you are expecting an instance of FormerEmployee and downcast the loaded instance to that type, you would be greeted with an exception because the actual type held in there is EmployeeProxy.

This is where NoProxy plays its role. In the previous example, when the lazy setting was set to Proxy and the Benefit instances was loaded from database, its type was set to actual type – SeasonTicketLoan in this case. It was the Employee property that was set to proxy type EmployeeProxy. But when lazy setting on the Employee association is set to NoProxy, then NHibernate will load a proxy instance of the Benefit class first -, which is SeasonTicketLoanProxy. Now because the parent object is a proxy, NHibernate is capable of intercepting it. When you access the Employee property on this proxy, NHibernate will go to database and load the correct instance of Employee and return it.

Note

NHibernate lets you intercept different operations that it performs so that you can run your custom logic before NHibernate finishes its own operation. One such interception, called property load interception, will let you run your logic before/after value of a property is loaded from database. Implementation of NoProxy uses property load interception. What that means for you, the user of NHibernate is that the NoProxy option will work only if the association uses property. If your association uses field then NoProxy would not work.

Besides lazy collections and lazy single-ended associations, NHibernate also supports lazy properties. One or more mapped properties of an entity can be declared lazy by using the syntax shown next:

Property(e => e.EmployeeNumber, mapper => { mapper.Lazy(true);});

In the preceding syntax, the EmployeeNumber property on the Employee class is mapped as lazy. Value of a lazy property is loaded from database when the property is accessed for the first time. If a class has more than one lazy property then all lazy properties are loaded at once when any of the lazy property is accessed.

In the introduction of lazy loading, we discussed how lazy loading can avoid whole databases being loaded into memory on retrieval of a single entity. Well, that is a great benefit of lazy loading but there is another more apparent benefit that lazy loading brings to the table.

Suppose you are working on a business requirement with makes an employee a member of a community. Assume that you load this employee by its ID. Ideally, you would only want to load the employee and its Communities collection. In absence of lazy loading, you would have to resort to writing a detailed query to load only the parts you need.

Now, suppose you have another requirement that involves loading employee by its ID and the Benefits collection on the employee instance. The query you used for the previous requirement cannot be used here because that query did not load the Benefits collection. You have two options now – one, write a new query to load employee and its Benefits collection and two, update the previous query so that it loads both the Communities and Benefits collection of employee instance. Neither of these solutions are ideal. The first solution is not scalable as you would end up writing similar queries with slight variations in details that they load. The second solution leads to unnecessary loading of collection items that may not be required.

Lazy loading handles such situations quite nicely. You write one query to retrieve employee by its ID and use it in both the requirements. When the code for the first requirement navigates to the Communities collection, it is loaded. When the code for the second requirement accesses the Benefits collection, it is loaded at that point. Neither do you have to write duplicate querying code nor load unnecessary collection items.

Lazy properties are slightly different. If an entity has lazy properties, then NHibernate ends up making two database trips, once to load the non-lazy properties of the entity and second time to load the lazy properties of the entity. This behavior may actually result in unnecessary round trips to database. So do not use lazy properties unless you are absolutely sure that you need lazy behavior. One situation where you might want lazy property is when the property holds large amount of data which is not needed to be fetched all the time along with other properties on the same entity. SQL types such as BLOB, CLOB, TEXT, and Binary are examples of such properties. Making such properties lazy, you can save large amount of data coming out of database every time the entity is loaded.

While lazy loading is a great feature, it is very easy to get into issues if lazy loading is used without care. There are some gotchas around lazy loading that we will look into briefly in this section. Knowing these will help you avoid problems and frustration while working with lazy loading.