Anatomy of a WDDX Packet


Now that you have an idea about how the <cfwddx> tag works, let's take a closer look at the WDDX packets themselves. You've already seen WDDX packets as displayed in a browser (Figures 16.1 and 16.3), but packets aren't really meant to be displayed on Web pages. It makes more sense to look at them as if they were data files, kind of like a database or delimited text file.

NOTE

Really, the principal idea behind WDDX is that the XML for each WDDX packet is created and parsed automatically, so you don't actually ever need to know or understand the anatomy of the packets themselves. That said, I thought you might be curious about the various elements (tags) in the packets. Feel free to skip this section if you want!


Listing 16.5 shows the StringPacket.txt file that was created by Listing 16.1. I have added some carriage returns and indention to make the packet easier on the eyes. The whitespace I added doesn't make the packet any less valid, but it makes it easier for us humans to understand.

Listing 16.5. StringPacketFormattted.txtThe Simple WDDX Packet Created by Listing 16.1
 <wddxPacket version='1.0'>  <header/>  <data>  <string>Hello, World!</string>  </data> </wddxPacket> 

The entire packet is enclosed between a pair of <wddxPacket> tags. As of this writing, the version attribute will always be 1.0. If the WDDX specification changes in the future, the version number will be updated accordingly. This way, before an application attempts to deserialize a packet, it can check the version number to ensure that it knows how to read all the tags in the packet before it starts.

NOTE

For history buffs out there, the first version of WDDX was version 0.9 and was introduced in ColdFusion 4.0. A few minor additions to WDDX were made in the months thereafter, resulting in version 1.0. The main change from 0.9 to 1.0 was the introduction of the <binary> element, which allows WDDX packets to contain raw bits of binary data such as images. <cfwddx> has been producing version 1.0 packets since ColdFusion 4.5 and continues to do so in the current version.


Within the <wddxPacket> block, a <header> tag always appears next. The <header> tag serves no purpose in WDDX at this time but might come to hold significant information in a future version of WDDX. After the <header> tag, a pair of <data> tags appear, and all the tags that contain the actual serialized information are placed between them.

In Listing 16.5, a single pair of <string> tags is placed between the <data> tags. If the data in the packet were a date value instead of a string, a pair of <dateTime> tags would appear there instead.

For a glimpse inside a more interesting WDDX packet, take a look at Listing 16.6, which shows the StructPacket.txt file generated by my second serialization example (Listing 16.3). The same <wddxPacket>, <header>, and <data> elements are present and will always be present in any valid packet. Not surprisingly, this packet contains quite a few additional elements nested within its <data> block.

Again, I've added indention to make the packet more readable on the printed page, but the indention doesn't affect the validity of the packet.

Listing 16.6. StructPacketFormattted.txtThe Complex Packet Created by Listing 16.3
 <wddxPacket version='1.0'>  <header/>  <data>  <struct>  <var name='PACKETDATE'>  <dateTime>2002-6-16T14:51:5-5:0</dateTime>  </var>  <var name='FILMS'>  <recordset   fieldNames='FILMID,MOVIETITLE,AMOUNTBUDGETED,DATEINTHEATERS'  rowCount='5'>    <field name='FILMID'>  <number>1.0</number>  <number>2.0</number>  <number>3.0</number>  <number>18.0</number>  <number>21.0</number>  </field>  <field name='MOVIETITLE'>  <string>Being Unbearably Light</string>  <string>Charlie's Devils</string>  <string>Closet Encounters of the Odd Kind</string>  <string>Folded Laundry, Concealed Ticket</string>  <string>Forrest Trump</string>  </field>  <field name='AMOUNTBUDGETED'>  <number>300000.0</number>  <number>750000.0</number>  <number>350000.0</number>  <number>7000000.0</number>  <number>1.35E8</number>  </field>  <field name='DATEINTHEATERS'>  <dateTime>2000-8-1T0:0:0-5:0</dateTime>  <dateTime>2000-12-25T0:0:0-5:0</dateTime>  <dateTime>2000-11-7T0:0:0-5:0</dateTime>  <dateTime>2002-9-15T0:0:0-5:0</dateTime>  <dateTime>2004-7-12T0:0:0-5:0</dateTime>  </field>  </recordset>  </var>  <var name='COMPANYNAME'>  <string>Orange Whip Studios</string>  </var>  <var name='COMPANYURL'>  <string>http://www.orangewhipstudios.com</string>  </var>  <var name='OFFICES'>  <array length='3'>  <string>New York, NY</string>  <string>Paris, France</string>  <string>Pittsfield, MA</string>  </array>  </var>  </struct>  </data> </wddxPacket> 

