NHibernate blog : caches

NHibernate Caches 2.1.0GA

Fabio Maulo — Sun, 19 Jul 2009 14:24:00 GMT

NHibernate Caches 2.1.0GA was released today.

Enjoy it together with NHibernate2.1.0GA.

NHibernate Configuration

Fabio Maulo — Fri, 17 Jul 2009 21:30:00 GMT

Perhaps not so many people know in how many ways NH can be configured since NH2.0.0. In this post I’ll try to summarize some one before implement Loquacious configuration in NH3.0.0.

Xml (default)

The xml way is the most common used so only some little notes are needed here.

Inside the root node, hibernate-configuration, you can configure 3 “things”: the bytecode provider, the reflection optimizer usage and the session-factory.

The bytecode provider and the reflection optimizer can be configured only and exclusively inside the application config (app.config or web.config); outside application config the two configuration are ignored. If you need to configure the bytecode provider or the reflection optimizer the minimal configuration required, inside app.config is, for example:

    <hibernate-configuration xmlns="urn:nhibernate-configuration-2.2">
   <bytecode-provider type="null"/>
   <reflection-optimizer use="false"/>
</hibernate-configuration>

As you can see the session-factory section is not present (for this reason I wrote “minimal”).

The session-factory configuration can be wrote inside or outside the app.config or even in both (inside and outside). The minimal configuration required is:

<hibernate-configuration xmlns="urn:nhibernate-configuration-2.2">
<session-factory name="NHibernate.Test">
   <property name="dialect">NHibernate.Dialect.MsSql2005Dialect</property>
   <property name="proxyfactory.factory_class">
       NHibernate.ByteCode.LinFu.ProxyFactoryFactory, NHibernate.ByteCode.LinFu
   </property>
</session-factory>
</hibernate-configuration>

As you can see there are only two properties and, as is, you can’t use this configuration because there isn’t the connection string.

If you want you can write the minimal configuration inside your application config and merge/override it with the configuration wrote in an external file. I’m using this technique everywhere for tests purpose because test suite and production has some common configuration and some other different configuration (for example the current_session_context_class). The code to merge/override the configuration inside app.config with the configuration outside the app.config is:

var configuration = new Configuration()
.Configure()
.Configure(yourNhConfPath);

After this two lines you can continue configuring NHibernate by code (even using the method chaining).

Xml (custom configSections)

As usual in NHibernate, you can have a custom Schema for the hibernate-configuration section. The way is simple:

    <configSections>
   <section name="hibernate-configuration"
            type="YourCompany.YourProduct.YourConfigurationSectionHandler, YourAssembly" />
</configSections>

The restriction is :

The section name must be “hibernate-configuration”.
Your ConfigurationSectionHandler must implements IHibernateConfiguration.

The reason to write a custom ConfigurationSectionHandler, more than implement something related to Enterprise Library-Configuration Application Block, can be related with the need of some framework (your imagination may work here).

Xml : The mystery

In these year I saw :

everybody using property
somebody using the mapping section
few people using the event and/or the listener sections
absolutely nobody using the class-cache nor collection-cache sections

The two sections related with the second-level-cache configuration are very useful. In general the configuration of the cache is something happening after wrote all mappings; you may have a tests suite that must work without cache and another test suite to check the behavior using second-level-cache. Even if I have changed NH2.1.0 to ignore the cache configuration, inside a class-mapping, when the cache.use_second_level_cache is set to false, the right place to configure the cache, of each class/collection, is inside the session-factory-configuration and not inside the class-mapping itself; you don’t need to modify a tested mapping only because cache and you don’t need to re-deploy class-mappings only because you need to modify/add the cache configuration of a class/collection.

Configuration by code

The whole configuration via XML can be done by pure .NET code.

The bytecode provider can be set before create an instance of the Configuration class:

Environment.BytecodeProvider = new EnhancedBytecode(container);
var cfg = new Configuration();

To set properties in a no strongly typed way (mean by strings) :

