So far in this series, we’ve introduced you to Couchbase Server and showed you how to set up a cache cluster.  Then we covered using that cluster as an ORM Secondary Cache as well as connecting to it through our open source CacheBox Provider.  Today, we’re going to show how to get the deepest integration yet for those of you running Railo’s Open Source CFML server via our upcoming Ortus Railo Couchbase Extension.  Our extension will allow you to leverage Couchbase directly from Railo as a caching engine, but also as a storage container for session or even client scope variables.  The extension also introduces several native ColdFusion functions that will allow you to interact with Couchbase directly from CFML code for your NoSQL or Caching needs. So let's get to it and start off by introducing our extension.

Capabilities

Caching

CFML has a set of cache-related functions that allow you to set and retrieve objects from an application cache.  Adobe ColdFusion uses EHCache, an in-process Java caching solution.  Railo, the open source CFML engine, also can use EHCache, but they went a step further and introduced a pluggable cache architecture that allows you to write a Java adapter class that will connect to any underlying caching engine; much how CacheBox works but right into the engine. 

Session/Client Storages

Railo also allows these caches to be used for session or client storage as an added bonus.  This is extremely handy if you have a farm of load balanced web servers and you want to use session storage without using session replication or enabling sticky sessions on your load balancer.  By configuring your session storage to use an out-of-process distributed cache you are allowing your site to scale out easily since the application servers won't be taxed with storing session data for all your users in their in-process heap.  It will also allow for your session information to survive server restarts and provide a much better user experience for your application.  Lastly, it can allow your load balancers to run round-robin algorithms instead of the typical sticky session approach.  This will bring a much more stable cluster farm where load can be distributed evenly and without user segregation.

Native Integration

Couchbase is not only an amazing caching solution but also a NoSQL database, as we have seen throughout our series.  Having the capabilities to interact with it easily via CFML was our next step of introducing several native CFML functions thanks to Railo's extension architecture.  This is where we come in.  We here at Ortus Solutions have developed a commercial extension for Railo Server that adds Couchbase support for the native cache functions, as well as query/template/function caches, session/client storage and native CFML functions for NoSQL integration.  This extension is built on top of the Couchbase Java SDK and truly gives you low-level access to the power of Couchbase Server.

Purchasing The Extension

The Ortus Railo Couchbase Extension will be available for purchase in the coming weeks from our Ortus store for only $99 per year/instance.  We have also created a trial version of the extension that will provide you with these capabilities for up to 30 days.  The following instructions all leverage our trial extension.
 

Features In A Nutshell

• Add Couchbase functionality to any Railo application
• Install at the web context level or the server level (Available to all contexts)
• Create Cache connections in the Railo web administrator to connect to any network-accessable Couchbase cluster
• Set and get objects from Couchbase via standard CFML functions and tags (cachePut(), cacheGet(), <cfcache action="get|put">)
• Fully supports all built-in Railo cache functions including wildcard filters
• Seamlessly distribute storage of the following to any bucket in a Couchbase cluster
  • Railo session storage
  • Railo client storage
  • Railo Ram resouce (ram://...)
• Seamlessly cache the following to any timeout-sensitive bucket in a Couchbase cluster
  • Results of database queries
  • Results of deterministic functions
  • Complex or simple objects in your application's code
  • Cached templates (<cfcache action="content|cache|serverCache">)
• Registers new Built-In Functions (BIFs) for executing user-defined queries against Couchbase views.
• Extremely lightweight and fast

Installation

In your Railo Server Administrator under “Extension” > “Providers” paste in your Ortus provider URL (Please Contact Us For URL) and click “save”.  Now click “Extensions” > “Applications” and wait for the list to load.  There should be a new item in the list called “Couchbase Cache”.  

 

Click it and then click the ”install” button to download and install the extension to your Railo server.
 

The Ortus Railo Couchbase Extension should now be installed on your server and ready to use.  Make sure your Couchbase cluster is running and proceed on to the next step of creating a cache.

Configuration

If you install the Extension in the Server Administrator, you will be able to create server-level caches as well as site-specific caches in each of the Web Administrators.  If you install the extension in a web administrator, you will only be able to create Couchbase caches for that web context only.  
 

To add a new cache, click on “Services” > “Cache” and you should see a list of existing caches.  If there are no existing caches, you should be taken straight to the “create” screen.  Type a name for this cache connection and choose “Couchbase Server” from the “type” dropdown and click "create":
 

You will then be taken to a page of options for the Couchbase Cache implementation.  Check the “Storage” box if you want to be able to use this cache for session or client storage.  Enter the servers in the text area one per line.
 

 

Enter your bucket name and password.  If you are using the default bucket, there will be no password needed.  The “Default” dropdown allows you to specify this connection to be used as the storage mechanism for function, object, template, query, or resource caches.  If you set this at the server level, it can be overridden at the website level.  Click “Submit” to finish creating the cache connection and save its settings.  The newly-created cache connection should now show up in the list of caches.  Check the box next to your new cache and click the “verify” button to try the new cache out.  If the word “Error” appears in red, hover over it with your mouse to see the error message.  For more information check the logs.  If a green “OK” appears, you’re up and running!
​

Usage

The first and easiest way to use your new cache is via the built-in cache functions in CFML.  If you have selected your cache as the default “Object” cache in the admin, you can simply do this:

cachePut(”key”,”value”);
cacheGet(“key”);

Look at the Couchbase admin console located on port 8091 (http://localhost:8091) of any one of your clusters’ nodes and you should see a spike in the “ops per second” graph.  If your Couchbase cache is not the default “Object” cache, then simply specify the cache name like so:

cachePut(id="key",value="value",cacheName="myCouchbaseCache");
cacheGet(id="key",cacheName="myCouchbaseCache");

If you have set your Couchbase cache to be the default function, template, or query storage, then simply use those features as you normally do and check the Couchbase console to ensure that the cache shows activity.  For the most part those features just plain work.

Session/Client Storage

If you want to use your cache for session/client storage, add the following lines to your Application.cfc.

// The name of the storage cache you created
this.sessionStorage = 'myCouchbaseCache';

// Set this to true if you have more than one web server sharing the same session storage
this.sessionCluster = true;

Then just use your session (or client) scope as you normally would.  The contents of those scopes will be automatically persisted to the cluster and will be available to whichever web server your users hit.
​

Debugging/Troubleshooting

The debugging steps for the Ortus Railo Couchbase Extension are very similar to the CacheBox provider, but I’ll post them here again since they’re good to keep in mind.

• Look in the "out" and "err" logs for information.  These are usually found in the servlet container's log directory.  For instance, if you're using Tomcat, look in Tomcat's log directory.  There are often messages logged there that never make it up to the CFML engine.
• Always scroll to the bottom of Java stack traces to look for a “caused by” section which is the original 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 the bucket name you specified in the config.
• 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.  This could include old versions of the Extension or Membase/CouchDB extensions which share some of the same jars.
• 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 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 so we can assist you with our professional open source services.