Couchbase: Ortus Railo Extension

Transcription

1 Tweet Couchbase: Ortus Railo Extension Brad Wood Aug 28, 2013 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

2 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 inprocess 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

3 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. You only need one license per JVM instance regardless of how many web contexts you are running. You can also use the same license for development or non-public facing instances. Once you buy your license, we ll send you your custom Railo Extension Provider URL with appropriate license key. If you would like to purchase a license before public release, please contact us at sales@ortussolutions.com. 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

4 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.

5 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.

6 We recommend installing the extension in the Server Administrator so it is available to all the web contexts. 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.

7 If you have many servers in your Couchbase cluster, you only need to list a few of them here. The client library will do auto discovery of the rest of the nodes once it connects. 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! â On certain cases Railo will report that it cannot find the Couchbase Extension class. This is most likely due to how Railo loads the class files upon installation. To fix this just restart Railo. Usage

8 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 ( 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

9 contents of those scopes will be automatically persisted to the cluster and will be available to whichever web server your users hit. â Please make sure that you are using CFML based sessions in your site in order for this functionality to work. This will not work with J2EE sessions as then the servlet container manages your session. This can be configured in the Railo administrator (web or server) under the "Scope" section. 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.

10 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. Copyright Ortus Solutions, Corp.