configuration.SetProperty(Environment.GenerateStatistics, "true");
configuration.SetProperty(Environment.BatchSize, "10");

To set listeners in a no strongly typed way (mean by strings) :

configuration.SetListeners(ListenerType.PreInsert,
new[] { "YourCompany.YourProduct.YourListener, YourAssembly" });

To set listeners in strongly typed way :

configuration.EventListeners.DeleteEventListeners =
new[] {new ResetReadOnlyEntityDeleteListener()}
.Concat(listeners.DeleteEventListeners).ToArray();

To add class-mappings the Configuration class has various Add* methods :

AddAssembly(Assembly assembly)
AddAssembly(string assemblyName)
AddClass(System.Type persistentClass)
AddDirectory(DirectoryInfo dir)
AddFile(string xmlFile)
AddFile(FileInfo xmlFile)
AddXmlReader(XmlReader hbmReader)
AddXml(string xml)
AddResource(string path, Assembly assembly)
...
...

Note AddXml(string xml) or AddXmlString(string xml) mean that you can add a mapping created at run-time:

string hbm =
@"<?xml version='1.0' encoding='utf-8' ?>
           <hibernate-mapping xmlns='urn:nhibernate-mapping-2.2'
               namespace='NHibernate.DomainModel'
               assembly='NHibernate.DomainModel'>
               <class name='A' persister='A'>
                   <id name='Id'>
                       <generator class='native' />
                   </id>
               </class>
           </hibernate-mapping>";

Configuration cfg = new Configuration();
cfg.AddXmlString(hbm);

To set second-level-cache configuration for classes and collections:

SetCacheConcurrencyStrategy(string clazz, string concurrencyStrategy)
SetCacheConcurrencyStrategy(string clazz, string concurrencyStrategy, string region)
SetCollectionCacheConcurrencyStrategy(string collectionRole, string concurrencyStrategy)

The trick of custom Dialect

Few people know this trick (perhaps only the one I’m seeing everyday in the mirror).

Each Dialect has the ability to define its own DefaultProperties. Inside the core, so far, we are using the DefaultProperties property only for few purpose (for example to define the default driver):

DefaultProperties[Environment.ConnectionDriver] =
"NHibernate.Driver.SqlClientDriver";

If you are not so scared by inherit from a dialect implemented in the core and extends it to register some functions or to change some behavior, you can use it even to define default properties:

public class YourCustomDialect : MsSql2005Dialect
{
public YourCustomDialect()
{
   DefaultProperties[Environment.QuerySubstitutions] =
       "wahr 1, falsch 0, ja 'J', nein 'N'";
   DefaultProperties[Environment.ConnectionString] =
       "your connection string";
   DefaultProperties[Environment.BatchSize] = "50";
}
}

What we saw

Since NH2.0.0GA, you have three or four ways to configure NHibernate with merge/override from different sources.

NHibernate Caches 2.1.0CR1

Fabio Maulo — Sun, 05 Jul 2009 15:15:00 GMT

NHibernate Caches 2.1.0CR1 was released today.

Download NHibernate Caches 2.1.0CR1.

Enjoy it together with NHibernate2.1.0.

NHibernate Cache Providers 2.1.0Beta1

Fabio Maulo — Sun, 21 Jun 2009 15:52:00 GMT

NHibernate Caches 2.1.0Beta1 was released today.

Download NHibernate Caches 2.1.0Beta1.

Enjoy it together with NHibernate2.1.0.

NHibernate Cache Providers 2.1.0Alpha1

Fabio Maulo — Sun, 07 Jun 2009 17:03:00 GMT

NHibernate Caches 2.1.0Alpha1 was released today.

Download NHibernate Caches 2.1.0Alpha1.

Enjoy it together with NHibernate2.1.0.

NHibernate 2nd Level Cache

Ayende — Fri, 24 Apr 2009 12:28:00 GMT

NHibernate has a builtin support for caching. It sounds like a trivial feature at first, until you realize how significant it is that the underlying data access infrastructure already implements it. It means that you don’t have to worry about thread safety, propagating changes in a farm, built smart cache invalidation strategies or deal with all of the messy details that are usually along for the ride when you need to implement a non trivial infrastructure piece.

