NHibernate has a first level or session level cache which is used by default. Each session contains its own session level cache which is not shared with other sessions. This cache is disposed whenever the session is closed. However NHibernate allows to use second level, across session cache which spans across sessions life time and can be shared by multiple sessions.

 

NCache provides a second level or process level cache for NHibernate by implementing NHibernate's ICacheProvider and ICache interfaces. This enables NCache to be used as NHibernate second cache in existing NHibernate application without any code change. All that’s needed is to change NHibernate configuration file to plug-in NCache as cache provider and distributed caching can be used.

 

Second level cache can be configured by  enabling the use of second level cache and configuring second level cache provider in NHibernate configurations.

 

Configuring NHibernate Application to use NCache as Second Level Cache

 

 

<property name="cache.provider_class">      Alachisoft.NCache.Integrations.NHibernate.Cache.NCacheProvider,      Alachisoft.NCache.Integrations.NHibernate.Cache</property>

 

cache.provider_class: This option lets the user specify NCache as 2^nd level cache provider. The user needs to mention two classes which implement ICacheProvider and ICache interfaces respectively. This is how NHibernate knows how to call this second level cache.

 

 

 

<property name="cache.use_second_level_cache">true</property>

 

 

<appSettings>

      ....

    <add key="ncache.application_id" value="myapp" />

      ....

  </appSettings>

 

Configuring Cacheable Objects

 

Enabling the use of second level cache does not cache each class object by default. Instead classes needed to be cached are to be marked cacheable in class mapping (.hbm.xml) file. To mark a class cacheable add the following tag in class's configuration:

 

    <cache usage="read-write" region ="AbsoluteExpirationRegion"/>

 

In the above tag, properties usage and region can be changed.

 

Region specifies the name of second level cache region to be used for this class objects. If no region is specified, fully qualified class name will be used as region name with default region configurations.

 

Usage specifies caching concurrency  strategy to be used for this class. NHibernate allows the following three concurrency strategies to be used for caching:

 

 

Configuring Cache Regions

 

NHibernate uses cache regions to store objects. NCache allows cache regions to be configured with different properties. For this purpose NCache has a configuration file named "NCacheNHibernate.xml", which contains all regions’ configurations and other related configurations used by NCache. This file can be placed at root directory of application or in config folder of NCache Installation directory.

 

Following is a sample configuration file:

 

<configuration>

<application-config application-id="myapp" enable-cache-exception="true"

default-region-name="default" key-case-sensitivity="false">

    <cache-regions>

          <region name="AbsoluteExpirationRegion" cache-name="mycache" priority="Default" expiration-type="sliding" expiration-period="180" />

          <region name="default" cache-name="mycache" priority="default" expiration-type="none" expiration-period="0" />

    </cache-regions>

    <database-dependencies>

          <dependency entity-name="nhibernator.BLL.Customer" type="oledb" sql-statement="select ContactName from dbo.Customers where CustomerID =?" cache-key-format="depdency.customer:[pk]"/>

    </database-dependencies>

 

</application-config>

</configuration>

 

Multiple application configurations can be specified in NCacheNHibernate.xml. Any NHibernate application will use one of the specified configuration based on the application-id specified in applications app.config/web.config file.

 

Following are the configurable options in application-config section.

 

Member	Description
application-id	This option let the user specify a unique id for current application-config. This id is used to select appropriate configuration for a particular application.
enable-cache-exception	Identifies whether the exceptions if occurred in NCache will be propagated to NHibernate provider.
default-region-name	Allows to specify a default region for the application. If a particular region's configurations are not found, default region configurations will be used. Specified default region configuration must exist in cache-regions section.
key-case-sensitivity	This option allows to specify whether cache keys will be case sensitive or not. This option has to be configured according to database used. If database is case-sensitive set this option true, otherwise false.
cache-regions	This sections lets the user configure multiple cache regions for NHibernate application. Each region's configuration is specified in region tag.
region	This tag contains the configurations for one particular region. Following options can be configured for any particular region. name: Each region is identified by its name. Name of the region should be unique. cache-name: This option allows specifying  NCache's cache name to be used for this region. priority: The priority the user wants to use for cached items. The possible values are : ·     Default ·     Low ·     BelowNormal ·     Normal ·     AboveNormal ·     High ·     NotRemovable expiration-type: This options allows to specify type of expiration for any item in this region. Possible values are absolute/sliding/none. expiraion-period: Allows to specify expiration period if absolute/sliding expiration is configured. Its value should be greater than 0.
database-dependencies	It lets the user specify database dependencies for current NHibernate application. dependency: Each dependency is configured in a dependency tag. Multiple tags can be configured for multiple dependencies. The following options can be configured for each dependency. entity-name: Dependencies are added based on the fully qualified name of classes. This option allows to specify name of class for which current dependency is to be added. Any entity can have maximum one dependency. type: Allows to specify database dependency type. Possible values are sql/oracle/oledb. Since NCache provider uses connection string specified in NHibernate's configuration, use dependency type appropriate to connection string. sql-statement: Allows to specify sql statement to be used for building NCache's database dependency. cache-key-format: This option is used to configure cache key format for any item of current entity type. Cache key format should include "[pk]" in it, which will be replaced with the primary key of record. cache-key-format may also include "[en]" which will be replaced with entity name. Default value of cache key format is "NHibernateNCache:[en] #[pk]". Same cache key format should be used while writing database trigger incase of oledb database dependency. See NCache help for writing database trigger for oledb dependency. composite-key-separator: If the records of current entity have composite key as primary key, cache-key is formed by combining all keys separated by composite-key-separator. composite-key-separator must be of one character length. Its default value is "$".

 

 

Using Query Caching

 

NHibernate also provides a feature of query caching. Enabling query caching caches queries made by NHibernate to database, along with query result sets. Query caching makes use of second level cache to store queries, so that whenever the same query is needed to be executed again, it can be fetched from cache.

 

Any object retrieved as a result of query are cached to their respective regions, therefore objects must be marked as cacheable for efficient use of query caching. However query along with the primary keys of result sets is stored in a default query region named NHibernate.Cache.StandardQueryCache.

 

Since not every query's results remain same for a period of time. Therefore query caching should only be used with queries whose results are likely to be changed less frequently.

 

How to Enable Query Caching

 

To enable query caching, add the following property in NHibernate configuration section's session-factory tag:

 

    <property name="cache.use_query_cache">true</property>

 

Enabling query cache does not cache each query by default. Instead queries needed to be cached are to be set cacheable in code. To set a query cacheable, call SetCacheable(true) function of query while creating query, e.g.,

 

IQuery qry = session.CreateQuery("from Customer c").SetCacheable(true);

 

 

See Also

NHibernate Overview | Entity Framework Caching Integration | Memcached |Client Side API Programming | Server Side API Programming | Client Side ASP.NET Features

---

Send comments on this topic.