Blog

CFCouchbase SDK Released

Luis Majano March 03, 2014

Spread the word

Luis Majano

March 03, 2014

Spread the word


Share your thoughts

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;
}
Now that the library is installed you can instantiate the class cfcouchbase.CouchbaseClient with or without any connectivity options. This client will connect to one Couchbase bucket on the localhost:8091 by default, so you can interact with it.

 

Important: Each Couchbase bucket operates independantly and uses its own authentication mechanisms. You need an instance of CouchbaseClient for each bucket you want to interact with. It is also extremely important that you shutdown the clients whenever your application goes down in order to gracefully shutdown connections, else your server might degrade.

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.

Simple Strings

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

CFML Complex Objects (arrays, queries, structures)

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.

Components (CFCs)

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.

Components - Auto Inflation

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() );
Components - Manual Inflation

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' );
	}
);
Components - Custom

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, '|' ) );		
	}
}
Components - Binary

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.

Resources

Please visit our CFCouchbase page for all the necessary resources.

Add Your Comment

Recent Entries

Ortus Content Digest for week of August 19th

Ortus Content Digest for week of August 19th

It's August 19th... Into the Box is approaching fast, what has Ortus been publishing this week? We have the CFML News Podcast, some CFCasts and YouTube Videos, lots of Ortus and ITB Blog Posts. We have a lot more planned for next week as well.

Gavin Pickin
Gavin Pickin
August 19, 2022
Integrating ColdBox with Existing Code Series 5: Using Wirebox

Integrating ColdBox with Existing Code Series 5: Using Wirebox

Recently, I did a webinar on Refactoring Legacy Code and the question came up about whether or not it was possible to use ColdBox with existing code without converting everything to a ColdBox module or making changes to the existing codebase. In the first installation in this series, we took a tour of the various elements which make up ColdBox. In the second installation, we looked at creating layouts, views, and routes in the main site. In the third, we created a module and did the first integration of our existing code into our ColdBox site. In the fourth, we continued developing our module with a handler and passing variable back to Coldbox. Now we'll use Wirebox with and without ColdBox Modules to see how these approaches differ from a traditional approach.

Dan Card
Dan Card
August 18, 2022
Ortus Content Digest for week of August 12th

Ortus Content Digest for week of August 12th

It's August 12th... what has Ortus been publishing this week? We have the CFML News Podcast, some CFCasts and YouTube Videos, lots of Ortus and ITB Blog Posts. We have a lot more planned for next week as well.

Gavin Pickin
Gavin Pickin
August 12, 2022