And no, it isn’t as simple as just shoving a value to the cache.

I spent quite a bit of time talking about this here, so I wouldn’t go about all the cache internals and how they work, but I’ll mention the highlights. NHibernate internally has the following sub caches:

Entity Cache
Collection Cache
Query Cache
Timestamp Cache

NHibernate make use of all of them in a fairly complex way to ensure that even though we are using the cache, we are still presenting a consistent view of the cache as a mirror of the database. The actual details of how we do it can be found here.

Another thing that NHibernate does for us when we update the cache is try to maintain the consistent view of the world even when using replicated caches used in a farm scenarios. This requires some support from the caching infrastructure, such as the ability to perform a hard lock on the values. Of the free caching providers for NHibernate, only Velocity support this, which means that when we evaluate a cache provider for NHibernate to be used, we need to take this into account.

In general, we can pretty much ignore this, but it does have some interesting implications with regards to what are the isolation guarantees that we can make based on the cache implementation that we use, the number of machines we use and the cache concurrency strategy that we use.

You can read about this here and here.

One thing that you should be aware of is that NHibernate currently doesn’t have transaction cache concurrency story, mostly because there is no cache provider that can give us that. As such, be aware that if you require serializable isolation level to work with your entities, you cannot use the 2nd level cache. The 2nd level cache currently guarantee only read committed (and almost guarantee repeatable read if this is the isolation level that you use in the database). Note that this guarantee is made for read-write cache concurrency mode only.

Tuning NHibernate: Tolerant QueryCache

Fabio Maulo — Sat, 18 Apr 2009 00:05:00 GMT

[From My Blog]

Before reading this post you should know something about QueryCache and its imply tuning NH.

Resuming:

Using IQuery.SetCacheable(true) you can put/get the entirely result of a query from the cache.
The cache is automatically invalidated when the query-space change (mean that the cache will be throw when an Insert/Update/Delete is executed for one of the Tables involved in the query).
Using IQuery.SetCacheMode(CacheMode.Refresh) you can force the cache refresh (for example if you need to refresh the cache after a Delete/Insert).

The Case

(the picture is a e-Bay snapshot)

Take a look to the left side. Near each option you can see a number and I’m pretty sure that it not reflect exactly the state in the DB. That number is only “an orientation” for the user probably calculated few minutes before.

Now, think about the SQLs, behind the scene, and how many and how much heavy they are. A possible example for “Album Type”, using HQL, could look like:

select musicCD.AlbumType.Name, count(*) from MusicCD musicCD where musicCD.Genre = ‘Classical’ group by musicCD.AlbumType.Name

How much time need each “Refine search” ?

Ah… but there is no problem, I’m using NHibernate and its QueryCache… hmmmm…

Now, suppose that each time you click an article you are incrementing the number of visits of that article. What happen to your QueryCache ? yes, each click the QueryCache will be invalidated and thrown (the same if some users in the world insert/update/delete something in the tables involved).

The Tolerant QueryCache abstract

The Tolerant QueryCache should be an implementation of IQueryCache which understands, through its configuration properties, that updates, to certain tables, should not invalidate the cache of queries based on those tables.

Taken the above example mean that an update to MusicCD does not invalidate all “Refine search” queries, if we are caching those statistics heavy queries.

The integration point

Well… at this point you should know how much NHibernate is extensible and “injectable”.

For each cache-region NHibernate create an instance of IQueryCache trough an implementation of IQueryCacheFactory and, as you could imagine, the IQueryCacheFactory concrete implementation can be injected trough session-factory configuration.

<property name="cache.query_cache_factory">YourQueryCacheFactory</property>

At this point we know all we should do to have our TolerantQueryCache :

Some configuration classes to configure tolerated tables for certain regions.
An implementation of IQueryCacheFactory to use the TolerantQueryCache for certain regions.
The implementation of TolerantQueryCache.

