In our first two posts, we covered how to install Couchbase server and get a cluster up and running.  In this post we are going to put that cluster of yours to use and show you how to configure it as an ORM secondary cache provider for your ColdFusion applications.  

 

If your “cluster” is still just a single server, don’t worry.  The size and configuration of a Couchbase cluster is seamlessly invisible to the connecting client.  Meaning you can grow and scale your cluster without changing your setup/connection code.

At this point in time, there is no Couchbase-specific library for a Hibernate secondary cache, but luckily for us, Couchbase is compatible with the memcached protocol, so we can use the memcached library.  The only drawback is that if you are connecting on the standard port of 11211 to Couchbase, the library will only be able to connect to the “default” bucket.  To use a named bucket for your ORM Secondary cache, you will need to assign the Couchbase bucket you create to a unique port number with NO password when you create it in Couchbase Administrator application.

 

Supporting Files

We’ll be using a library called Hibernate-Memcached.  It is located here: https://github.com/raykrueger/hibernate-memcached

You can clone the repo locally, install Maven, and build the project to compile your own “hibernate-memcached-<version>.jar”.  If that sounds really annoying, scary, or not so exciting, don’t worry-- we have already compiled the jar for you and you can just download ours.
 

Note, we used Java 1.7.0_21 to compile so it would be best if you have your JVM updated to that version or later.  Here’s some old, but still fairly-applicable instructions on how to upgrade your JVM for Adobe ColdFusion. http://helpx.adobe.com/coldfusion/kb/change-jvm-coldfusion-jrun.html

There is one dependent library that must be also used and that is Spymemcached.  The Spymemcached guys are nice enough to have compiled binaries of their latest build. so you can grab the latest version of “spymemcached-<version>.jar” file.

 

Now that you have obtained the two jar files, we need to place them in the Java Classpath of your application server so the Hibernate classes can access them.  For Railo and Adobe ColdFusion, place the two jar files in servlet container’s lib directory.  

Railo deployed on Tomcat, that would be:

<tomcat root>/lib/

Adobe ColdFusion 10’s standalone Tomcat install,that would be: 

<cfroot>/cfusion/lib/

Finally, restart the entire servlet container.

Configuration

Open your application's Application.cfc in your favorite editor and add the following lines of config along with your other ORM settings:

ormSettings.secondarycacheenabled = true;
ormSettings.cacheprovider = "com.googlecode.hibernate.memcached.MemcachedCacheProvider";
// (change directory/filename accordingly)
ormSettings.ormconfig = '/config/hibernate.cfg.xml.cfm';

For more information about ORM settings please visit this URL: https://learn.adobe.com/wiki/display/coldfusionen/ORM+settings

You can see that we use our own ormconfig in order to tell Hibernate what secondary cache to use and configure the protocol to connect to Couchbase.  The most important line is the hibernate.memcached.servers property which is a space delimited list of nodes in the cluster.

<property name="hibernate.memcached.servers">192.168.1.1:11211 192.168.1.2:11211</property>

All the nodes in your cluster don’t need to be represented here, just a few.  The rest of the nodes will automatically get picked up from the cluster automatically.  Hibernate will start if one or more of the servers in your hibernate.memcached.servers property is unreachable at the time that the CFML engine starts, but it will log errors in the standard error file.  Once those missing nodes are added to the cluster and rebalanced, they will get picked up and used again.  There are several other useful settings you can tweak in the XML file such as hibernate.memcached.cacheTimeSeconds, but the comments in the file should help explain what they do.
 

After you have done these changes, reload the ORM via ormreload(), or cycle your CF services again.  You should now have your secondary cache set up and ready to roll with Couchbase amazing caching goodness!  

Debugging/Troubleshooting

In the unlikely event that something doesn’t work the first time, here’s some debugging steps to help you figure out the issue.

• Look in the “out” and “err” logs for information.  These are usually found in the servlet container’s logs.  For instance, if you’re using Tomcat, look in Tomcat’s log directory or ColdFusion's log directory.
• Errors loading the Java class are usually displayed on the screen, but failures to connect to the Couchbase servers are usually logged silently.  Again, make sure you open any logs which were recently modified and scroll to the bottom.  Railo currently swallows any errors loading Hibernate which means there might not be anything useful in the logs. (RAILO-2541)
• If Java errors are being puked out from the belly of the server, scroll to the BOTTOM of the stack trace.  A common pattern in Java is to catch an exception and rethrow a new “wrapped” exception that has the original one stored as the “cause”.  The outermost exception is the first error message you see, but you have to scroll down to the “caused by...” part to get the real error.
• If you’re getting class not found errors, double check the jar files are in the correct directories and that you restarted the JVM.
• If you are getting connection errors or Null pointer exceptions, check the spelling of your hostnames and ports and make sure Couchbase is actually running with a “default” bucket on each of those servers.
• Make sure there’s no conflicting versions of either of your jar files laying around on your hard drive that could also be in the classpath and interfering.
• Check the path and name of your hibernate.cfg.xml.cfm file to ensure it’s being loaded.
• Once the library connects, you should see lines in the out log showing the servers being connected to successfully.  Open up the Couchbase web admin on one of your nodes and watch the “ops per second” graph while you hit your ORM app.  If you see spikes in the graph every time you hit the app, then it’s working!
• If all else fails, please contact us as we would love to help you not only get your Couchbase cluster infrastructure production ready, but also your CFML applications as well.

In our next post we’ll explore the new open source Couchbase provider for CacheBox that lets you use use Couchbase for any CFML application or ColdBox view/event caching, application object caching and much more.

Read our next article in the series: Couchbase: CacheBox Integration.