Whatever message this page gives is out now! Go check it out!
Moving complex data across the web with WDDX
Last update:
Jun 9, 2026
Note:
Since Adobe will no longer be supporting Flash Player after December 31, 2020 and Adobe will block Flash content from running in Flash Player beginning January 12, 2021, Adobe strongly recommends all users immediately uninstall Flash Player to help protect their systems.
For more information, see Flash Player End of Life announcement.
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:
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.
It is lightweight. The JavaScript used to serialize and deserialize data, including a debugging function to dump WDDX data, occupies less than 22 K.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:
WDDX has two features that make it useful for transferring data in a web environment:
- 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.
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.
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.)
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:
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:
<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.
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.
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.
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 | XMLSchema | 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.
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.
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