The Test

Here is only the integration test; all implementations are available in uNhAddIns.

Domain

public class MusicCD
{
 public virtual string Name { get; set; }
}

public class Antique
{
 public virtual string Name { get; set; }
}

<class name="MusicCD" table="MusicCDs">
 <id type="int">
     <generator class="hilo"/>
 </id>
 <property name="Name"/>
</class>

<class name="Antique" table="Antiques">
 <id type="int">
     <generator class="hilo"/>
 </id>
 <property name="Name"/>
</class>

Configuration

public override void Configure(NHibernate.Cfg.Configuration configuration)
{
 base.Configure(configuration);
 configuration.SetProperty(Environment.GenerateStatistics, "true");
 configuration.SetProperty(Environment.CacheProvider,
     typeof(HashtableCacheProvider).AssemblyQualifiedName);

 configuration.QueryCache()
     .ResolveRegion("SearchStatistics")
     .Using<TolerantQueryCache>()
     .TolerantWith("MusicCDs");
}

The configuration is only for the “SearchStatistics” region so others regions will work with the default NHibernate implementation. NOTE: the HashtableCacheProvider is valid only for tests.

The test

// Fill DB
SessionFactory.EncloseInTransaction(session =>
{
 for (int i = 0; i < 10; i++)
 {
     session.Save(new MusicCD { Name = "Music" + (i / 2) });
     session.Save(new Antique { Name = "Antique" + (i / 2) });
 }
});

// Queries
var musicQuery =
 new DetachedQuery("select m.Name, count(*) from MusicCD m group by m.Name")
 .SetCacheable(true)
 .SetCacheRegion("SearchStatistics");

var antiquesQuery =
 new DetachedQuery("select a.Name, count(*) from Antique a group by a.Name")
 .SetCacheable(true)
 .SetCacheRegion("SearchStatistics");

// Clear SessionFactory Statistics
SessionFactory.Statistics.Clear();

// Put in second-level-cache
SessionFactory.EncloseInTransaction(session =>
{
 musicQuery.GetExecutableQuery(session).List();
 antiquesQuery.GetExecutableQuery(session).List();
});

// Asserts after execution
SessionFactory.Statistics.QueryCacheHitCount
 .Should("not hit the query cache").Be.Equal(0);

SessionFactory.Statistics.QueryExecutionCount
 .Should("execute both queries").Be.Equal(2);

// Update both tables
SessionFactory.EncloseInTransaction(session =>
{
 session.Save(new MusicCD { Name = "New Music" });
 session.Save(new Antique { Name = "New Antique" });
});

// Clear SessionFactory Statistics again
SessionFactory.Statistics.Clear();

// Execute both queries again
SessionFactory.EncloseInTransaction(session =>
{
 musicQuery.GetExecutableQuery(session).List();
 antiquesQuery.GetExecutableQuery(session).List();
});

// Asserts after execution
SessionFactory.Statistics.QueryCacheHitCount
 .Should("Hit the query cache").Be.Equal(1);

SessionFactory.Statistics.QueryExecutionCount
 .Should("execute only the query for Antiques").Be.Equal(1);

Fine! I have changed both tables but in the second execution the result for MusicCD come from the Cache.

Code available here.

NH.Caches Beta1 Is Out!

Diego Jancic — Sun, 31 Aug 2008 20:21:00 GMT

The first beta version of NHibernate.Caches is ready to be downloaded from SourceForge! (Download)

To be honest, the most used caches haven't major changes, just some bug fixes, and a bit of refactoring. But, there are still some interesting things that make this version "a thing that every developer must-have", let's say:

- Works with NH 2.0.0 GA! Not yet using it ? Check out what are you missing: http://www.hibernate.org/357.html#A14

- Two new providers were added:

- indeXus.net Shared Cache - http://www.sharedcache.com

- Microsoft Distributed Cache (CodeName "Velocity") - http://msdn.microsoft.com/en-us/data/cc655792.aspx

And, really thanks to dabuddhaman for the contributions!