We're in the home stretch now. Just two more days until this ColdFusion 9 caching series is finished. Today we're going to look at code that retrieves the server-wide Ehcache settings. But before we examine the code we need to first know where the cache settings are and what they mean.

Installations of ColdFusion 9 include an Ehcache configuration file called ehcache.xml. This file is located where ColdFusion 9 is installed in the directory {cfroot}/WEB-INF/cfusion/lib/. Here's a screenshot showing the location on my Mac.

If you open this XML file you'll see a lot of configuration settings for the built-in version of Ehcache. These include settings for cache listeners, cache replication via RMI, JGroups, and JMS, clustering settings, and properties for the default cache. Nearly all the contents of ehcache.xml are outside the scope of this blog post with the exception of configuring cache regions. If you scroll to the very bottom of the file you'll see the settings for the default cache region which has the implicit name "default." Every ColdFusion installation defines these defaults which govern the behavior of template and object cache in your applications. In other words, each ColdFusion Application (Application scope) has it's own template and object cache, which are created from these settings. The name for the caches are created based on the Application name in the form appnameTEMPLATE and appnameOBJECT. If you write code that isn't part of an application (Application.cfc or Application.cfm) or where the application name isn't defined, the cache for that set of code will be shared among all other unnamed applications. It's obviously advisable to set an application name.

Here's what the default configuration looks like.


You can override these defaults by changing values of the properties (and restarting ColdFusion) or by creating additional named cache regions. To create a new cache region you create a new block of cache settings above or below the default block. Make sure you restart your ColdFusion server after adding or changing a cache region. Here's an example of a user added cache region.


Some of these cache settings may be self-explanatory but let's take a look at their definitions. Here's what the ColdFusion documentation has to say about the settings, with a couple of my comments sprinkled throughout.

The following attributes are required:

  • name - Sets the name of the cache. This is used to identify the cache. It must be unique.
  • maxElementsInMemory - Sets the maximum number of objects that will be created in memory.
  • maxElementsOnDisk - Sets the maximum number of objects that will be maintained in the DiskStore. The default value is zero, meaning unlimited.
  • eternal - Sets whether elements are eternal. If eternal, timeouts are ignored and the element is never expired. (Aaron's note: In most cases setting eternal to true is probably not a good idea)
  • overflowToDisk - Sets whether elements can overflow to disk when the memory store has reached the maxInMemory limit.

The following attributes and elements are optional:

  • timeToIdleSeconds - Sets the time to idle for an element before it expires. i.e. The maximum amount of time between accesses before an element expires is only used if the element is not eternal. Optional attribute. A value of 0 means that an Element can idle for infinity. The default value is 0.
  • diskPersistent - Whether the disk store persists between restarts of the Virtual Machine. The default value is false. (Aaron's note: Setting this to true allows your cache to survive a server crash or intentional restart. If you manage your cache well your app may perform better with this set to true. Why? Because positive cache performance typically requires the server to "warm up." If cache is warmed before a restart, you can recreate this state quickly when your server is online again.)
  • diskExpiryThreadIntervalSeconds - The number of seconds between runs of the disk expiry thread. The default value is 120 seconds.
  • diskSpoolBufferSizeMB - This is the size to allocate the DiskStore for a spool buffer. Writes are made to this area and then asynchronously written to disk. The default size is 30MB. Each spool buffer is used only by its cache. If you get OutOfMemory errors consider lowering this value. To improve DiskStore performance consider increasing it. Trace level logging in the DiskStore will show if put back ups are occurring.
  • clearOnFlush - Whether the MemoryStore should be cleared when flush() is called on the cache. By default, this is true i.e. the MemoryStore is cleared.
  • memoryStoreEvictionPolicy - Policy would be enforced upon reaching the maxElementsInMemory limit. Default policy is Least Recently Used (specified as LRU). Other policies available - First In First Out (specified as FIFO) and Less Frequently Used (specified as LFU).

Now that we know where the ehcache.xml file lives and what the cache region settings mean, let's take a look at code that will retrieve these settings.

<!--- Show the properties for both the Object cache and the Template cache. --->
<cfdump var="#cacheGetProperties()#">

Wow, that was easy! The cacheGetProperties() function is a documented function that accepts one optional parameter, the type of cache properties you want to retrieve. This can be either template or object. If you leave the parameter out of the function call, as I did in the above example, cache properties for both template and object cache will be returned. Note, this function cannot be used to retrieve properties for user defined cache regions such as my customCacheRegion above. Also, caching functions like cacheGet() and cachePut() only work with the default cache region. These functions don't have a cache key as an optional argument keeping you from targeting anything with a custom name. Both of these situations are rather unfortunate and something I hope the ColdFusion team fixes in a future update. Here's what the above <cfdump> displays in a browser.

That's pretty much it for retrieving the default cache properties. Join me tomorrow when I'll show you how to programmatically alter the default cache properties at runtime.

Click here to download the code mentioned in this post.

Aaron West's Gravatar
About this post:

This entry was posted by Aaron West on November 29, 2009 at 2:18 PM. It was filed in the following categories: ColdFusion. It has been viewed 12775 times and has 0 comments.

13 related blog entries

0 Responses to 14 Days of ColdFusion 9 Caching: Day 13 - Retrieving the Server Cache Properties