Tables 16.2 and 16.3 provide a brief explanation of the various XML elements and attributes found in WDDX packets. Basically, the idea is to define the basic types of information that can be stored in packets (see Table 16.2), and then allow these types to be arranged as complex structures that mimic arrays, structures (or associative arrays), or recordsets (see Table 16.3). The result is a system that allows just about any type of information typically tracked by applications, regardless of the programming language used, to be represented cleanly and clearly.

Table 16.2. Basic Data Elements Found in WDDX Packets

ELEMENT

DESCRIPTION

<string>

Surrounds any string value in the packet. Within the <string>, any extended or nonprintable characters can be represented by a <char code=''> element, where the code attribute is the UTF-8 number for the character, expressed as a two-digit hex value, such as 0C for a form feed.

<number>

Surrounds any numeric value. Note that WDDX does not get into issues regarding the range or precision of numbers. That is, there is no special consideration given to whether a number is an integer, a floating-point number, a single, a double, or the like.

<dateTime>

Surrounds any date/time value. In WDDX, dates always include a time portion as well, and may optionally include time zone information. Dates must be formatted according to the ISO8601 standard, as in 2006-12-25T09:05:32-5:0 to represent 9:05 a.m. (Eastern Standard Time) on December 25, 2006.

<boolean>

Represents a Boolean (true/false) value. The <boolean> element will always contain a value='true' or value='false' attribute accordingly.

<null>

Represents a null value, such as a NULL value retrieved from a database table.

<binary>

Represents a binary value, such as the contents of an image or other nontextual information. At this time, <binary> elements will always contain an encoding='base64' attribute. Between the <binary> tags, the actual binary data will appear, having first been converted to the Base 64 format.


Table 16.3. Container Elements Found in WDDX Packets

ELEMENT

DESCRIPTION

<wddxPacket>

Required. Surrounds the entire WDDX packet. At this time, always contains a version='1.0' attribute.

<header>

Required. Reserved for future use.

<data>

Required. Surrounds the actual data in the packet.

<array>

Represents an array. The <array> element always contains a length attribute that indicates how many items are in the array. Then the actual items in the array are included between the opening and closing <array> tags, with each item contained within its own <string>, <number>, <dateTime>, or whatever other element is appropriate.

<recordset>

Represents a recordset, such as a query object returned by <cfquery>. Within the <recordset> element, a <field> element is used to represent each column in the recordset.

<field>

Used only as a child of the <recordset> element. Represents a single column within the recordset. Within the <field> element, each row of data is represented by a <string>, <number>, or whatever element is appropriate.

<struct>

Represents a CFML structure (or whatever the corresponding data type is called in other programming languages). Within the <struct> element, a <var> element is used to represent each individual value in the structure.

<var>

Used only as a child of the <struct> element. Represents a single name/ value pair within the structure. The name of the value is provided with the name attribute; the actual value appears between the opening and closing <struct> tags, surrounded by a <string>, <number>, or whatever element is appropriate.


NOTE

In general, you never have to actually type the tags in Table 16.2 or Table 16.3. They are generated automatically for you by the <cfwddx> tag (or whatever WDDX serializer you are using).


NOTE

The WDDX DTD says it is legal for the <header> element to contain a single comment attribute that could hold some kind of human-readable description of what the packet contains. However, <cfwddx> provides no direct way to insert or read such a comment.




Advanced Macromedia ColdFusion MX 7 Application Development
Advanced Macromedia ColdFusion MX 7 Application Development
ISBN: 0321292693
EAN: 2147483647
Year: 2006
Pages: 240
Authors: Ben Forta, et al

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net