Brad Wood

August 07, 2013

Spread the word

Share your thoughts

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.  


Please remember that the installation instructions are pretty much the same for Adobe ColdFusion and Railo CFML.

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:

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.

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.


At the time of writing this, 2.9.1 was the latest version of Spymemcached that we used.

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: 


Finally, restart the entire servlet container.


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:

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"></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.

Don’t bother setting hibernate.cache.use_query_cache or hibernate.cache.provider_class in the Hibernate config, they will be ignored.  You must use ormSettings.secondarycacheenabled and ormSettings.cacheprovider in your Application.cfc.

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!  


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.

Add Your Comment

Recent Entries

CBWIRE 3.0.0 Released

CBWIRE 3.0.0 Released

We are very excited to announce the release of version 3 of CBWIRE, our ColdBox module that makes building modern, reactive apps a breeze. This version brings with it a new component syntax, 19 enhancements and bug fixes, and improved documentation. Our biggest goal with this release was to improve the developer experience and to provide a low barrier to entry to getting started with CBWIRE.

Grant Copley
Grant Copley
May 22, 2023
ColdBox 7.0.0 Released

ColdBox 7.0.0 Released

Introducing ColdBox 7: Revolutionizing Web Development with Cutting-Edge Features and Unparalleled Performance

We are thrilled to announce the highly anticipated release of ColdBox 7, the latest version of the acclaimed web development HMVC framework for ColdFusion (CFML). ColdBox 7 introduces groundbreaking features and advancements, elevating the development experience to new heights and empowering developers to create exceptional web applications and APIs.

Designed to meet the evolving needs of modern web development, ColdBox 7 boasts a range of powerful features that streamline the development process and enhance productivity. With its robust HMVC architecture and developer-friendly tools, ColdBox 7 enables developers to deliver high-performance, scalable, and maintainable web applications and APIs with ease.

Esme Acevedo
Esme Acevedo
May 16, 2023
TestBox v5.0.0 Released!

TestBox v5.0.0 Released!

We are excited to announced the release of Testbox version 5, which brings a host of new features and improvements for developers. TestBox is a powerful and flexible tool that helps developers write comprehensive BDD/TDD tests for their applications, ensuring code quality and reducing the likelihood of bugs and errors. With TestBox v5, developers can take advantage of new features such as batch code coverage testing, improved reporting capabilities, method spies, and better integration with other tools in the Ortus suite.

These new features make TestBox even more versatile and user-friendly, and provide developers with a powerful tool for building high-quality, reliable applications.


Luis Majano
Luis Majano
May 11, 2023