ColdFusion 9.0 Resources

Moving complex data across the web with WDDX

WDDX is an XML vocabulary for describing a complex data structure, such as an array, associative array (such as a ColdFusion structure), or a recordset, in a generic fashion. It lets you use HTTP to move the data between different application server platforms and between application servers and browsers. Target platforms for WDDX include ColdFusion, Active Server Pages (ASP), JavaScript, Perl, Java, Python, COM, Flash, and PHP.

The WDDX XML vocabulary consists of a document type definition (DTD) that describes the structure of standard data types and a set of components for each of the target platforms to do the following:

Serialize: The data from its native representation into a WDDX XML document or document fragment.
Deserialize: A WDDX XML document or document fragment into the native data representation, such as a CFML structure.

This vocabulary creates a way to move data, its associated data types, and descriptors that allow the data to be manipulated on a target system, between arbitrary application servers.

Note: The WDDX DTD, which includes documentation, is located at www.openwddx.org/downloads/dtd/wddx_dtd_10.txt.

WDDX is a valuable tool for ColdFusion developers, however, its usefulness is not limited to CFML. If you serialize a common programming data structure (such as an array, recordset, or structure) into WDDX format, you can use HTTP to transfer the data across a range of languages and platforms. Also, you can use WDDX to store complex data in a database, file, or even a client variable.

WDDX has two features that make it useful for transferring data in a web environment:

It is lightweight. The JavaScript used to serialize and deserialize data, including a debugging function to dump WDDX data, occupies less than 22 K.
Unlike traditional client-server approaches, the source and target system can have minimal-to-no prior knowledge of each other. They only must know the structure of the data that is being transferred.

WDDX was created in 1998, and many applications now expose WDDX capabilities. The best source of information about WDDX is www.openwddx.org. This site offers free downloads of the WDDX DTD and SDK and additional resources, including a WDDX FAQ, a developer forum, and links to additional sites that provide WDDX resources.

Uses of WDDX

WDDX is useful for transferring complex data between applications. For example, you can use it to exchange data between a CFML application and a CGI or PHP application. WDDX is also useful for transferring data between the server and client-side JavaScript.

Exchanging data across application servers

WDDX is useful for the transfer of complex, structured data seamlessly between different application server platforms. For example, an application based on ColdFusion at one business could cfwddx use to convert a purchase order structure to WDDX. It could then use cfhttp to send the WDDX to a supplier running a CGI-based system.

The supplier could then deserialize the WDDX to its native data form, the extract information from the order, and pass it to a shipping company running an application based on ASP.

Transferring data between the server and browser

You can use WDDX for server-to-browser and browser-to-server data exchanges. You can transfer server data to the browser in WDDX format and convert it to JavaScript objects on the browser. Similarly, your application pages can serialize JavaScript data generated on the browser into WDDX format and transfer the data to the application server. You then deserialize the WDDX XML into CFML data on the server.

On the server, you use the cfwddx tag to serialize and deserialize WDDX data. On the browser, you use WddxSerializer and WddxRecordset JavaScript utility classes to serialize the JavaScript data to WDDX. (ColdFusion installs these utility classes on your server as webroot/CFIDE/scripts/wddx.js.)

WDDX and web services

WDDX does not compete with web services. It is a complementary technology focused on solving simple problems of application integration by sharing data on the web in a pragmatic, productive manner at low cost.

WDDX offers the following advantages:

It can be used by lightweight clients, such as browsers or Flash Player.
It can be used to store complex data structures in files and databases.

Applications that take advantage of WDDX can continue to do so if they start to use web services. These applications could also be converted to use web services standards exclusively; only the service and data interchange formats: not the application model, must change.

How WDDX works

The following example shows how WDDX works. A simple structure with two string variables could have the following form after it is serialized into a WDDX XML representation:

<var name='x'> 
    <struct> 
 
        <var name='a'> 
            <string>Property a</string> 
        </var> 
        <var name='b'> 
            <string>Property b</string> 
        </var> 
    </struct> 
</var>

When you deserialize this XML into CFML or JavaScript, the result is a structure that is created by either of the following scripts:

JavaScript

CFScript

x = new Object();

x.a = "Property a";

x.b = "Property b";

x = structNew();

x.a = "Property a";

x.b = "Property b";

