Using WDDX

What is WDDX?

WDDX is one of the neatest features natively available in ColdFusion, but tends to get overlooked far too often. WDDX allows you to "serialize" data, namely variables, into a string format that can then be "deserialized" into their original state.

Where could I use this technology?

There are many, many ways to use this native technology in your applications. This tutorial will show you how to use WDDX to store session scope data into the client scope.

As we all know, the session scope limits your applications scalability. Since the session scope relies on server memory, the application cannot be load balanced in many cases. Worse still, is the face that using the session scope exstensively means trips to and from the server's memory, possibly causing corruption!

So we instead decide to use the client scope to hold our session scope-like data. Only we run into a new problem, the client scope cannot hold complex values!

Take for instance :

<!--- creating a structure to hold user information --->
<cfset user = structNew()>
<cfset user.firstName = "Joe">
<cfset user.lastName = "Blow">
<!--- placing that structure into the session scope will work --->
<cfset session.user = user>
<!--- placing that structure into the client scope will fail!! --->
<cfset client.user = user>

ColdFusion will throw an exception :
Invalid client variable contents The value of the client variable user is not a string, number, boolean, or date/time value.

The server is telling us that the client scope can only hold simple values, and our structre is of complex type! Other complex data types besides structures will fail as well, such as a query object. You might for example, have a complex and intense database query that you will want persistent across a number of pages, one way of doing this is to place it into your session. With queries being a complex type, this will fail if you try to do the same in the client scope!

Solving the problem with WDDX

With WDDX, we can solve this problem by turning our data into a string and then storing it into the client scope.

We are going to create a request scope variable to store our session-like data, and use it instead of client or session. Then we will write helper functions/snippets that will do the conversion between our request variable and the client scope automatically!

To do this, we need to create three pieces of code. The first will set up our request scope storage. The second will serialize all of our data and place it into the client scope for us. The third will deserialize our data and put it back where it belongs.

Setting up our request scope storage variable

In our Application.cfm page, we will set up our request scope variable to store all of our session-like data. Anytime we would normally interact with the session or client scope, we will instead interact with this request scope variable.

<!--- set up our session/client storage variable in the request scope --->
<cfparam name="request.session" default="#structNew()#">
<!--- set up a client variable to store our serialized data --->
<cfparam name="client.session" default="">

We've also added a client variable named session. This is where our WDDX data will be saved. You won't have to interact with this variable in your application at all, we'll handle all of this in the following two helper snippets!

Thats it! Now we can use this variable in the request scope as if it were our session scope. Simple eh? But how would we interact with it in our pages instead of the session scope? Here is an example :

<!--- instead of storing something like this: --->
<cfset session.loginDate = now()>
<!--- we use it like this: --->
<cfset request.session.loginDate = now()>

<!--- instead of outputing something like this: --->
<!--- we output it like this: --->

Serializing our data into the client scope

In our OnRequestEnd.cfm page (which is executed at the end of all requests made to your ColdFusion application) we will create some code to automatically place any changes to our request.session variable into the client scope.

Our code looks like this:

<!--- first, we serialize our request variable into a wddx string (or packet) --->
<cfwddx action="cfml2wddx" input="#request.session#" output="wddxSession">
<!--- next we place it into the client scope. since it is a string, with no
complex data types, it will fit!! --->
<cfset client.session = wddxSession>

Deserializing our client scope WDDX packet and putting it into our request scope storage variable

In our Application.cfm file, after our request scope variable setup, we will deserialize any data put into the client scope, and return it to our request scope variable where it belongs!

After adding the new code to the Application.cfm, it should look like this:

<!--- set up our session/client storage variable in the request scope --->
<cfparam name="request.session" default="#structNew()#">
<!--- set up a client variable to store our serialized data --->
<cfparam name="client.session" default="">

<!--- now deserialize the client storage variable if its not empty--->
<cfif len(trim(client.session))>
     <!--- deserialize the contents of client.session and place into request.session --->
     <cfwddx action="wddx2cfml" input="#client.session#" output="request.session">

The new code we've added does all of the magic. It first finds out if we've place any information into our scope yet. If we have, then WDDX takes that data and converts it back to native ColdFusion data types!

Its alive!

With only seven lines of ColdFusion code, and the use of WDDX, we have completed our mission! Our application is no longer dependant on server memory, problematic session variables. We can now store complex data types like structures and queries into the client scope, which normally is prohibited! The best part is, its simple to implement by just adding "request." in front of your session variables, so there isn't any complexity added to your normal application development!

Please feel free to contact me with questions / comments

Nate Nielsen

About This Tutorial
Author: Nate Nielsen
Skill Level: Intermediate 
Platforms Tested: CF5,CFMX
Total Views: 113,282
Submission Date: September 10, 2004
Last Update Date: June 05, 2009
All Tutorials By This Autor: 9
Discuss This Tutorial
  • Thanks for the ability to store complex data types in the user database! nice to know that I can store up to 2,147,483,647 characters in SQL Server in that data field too!


Sponsored By...
Mobile App Development (IOS, Android, Cordova, Phonegap, Objective-C, Java) - Austin, Texas Mobile Apps - Touch512, LLC.