When you think of caching there are basically two types: in-process, and out-of-process (or external caching). In-process caching all happens on the host machine and often within the same JVM container (if you’re using ColdFusion specifically). That is, all caching will always reside locally, making caching operations extremely fast. The obvious downside to this method of caching is that the cache consumes the same resources that would have otherwise be spent on your application server.

In order to allow you to scale out (by adding more servers to a cluster, for example) rather than scaling up (by adding additional ram) you need to provide an out-of-process caching mechanism. Again, the obvious downside to an out-of-process setup is the fact that you must serialize and transmit data to an external JVM, which requires much more overhead and transmission time.

Caching Enhancements in ColdFusion 9 – Rob Brooks-Bilson’s Blog

Ehcache Server to the Rescue

Ehcache Server, found here, provides some ingenious ways to manage your out-of-process cached content using the HTTP methods GET, HEAD, PUT, and DELETE. This is a pretty large contrast with other external caching systems, like Memcached which require a language specific client to work.

Ehcache Server is simply deployed to the Java application server of your choice (like Glassfish, which is bundled in with a standalone version of Ehcache Server). Once it’s up and running, you can access your cache via the HTTP methods, or even use SOAP if you’re so inclined.

Memcached versus Ehcache – Greg Luck’s Blog
GlassFish, Open Source Application Server

Running the Standalone Server

These instructions are for Windows (as I do my development on that platform). If you’re interested in setting up Ehcache Server on other environments, or don’t want to use the standalone server package, you can check out the Ehcache Server installation instructions.

First download the standalone package from SourceForge. Unpack it to the destination of your choice and open cmd and go the the new folder’s bin sub-directory.

Finally, run the server by entering the following command:

java -jar ..\lib\ehcache-standalone-server-0.7.jar 8080 ..\war

With the server up and running, we can finally do some caching!

Lotsa Cache!

Ehcache Server comes with a default setup (which I’ll refer to in this instance), but you can modify it by going to \war\WEB-INF\classes\ehcache.xml.

Ehcache Server’s RESTful services are all accessed through a simple URL. In our case it’ll be http://localhost:8080/ehcache/rest/[CACHE NAME]. The default setup provides a couple of caches already, so we’ll use sampleCache1. Feel free to modify the ehcache.xml to play with different caching setups.

Let’s start with a basic PUT and GET.

Everything we cache requires a key. Think of a key as a unique identifier which describes where our cached data resides on the cache server. How you come up with these keys is up to you, but it’s probably best practice to come up with some sort of hashing algorithm which is consistent across your web application servers. The key must be a string without spaces or punctuation.

GET, as you may have guessed, is responsible for acquiring already cached data from the Ehcache Server, and providing it back to your web application. To get an element using our RESTful methods, we simply take the cache URL and add our key to the end of it like a sub-folder.

http://localhost:8080/ehcache/rest/sampleCache1/testKey

The URL above would return content stored in sampleCache1 which has the key testKey. Doing this in ColdFusion is as easy as:

<cfhttp method="get" url="http://localhost:8080/ehcache/rest/sampleCache1/testKey" result="cacheData" throwonerror="true" />

If you attempted to run the above code it would throw you an error. This is because we have set the throwonerror attribute to true, and because we don’t currently have anything cached under testKey. So, you want to PUT some element into the cache so it can be retrieved via the GET request:

<cfhttp method="put" url="http://localhost:8080/ehcache/rest/sampleCache1/testKey" throwonerror="true">
	<cfhttpparam type="body" value="Hello World" />
</cfhttp>

The above code will put the text Hello World into the sampleCache1 cache, with the key testKey. Calling the GET request again will return the content you provided. Easy eh?

To read more about the operations you have access to through the RESTful Ehcache Server, check out the documentation here.

Ehcache RESTful documentation

Object Serialization

One of the major hurdles to overcome with this form of caching is how to deal with objects and any other non-string elements you wish to cache. Ehcache Server expects a string and will respond with a string when you try to GET the content back again.

One of the quickest and easiest ways to do this is to depend on Java’s serialization methods to convert the object into a string representation when putting, and convert it back when getting.

To PUT:

<!--- Create element to cache --->
<cfset elementToCache = StructNew() />
<cfset elementToCache['sayHello'] = 'Hello World' />
<cfset elementToCache['meaningOfLife'] = 42 />

<!--- Create java objects --->
<cfset byteArrayOutputString = CreateObject('java', 'java.io.ByteArrayOutputStream').init() />
<cfset objectOutputStream = CreateObject('java', 'java.io.ObjectOutputStream').init(byteArrayOutputString) />

<!--- Serialize your data --->
<cfset objectOutputStream.writeObject(elementToCache) />
<cfset serializedElement = ToBase64(byteArrayOutputStream.toByteArray()) />
<cfset objectOutputStream.close() />

<!--- Put the element into the cache --->
<cfhttp method="put" url="http://localhost:8080/ehcache/rest/sampleCache1/testKey" throwonerror="true">
	<cfhttpparam type="body" value="#serializedElement#" />
</cfhttp>

And to GET your object back:

<!--- Perform cfhttp to get the content --->
<cfhttp method="get" url="http://localhost:8080/ehcache/rest/sampleCache1/testKey" result="cacheData" throwonerror="true" />

<!--- Create java objects --->
<cfset byteArrayInputStream = CreateObject('java', 'java.io.ByteArrayInputStream').init(ToBinary(cacheData.fileContent)) />
<cfset objectInputStream = CreateObject('java', 'java.io.ObjectInputStream').init(byteArrayInputStream) />

<!--- Perform deserialization --->
<cfset deserializedData = objectInputStream.readObject() />
<cfset objectInputStream.close() />

And tada, the structure you created previously now resides within the deserializedData variable!

Summary

Ehcache Server’s out-of-process RESTful services are very simple to use, yet provide you an extraordinary ability to scale out your system and increase performance dramatically.

Tags: Caching, ColdFusion, Ehcache, Ehcache Server, intermediate, RESTful

This entry was posted on Sunday, May 30th, 2010 at 1:55 pm and is filed under Caching. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.