Caching

Objects that are loaded from the database are always cached in the ORM Session as long as the session is open. When EntityLoad is called to retrieve an object in a session for the first time, ORM fetches the data from the database and constructs the object. In any subsequent call to load the same object in the same session, ORM fetches the object from the session cache. To forcefully retrieve the object from the database, EntityReload should be called on the object.

For more details on ORM Sessions and its lifecycle, see ORM session management and Architecture.

ColdFusion provides the ability to store the data that is retrieved from the database in secondary cache. The contents in secondary cache live longer than the life-time of a session. It can also be the life-time of the process or in-definite (disk-caching), depending on the ability of the secondary cache provider. The cache can also be used in a distributed environment depending on the ability of the secondary cache provider.

An important difference between session level cache and secondary level cache is that the session level caches the whole object but the secondary level caches only the data.

Secondary level cache can be leveraged by using an external cache provider with ColdFusion ORM. EHCache, JBossCache, OSCache, SwarmCache, and Tangosol Coherence Cache are some popular secondary cache providers, which can be plugged into Hibernate.

ColdFusion uses EHCache as the default secondary cache provider. EHCache is a distributed caching solution that supports memory and disk-based caching. EHCache can be configured using a configuration file. Different cache regions can be defined in the configuration file. Each cache region has its own configuration that specifies details including the number of elements it can store, eviction policy, time to live (ttl), and idle time.

ehcache.xml is available in the following location: CF_root\lib\. For details of the properties in the ehcache.xml, refer to the documentation available at the following URL:

http://ehcache.org/

The following is a sample EHCache configuration file (ehcache.xml):

<ehcache> 
    <diskStore path="java.io.tmpdir"/> 
    <defaultCache 
        maxElementsInMemory="10000" 
        eternal="false" 
        timeToIdleSeconds="120" 
        timeToLiveSeconds="120" 
        overflowToDisk="true" 
        diskPersistent="false" 
        diskExpiryThreadIntervalSeconds="120" 
        memoryStoreEvictionPolicy="LRU" 
        />        
    <cache name="Artist" 
        maxElementsInMemory="20" 
        eternal="true" 
        overflowToDisk="false" 
        /> 
</ehcache>

To use secondary cache, you must configure the following settings in the application:

• ormsettings.secondarycacheenabled

  This setting defines whether the secondary cache would be used by the application. By default, this is set to false.

• ormsettings.Cacheprovider

  This setting defines the cache provider that needs to be used for secondary cache. This defaults to EHCache. The other values for this setting are JBossCache, OSCache, SwarmCache and Hashtable. You can also specify the fully qualified class name of the cache provider.

• ormsettings.cacheconfig

  This setting defines the configuration file required by the secondary cache provider. For example, EHCache requires EHCache.xml that defines the configuration settings for the secondary cache. Specify the path to the XML file in this setting. If this setting is not defined, cache provider uses its default configuration.

After you have configured the secondary cache, it is critical to identify the objects in your application that can be cached because the data cached by secondary cache is shared by all the sessions of an application. Typically, caching should be enabled for a CFC that represents:

• Data that changes rarely

• Data that is local to an application and is not modified by other applications

• Non-critical data

For each type of object that needs to be cached, you also need to decide the access strategies. ORM provides the following cache strategies that you can use for your objects:

• read-only

  This strategy is useful for data that is read frequently but never updated. This is the best performing cache strategy.

• nonstrict-read-write

  This strategy is useful for data that is updated occasionally. Typically, it is very unlikely that two transactions would update the same object simultaneously.

• read-write

  This strategy may be appropriate if your data needs to be updated. It carries more overhead than the two preceding strategies.

• Transactional

  This strategy provides the support for transactional cache. It can only be used if the cache provider is transaction aware.

Support for these strategies depend on the cache provider. Not all the cache providers support all the cache strategies. For more information on these strategies, see:

www.hibernate.org/hib_docs/reference/en/html/performance-cache.html

The secondary cache can cache the following types of data.

• Persistent object data

• Persistent object association

• Query data

Except in cacheSetProperties and cacheGetProperties, user-defined caches are supported in all caching functions.

Edit ehCache.xml (cfroot/lib)to set the properties for user-defined caches as shown in the following example:

<!--- item to put in user-defined cache ---> 
<cfset currentTime = Now()> 
<!--- put item in user-defined cache ---> 
<cfset timeToLive=createtimespan(0,0,0,30)> 
<cfset timeToIdle=createtimespan(0,0,0,30)> 
<cfset customCache = "usercache"> 
<cfset id = "cache1"> 
<cfset cachePut(id,currentTime,timeToLive,timeToIdle,customCache)> 
<!-- list items in the cache ---> 
List Items in cache:  
<cfset cacheIds = cacheGetAllIds(customCache)> 
<cfdump var="#cacheIds#"><br> 
<!--- print cache data ---> 
<cfset cachedData = cacheGet(id,customCache)> 
<cfoutput>#cachedData#</cfoutput> 
<!--- print cache metadata ---> 
Cache metadata: 
<cfset mdata = cacheGetMetadata(id,"object",customCache)> 
<cfdump var="#mdata#"> 
<!--- clear user-defined cache ---> 
<cfset cacheRemove(ArrayToList(cacheIds),true,customCache)>