Using Coldfusion and Ehcache

Introduction
Which version of Ehcache comes with which version of ColdFusion?
Which version of Ehcache should I use if I want a distributed cache?
Using Ehcache with ColdFusion 9 and 9.0.1
Switching from a local cache to a distributed cache with ColdFusion 9.0.1
Using Ehcache with ColdFusion 8

Introduction

ColdFusion ships with Ehcache. This page covers integrating ColdFusion versions 9, 9.0.1, and 8 with Ehcache.

Which version of Ehcache comes with which version of ColdFusion?

The following versions of ColdFusion ship with Ehcache:

ColdFusion 9.0.1 includes Ehcache 2.0 out-of-the-box
ColdFusion 9 includes Ehcache 1.6 out-of-the-box
ColdFusion 8 caching was not built on Ehcache, but Ehcache can easily be integrated with a CF8 application (see below).

Which version of Ehcache should I use if I want a distributed cache?

Ehcache is designed so that applications written to use it can easily scale out. A standalone cache (the default in ColdFusion 9) can easily be distributed. A distributed cache solves database bottleneck problems, cache drift (where the data cached in individual application server nodes becomes out of sync), and also (when using the recommended 2-tier Terracotta distributed cache) provides the ability to have a highly available, coherent in-memory cache that is far larger than can fit in any single JVM heap. See Getting Started for details.

Note: Ehcache 1.7 and higher support the Terracotta distributed cache out of the box. Due to Ehcache's API backward compatibility, it is easy to swap out older versions of ehcache with newer ones to leverage the features of new releases.

Using Ehcache with ColdFusion 9 and 9.0.1

The ColdFusion community has actively engaged with Ehcache and have put out lots of great blogs. Here are three to get you started. For a short introduction, see Raymond Camden's blog. For more in-depth analysis, see Rob Brooks-Bilson's nine-part Blog Series or 14 days of ColdFusion caching, by Aaron West, covering a different topic each day.

Switching from a local cache to a distributed cache with ColdFusion 9.0.1

Download the Terracotta kit. Click the link to the open-source kit if you are using open source and get terracotta-<version>-installer.jar.
Install the kit with java -jar terracotta-<version>-installer.jar. We will refer to the directory you installed it into as TCHOME. Similarly, we will refer to the location of ColdFusion as CFHOME. These instructions assume you are working with a standalone server install of ColdFusion; if working with a EAR/WAR install you will need to modify the steps accordingly (file locations may vary and additional steps may be needed to rebuild the EAR/WAR).

Before integrating the distributed cache with ColdFusion, you may want to follow the simple self-contained tutorial which uses one of the samples in the kit to demonstrate distributed caching: http://www.terracotta.org/start/distributed-cache-tutorial
Copy TCHOME/ehcache/lib/ehcache-terracotta-\<version>.jar into CFHOME/lib

Edit the CFHOME/lib/ehcache.xml to add the necessary two lines of config to turn on distributed caching

<terracottaConfig url="localhost:9510"/>
<defaultCache
   ...
   >
           <terracotta clustered="true" />
</defaultCache>

Edit jvm.config (typically in CFHOME/runtime/bin) properties to ensure that coldfusion.classPath (set with -Dcoldfusion.classPath= in java.args) DOES NOT include any relative paths (ie ../ ) - ie replace the relative paths with full paths (This is to work around a known issue in ehcache-terracotta-2.0.0.jar).
Start the Terracotta server in a *NIX shell or Microsoft Windows:
```
$TCHOME/bin/start-tc-server.sh
start-tc-server.bat
```
Note: In production, you would run your servers on a set of separate machines for fault tolerance and performance.
Start ColdFusion, access your application, and see the distributed cache in action.
This is just the tip of the iceberg & you'll probably have lots of questions. Drop us an email to info@terracottatech.com to let us know how you got on, and if you have questions you'd like answers to.

Using Ehcache with ColdFusion 8

To integrate Ehcache with ColdFusion 8, first add the ehcache-core jar (and its dependent jars) to your web application lib directory. The following code demonstrates how to call Ehcache from ColdFusion 8. It will cache a CF object in Ehcache and the set expiration time to 30 seconds. If you refresh the page many times within 30 seconds, you will see the data from cache. After 30 seconds, you will see a cache miss, then the code will generate a new object and put in cache again.

<CFOBJECT type="JAVA" class="net.sf.ehcache.CacheManager" name="cacheManager">
<cfset cache=cacheManager.getInstance().getCache("MyBookCache")>
<cfset myBookElement=#cache.get("myBook")#>
<cfif IsDefined("myBookElement")>
   <cfoutput>
    myBookElement: #myBookElement#<br />
   </cfoutput>
   <cfif IsStruct(myBookElement.getObjectValue())>
           <strong>Cache Hit</strong><p/>
           <!-- Found the object from cache -->
           <cfset myBook = #myBookElement.getObjectValue()#>
   </cfif>
</cfif>
<cfif IsDefined("myBook")>
<cfelse>
<strong>Cache Miss</strong>
   <!-- object not found in cache, go ahead create it -->
   <cfset myBook = StructNew()>
   <cfset a = StructInsert(myBook, "cacheTime", LSTimeFormat(Now(), 'hh:mm:sstt'), 1)>
   <cfset a = StructInsert(myBook, "title", "EhCache Book", 1)>
   <cfset a = StructInsert(myBook, "author", "Greg Luck", 1)>
   <cfset a = StructInsert(myBook, "ISBN", "ABCD123456", 1)>
   <CFOBJECT type="JAVA" class="net.sf.ehcache.Element" name="myBookElement">
   <cfset myBookElement.init("myBook", myBook)>
   <cfset cache.put(myBookElement)>
</cfif>
<cfoutput>
Cache time: #myBook["cacheTime"]#<br />
Title: #myBook["title"]#<br />
Author: #myBook["author"]#<br />
ISBN: #myBook["ISBN"]#
</cfoutput>

Documentation __TITLE__