For my final post in this 14 day caching series I want to look at setting the server cache properties at runtime. I showed how to retrieve the cache settings in yesterday's post using the cacheGetProperties() function. To set the cache properties for either the template or object cache you use the cacheSetProperties() function. Consider the following code.

<cfset myProps = StructNew()>
<cfset myProps.diskStore = "/Users/aaron"> <!--- Was listed in the docs during beta, removed when CF was publicly released, and now it's there again. Including the line in your code doesn't cause any problems but it doesn't appear to do anything either. --->
<cfset myProps.diskPersistent = "true">
<cfset myProps.eternal = "false">
<cfset myProps.maxElementsInMemory = "5000">
<cfset myProps.maxElementsOnDisk = "100000">
<cfset myProps.memoryEvictionPolicy = "FIFO">
<cfset myProps.objectType = "Object">
<cfset myProps.overflowToDisk = "true">
<cfset myProps.timeToIdleSeconds = "86400">
<cfset myProps.timeToLiveSecond = "86400">

<cfdump var="#cacheGetProperties("Object")#">

<!--- Update the cache properties. --->
<cfset cacheSetProperties(myProps)>

<cfdump var="#cacheGetProperties("Object")#">

<!--- Put a sample item into Object cache. --->
<cfset cachePut("wt-14-cache", "This is a cached string.")>

The cacheSetProperties() function is about as basic as it gets. It accepts a single structure that includes properties that match those defined in the ehcache.xml configuration file. In the code above I create this structure and set some of the properties, such as diskPersistent and memoryEvictionPolicy, to values different from the defaults. I target the object cache by setting the objectType property to "Object." I then use the cacheGetProperties() function to retrieve the current settings of the object cache and display them in a <cfdump>. Using the cacheSetProperties() function I then update the properties of the object cache by passing the function the structure created earlier. Finally, I retrieve the object cache properties a second time and display them in the browser to be sure they have changed. The output of the code is shown below. Notice how four properties have been changed.

Here are a few things to keep in mind when using cacheGetProperties() and cacheSetProperties().

  • the functions only work on the default cache region defined in ehcache.xml. Until Adobe adds an optional cache key parameter you cannot target a region with a custom name.
  • changes you make with cacheSetProperties() must target either the template or object "objecttype."
  • changes you make take affect immediately but will not survive a ColdFusion server restart. To change the settings permanently, change the property values in the ehcache.xml file.
  • the diskStore property was listed in the docs during beta, removed when CF was publicly released, and now it's there again. Including the line in your code doesn't cause any problems but it doesn't appear to do anything either.
  • [fun tip/info] the timeToIdoleconds property is intentionally misspelled in my download example code but corrected above. During the ColdFusion beta the property had to be misspelled or you would get an error. The same was true for the word "idol" versus "idle." In the public release of ColdFusion you can spell the property timeToIdoleconds, timeToIdolSeconds, or timeToIdleSeconds. All three will work.

Whew, I'm done!! With 14 days of blogging about ColdFusion 9 caching that is. It's been a crazy two weeks of blogging every day, something I've never done. In fact, I actually wrote 17 posts; three weren't about caching. Will I do it again? Hopefully not anytime soon. It was a lot of fun to put together all the posts but it was tons of work, much more than I had imagined. There's a plethora of content about caching and I didn't cover all of it. Most of the posts I wrote were pretty short so I could keep the content bite size and easily consumable. I stayed away (mostly) from a lot of the strategy around caching but if you are interested in that type of content I recommend you read Rob's posts. He goes into more detail than I did with some of his posts and he definitely gets more into the strategy of caching.

Nevertheless, if you read all 14 blog posts you should win an award or something. Please comment to let me know if you read them all! And even if you didn't, thanks for reading one or more of them. It's been fun and I really hope you were able to get something out of the content. Happy caching!

Click here to download the code mentioned in this post.

NOTE: The code for this example was originally created by Rob Brooks-Bilson and was included in his Adobe MAX 2009 presentation. I've altered it some for the purposes of this blog post.

Aaron West's Gravatar
About this post:

This entry was posted by Aaron West on November 30, 2009 at 8:00 AM. It was filed in the following categories: ColdFusion. It has been viewed 7975 times and has 3 comments.

13 related blog entries

3 Responses to 14 Days of ColdFusion 9 Caching: Day 14 - Setting the Server Cache Properties

  1. Just finished reading the series (got interrupted along the way). Really awesome job. Thanks for taking the time to do this.

  2. Thanks Ben! Much appreciated!

  3. Hi Aaron,

    Very very great article!
    I just start to use ehcache. Before I used application scope to save objects or html rendering. I decided to make the switch in order to have more control and visibility on what is cached and how!

    I know this post is a little bit old but I want to thank you for these posts. Very helpful!