Conversely, when you serialize the variable x produced by either of these scripts into WDDX, you generate the XML listed in the preceding code.

ColdFusion provides a tag and JavaScript objects that convert between CFML, WDDX, and JavaScript. Serializers and deserializers for other data formats are available on the web. For more information, see www.openwddx.org.

Note: The cfwddx tag and the wddx.js JavaScript functions use UTF-8 encoding to represent data. Any tools that deserialize ColdFusion-generated WDDX must accept UTF-8 encoded characters. UTF-8 encoding is identical to the ASCII and ISO 8859 single-byte encodings for the standard 128 "7-bit" ASCII characters. However, UTF-8 uses a two-byte representation for "high-ASCII" ISO 8859 characters where the initial bit is 1.

WDDX data type support

The following text describes the data types that WDDX supports. This information is a distillation of the description in the WDDX DTD. For more detailed information, see the DTD at www.openwddx.org.

Basic data types

WDDX can represent the following basic data types:

Data type	Description
Null	Null values in WDDX are not associated with a type such as number or string. The tag converts WDDX Nulls to empty strings.
Numbers	WDDX documents use floating-point numbers to represent all numbers. The range of numbers is restricted to +/-1.7E+/-308. The precision is restricted to 15 digits after the decimal point.
Date-time values	Date-time values are encoded according to the full form of ISO8601; for example, 2002-9-15T09:05:32+4:0.
Strings	Strings can be of arbitrary length and must not contain embedded nulls. Strings can be encoded using double-byte characters.

Complex data types

WDDX can represent the following complex data types:

Data type	Description
Array	Arrays are integer-indexed collections of objects of arbitrary type. Because most languages start array indexes at 0, while CFML array indexes start at 1, working with array indexes can lead to nonportable data.
Structure	Structures are string-indexed collections of objects of arbitrary type, sometimes called associative arrays. Because some of the languages supported by WDDX are not case-sensitive, no two variable names in a structure can differ only in their case.
Recordset	Recordsets are tabular rows of named fields, corresponding to ColdFusion query objects. Only simple data types can be stored in recordsets. Because some of the languages supported by WDDX are not case-sensitive, no two field names in a recordset can differ only in their case. Field names must satisfy the regular expression [_A-Za-z][_.0-9A-Za-z]* where the period (.) stands for a literal period character, not “any character”.
Binary	The binary data type represents strings (blobs) of binary data. The data is encoded in MIME base64 format.

Data type comparisons

The following table compares the basic WDDX data types with the data types to which they correspond in the languages and technologies commonly used on the web:

WDDX	CFML	XML Schema	Java	ECMAScript/ JavaScript	COM
null	N/A	N/A	null	null	VT_NULL
boolean	Boolean	boolean	java.lang.Boolean	boolean	VT_BOOL
number	Number	number	java.lang.Double	number	VT_R8
dateTime	DateTime	dateTime	java.lang.Date	Date	VT_DATE
string	String	string	java.lang.String	string	VT_BSTR
array	Array	N/A	java.lang.Vector	Array	VT_ARRAY \| VT_VARIANT
struct	Structure	N/A	java.lang. Hashtable	Object	IWDDXStruct
recordset	Query object	N/A	coldfusion.runtime.QueryTable	WddxRecordset	IWDDXRecordset
binary	Binary	binary	byte[]	WddxBinary	V_ARRAY \| UI1

Time zone processing

Producers and consumers of WDDX packets can be in geographically dispersed locations. Therefore, it is important to use time zone information when serializing and deserializing data, to ensure that date-time values are represented correctly.

The cfwddx action=cfml2wddx tag useTimezoneInfo attribute specifies whether to use time zone information in serializing the date-time data. In the JavaScript implementation, useTimezoneInfo is a property of the WddxSerializer object. In both cases, the default useTimezoneInfo value is True.

Date-time values in WDDX are represented using a subset of the ISO8601 format. Time zone information is represented as an hour/minute offset from universal time (UTC); for example, “2002-9-8T12:6:26-4:0”.

When the cfwddx tag deserializes WDDX to CFML, it automatically uses available time zone information, and converts date-time values to local time. In this way, you need not worry about the details of time zone conversions.

However, when the JavaScript objects supplied with ColdFusion deserialize WDDX to JavaScript expressions, they do not use time zone information, because in JavaScript it is difficult to determine the time zone of the browser.