We've already spent quite some time talking about collections. In this section we will highlight a couple more issues about how collections behave at runtime.

Parent p = (Parent) sess.Load(typeof(Parent), id);
    Child c = new Child();
    c.Parent = p;
    p.Children.Add(c);  //no need to fetch the collection!
    sess.Flush();

NHibernate implements lazy initializing proxies for persistent objects using runtime IL generation (via the excellent Castle.DynamicProxy library).

The mapping file declares a class or interface to use as the proxy interface for that class. The recommended approach is to specify the class itself:

<class name="Eg.Order" proxy="Eg.Order">

The runtime type of the proxies will be a subclass of Order. Note that the proxied class must implement a default constructor with at least protected visibility and that all methods, properties and events of the class should be declared virtual.

There are some gotchas to be aware of when extending this approach to polymorphic classes, eg.

<class name="Eg.Cat" proxy="Eg.Cat">
    ......
    <subclass name="Eg.DomesticCat" proxy="Eg.DomesticCat">
        .....
    </subclass>
</class>

Firstly, instances of Cat will never be castable to DomesticCat, even if the underlying instance is an instance of DomesticCat.

Cat cat = (Cat) session.Load(typeof(Cat), id);  // instantiate a proxy (does not hit the db)
if ( cat.IsDomesticCat ) // hit the db to initialize the proxy
{                  
    DomesticCat dc = (DomesticCat) cat;       // Error!
    ....
}

Secondly, it is possible to break proxy ==.

Cat cat = (Cat) session.Load(typeof(Cat), id);            // instantiate a Cat proxy
DomesticCat dc = 
    (DomesticCat) session.Load(typeof(DomesticCat), id);  // required new DomesticCat proxy!
Console.Out.WriteLine(cat==dc);                            // false

However, the situation is not quite as bad as it looks. Even though we now have two references to different proxy objects, the underlying instance will still be the same object:

cat.Weight = 11.0;  // hit the db to initialize the proxy
Console.Out.WriteLine( dc.Weight );  // 11.0

Third, you may not use a proxy for a sealed class or a class with any sealed or non-virtual methods.

Finally, if your persistent object acquires any resources upon instantiation (eg. in initializers or default constructor), then those resources will also be acquired by the proxy. The proxy class is an actual subclass of the persistent class.

These problems are all due to fundamental limitations in .NET single inheritance model. If you wish to avoid these problems your persistent classes must each implement an interface that declares its business methods. You should specify these interfaces in the mapping file. eg.

<class name="Eg.Cat" proxy="Eg.ICat">
    ......
    <subclass name="Eg.DomesticCat" proxy="Eg.IDomesticCat">
        .....
    </subclass>
</class>

where Cat implements the interface ICat and DomesticCat implements the interface IDomesticCat. Then proxies for instances of Cat and DomesticCat may be returned by Load() or Enumerable(). (Note that Find() does not return proxies.)

ICat cat = (ICat) session.Load(typeof(Cat), catid);
IEnumerable en = session.Enumerable("from cat in class Eg.Cat where cat.Name='fritz'");
en.MoveNext();
ICat fritz = (ICat) en.Current;

Relationships are also lazily initialized. This means you must declare any properties to be of type ICat, not Cat.

Certain operations do not require proxy initialization

NHibernate will detect persistent classes that override Equals() or GetHashCode().

Exceptions that occur while initializing a proxy are wrapped in a LazyInitializationException.

Sometimes we need to ensure that a proxy or collection is initialized before closing the ISession. Of course, we can alway force initialization by calling cat.Sex or cat.Kittens.Count, for example. But that is confusing to readers of the code and is not convenient for generic code. The static methods NHibernateUtil.Initialize() and NHibernateUtil.IsInitialized() provide the application with a convenient way of working with lazyily initialized collections or proxies. NHibernateUtil.Initialize(cat) will force the initialization of a proxy, cat, as long as its ISession is still open. NHibernateUtil.Initialize( cat.Kittens ) has a similar effect for the collection of kittens.

NHibernate can make efficient use of batch fetching, that is, NHibernate can load several uninitialized proxies if one proxy is accessed. Batch fetching is an optimization for the lazy loading strategy. There are two ways you can tune batch fetching: on the class and the collection level.

Batch fetching for classes/entities is easier to understand. Imagine you have the following situation at runtime: You have 25 Cat instances loaded in an ISession, each Cat has a reference to its Owner, a Person. The Person class is mapped with a proxy, lazy="true". If you now iterate through all cats and get the Owner of each, NHibernate will by default execute 25 SELECT statements, to retrieve the proxied owners. You can tune this behavior by specifying a batch-size in the mapping of Person:

