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.
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. |