We are very excited to spring forth a new open source product for the Ortus Family: CFCouchbase SDK.  The CFCouchbase SDK is a CFML library for interacting with Couchbase NoSQL Server. It can be used by any CFML application or CFML framework to provide them with NoSQL, distributed caching, dynamic queries and many more capabilities. 

We have been working with Couchbase NoSQL Server for a while now it has been a true pleasure to not only build scalable farms with it, but also it is incredibly responsive when it comes down to NoSQL and caching transactions.  We have extended their Java SDK and wrapped it in some dynamic CFML goodness.  We not only expose all of the capabilities of the Java SDK, but we also provide automatic CFML to Java serialization and deserializations, Querying DSL, and also a way to automatically serialize and deserialize ColdFusion Components CFCs.

Quick Installation

Once you download the CFCouchbase SDK you will find a cfcouchbase folder inside of it alongside API Docs, samples and the full documentation. This is the entire SDK and the easiest way to install it is to copy it to your web root. However, for a more secure installation we recommend you place it outside of your web root and create a mapping called cfcouchbase to it:

this.mappings[ "/cfcouchbase" ] = '/path/to/cfcouchbase';

public boolean function onApplicationStart(){
	application.couchbase = new cfcouchbase.CouchbaseClient();
	return true;
}
public boolean function onApplicationEnd(){		
	application.couchbase.shutdown( 10 );
	return true;
}

Quick Usage

We have tried our best to make the CFCouchbase API as simple as possible so you can very easily get started with it. We have also fully documented the library, like with anything we do! We even include some sample applications that will take you from using CFCouchbase on any CFML application to a full Object Oriented approach with the ColdBox Framework.

// Create the client
client  = new cfcouchbase.CouchbaseClient();
 
// Create a document in the cluster
client.set( id='brad', value={ name: 'Brad', age: 33, hair: 'red' } );
 
// Retrieve that doc
person = client.get( id='brad' );
 
// Use the document
writeOutput( '#person.name# is #person.age# years old and has #person.hair# hair.' );
 
// Execute a query
results = client.query( designDocumentName='beer', viewName='brewery_beers' );
// Iterate and present results
for( var result in results ) {
    writeOutput( result.document.name );
}
 
// Shutdown the client
client.shutdown();

Automatic Conversions

The SDK will also be smart enough to automatically serialize and deserialize many native CFML data structures and objects for you. So you don't have to deal with this conversion hassle. We provide many ways to customize this marshalling for you.

If you pass simple strings or JSON to the SDK, it will just pass it through untouched to Couchbase for storage.

The CFCouchbase SDK will automatically marshall native CFML arrays, structures and queries into their respective JSON representations and saved within Couchbase. Once they are retrieved, the SDK will automatically convert them back to their native CFML counterpart.

The SDK offers you several ways to interact with CFCs: auto inflation, manual inflation, custom inflation and binary. You can find a much more in-depth guide on this topic in our documentation.

If your CFC is tagged with the autoInflate annotation, then the SDK will store your CFC in Couchbase by reading all of its public properties and building a JSON structure with them alongside the CFC instantiation path. Once you request the entry from Couchbase again, the SDK will be smart enough to detect the instantiation path and rebuild a new CFC with the data from Couchbase.

component accessors="true" autoInflate="true"{
	property name="title"  default="";
	property name="artist" default="";
}

funkyChicken = new path.to.song();
funkyChicken.setTitle( "Chicken Dance" );
funkyChicken.setArtist( "Werner Thomas" );

// Pass the CFC in
couchbase.set( 'funkyChicken', funkyChicken );

// And get a CFC out!
birdieSong = couchbase.get( 'funkyChicken' );

writeOutput( birdieSong.gettitle() );
writeOutput( birdieSong.getArtist() );

If your CFC does not have the autoInflate annotation, then the SDK will just look at the CFC properties and build a JSON structure and it will store it. Once you get the entry from Couchbase, you will manually need to inflate the object with the data retreived. We provide a inflateTo argument in all get and query operations for you, which can be a path, an instance or a closure.

// path
person = client.get(
	ID = 'funkyChicken',
	inflateTo = 'path.to.song'
);

// instance
person = client.get(
	ID = 'funkyChicken',
	inflateTo = new path.to.Song()
);

// closure
person = client.get(
	ID = 'funkyChicken',
	inflateTo = function( document ){
		// Let WireBox create and autowire an instance for us
		return wirebox.getInstance( 'path.to.song' );
	}
);

If for some reason, you want to do your own funky serialization and deserialization, well you can. Just leverage our convention methods: $serialize() and $deserialize().

component accessors="true"{

	property name="firstName";
	property name="lastName";
	property name="age";

	function $serialize(){
		// Serialize as pipe-delimited list
		return '#getFirstName()#|#getLastName()#|#getAge()#';
	}
	
	function $deserialize( ID, data ){
		// Deserialize the pipe-delimited list
		setFirstName( listGetAt( data, 1, '|' ) );
		setLastName( listGetAt( data, 2, '|' ) );
		setAge( listGetAt( data, 3, '|' ) );		
	}
}

Finally, if your CFC does not meet any of the above criteria, the SDK will just convert the object to a binary 64 representation. It will then re-inflate your object back to its original state when retreiving it.

We have just been scratching the surface with the capabilities that the SDK will provide to your applications. We recommend your read our blogging series below and check out all our resources to start building your CFML applications powered by Couchbase.

Ortus Couchbase Blogging Series

Here are the collection of blog entries we have done about Couchbase NoSQL Server.

• Intro to Couchbase Server
• Cluster Setup + ORM Secondary Cache
• Ortus CacheBox Couchbase Provider Release!
• Secondary ORM Configuration & Setup!
• CacheBox Integration!
• Ortus Railo Extension

Resources

Please visit our CFCouchbase page for all the necessary resources.

• Download
• Capabilities
• Documentation
• API Docs
• Source Code
• Issue Tracker
• Professional Support