<class name="Person" lazy="true" batch-size="10">...</class>

NHibernate will now execute only three queries, the pattern is 10, 10, 5. You can see that batch fetching is a blind guess, as far as performance optimization goes, it depends on the number of unitilized proxies in a particular ISession.

You may also enable batch fetching of collections. For example, if each Person has a lazy collection of Cats, and 10 persons are currently loaded in the ISesssion, iterating through all persons will generate 10 SELECTs, one for every read of Person.Cats. If you enable batch fetching for the Cats collection in the mapping of Person, NHibernate can pre-fetch collections:

<class name="Person">
    <set name="Cats" lazy="true" batch-size="3">
        ...
    </set>
</class>

With a batch-size of 3, NHibernate will load 3, 3, 3, 1 collections in 4 SELECTs. Again, the value of the attribute depends on the expected number of uninitialized collections in a particular ISession.

Batch fetching of collections is particularly useful if you have a nested tree of items, ie. the typical bill-of-materials pattern.

A NHibernate ISession is a transaction-level cache of persistent data. It is possible to configure a cluster or process-level (ISessionFactory-level) cache on a class-by-class and collection-by-collection basis. You may even plug in a clustered cache. Be careful. Caches are never aware of changes made to the persistent store by another application (though they may be configured to regularly expire cached data). In NHibernate 1.0 second level cache does not work correctly in combination with distributed transactions.

By default, NHibernate uses HashtableCache for process-level caching. You may choose a different implementation by specifying the name of a class that implements NHibernate.Cache.ICacheProvider using the property hibernate.cache.provider_class.

<cache 
    usage="read-write|nonstrict-read-write|read-only"                (1)
/>

<class name="Eg.Immutable" mutable="false">
    <cache usage="read-only"/>
    ....
</class>

<class name="eg.Cat" .... >
    <cache usage="read-write"/>
    ....
    <set name="kittens" ... >
        <cache usage="read-write"/>
        ....
    </set>
</class>

The following table shows which providers are compatible with which concurrency strategies.

Refer to Chapter 20, NHibernate.Caches for more details.

Whenever you pass an object to Save(), Update() or SaveOrUpdate() and whenever you retrieve an object using Load(), Find(), Enumerable(), or Filter(), that object is added to the internal cache of the ISession. When Flush() is subsequently called, the state of that object will be synchronized with the database. If you do not want this synchronization to occur or if you are processing a huge number of objects and need to manage memory efficiently, the Evict() method may be used to remove the object and its collections from the cache.

IEnumerable cats = sess.Enumerable("from Eg.Cat as cat"); //a huge result set
foreach( Cat cat in cats )
{
    DoSomethingWithACat(cat);
    sess.Evict(cat);
}

NHibernate will evict associated entities automatically if the association is mapped with cascade="all" or cascade="all-delete-orphan".

The ISession also provides a Contains() method to determine if an instance belongs to the session cache.

To completely evict all objects from the session cache, call ISession.Clear()

For the second-level cache, there are methods defined on ISessionFactory for evicting the cached state of an instance, entire class, collection instance or entire collection role.

Query result sets may also be cached. This is only useful for queries that are run frequently with the same parameters. To use the query cache you must first enable it by setting the property hibernate.cache.use_query_cache=true. This causes the creation of two cache regions - one holding cached query result sets (NHibernate.Cache.IQueryCache), the other holding timestamps of most recent updates to queried tables (NHibernate.Cache.UpdateTimestampsCache). Note that the query cache does not cache the state of any entities in the result set; it caches only identifier values and results of value type. So the query cache is usually used in conjunction with the second-level cache.

Most queries do not benefit from caching, so by default queries are not cached. To enable caching, call IQuery.SetCacheable(true). This call allows the query to look for existing cache results or add its results to the cache when it is executed.

If you require fine-grained control over query cache expiration policies, you may specify a named cache region for a particular query by calling IQuery.SetCacheRegion().

IList blogs = sess.CreateQuery("from Blog blog where blog.Blogger = :blogger")
    .SetEntity("blogger", blogger)
    .SetMaxResults(15)
    .SetCacheable(true)
    .SetCacheRegion("frontpages")
    .List();

If the query should force a refresh of its query cache region, you may call IQuery.SetForceCacheRefresh() to true. This is particularly useful in cases where underlying data may have been updated via a seperate process (i.e., not modified through NHibernate) and allows the application to selectively refresh the query cache regions based on its knowledge of those events. This is an alternative to eviction of a query cache region. If you need fine-grained refresh control for many queries, use this function instead of a new region for each query.