home *** CD-ROM | disk | FTP | other *** search
/ CD Actual Thematic 7: Programming / CDAT7.iso / Share / Java / ScriptBuilder / NOSB30_TRIAL.exe / data1.cab / Program_Files / Wddx / wddx_0090.dtd next >
Encoding:
Text File  |  1998-10-05  |  10.2 KB  |  255 lines
  1. <!-- ************************************************************************
  2.      WDDX DTD:
  3.  
  4.      Author: Simeon Simeonov (simeons@allaire.com)
  5.  
  6.      Last modified: 9/25/1998
  7.  
  8.      Copyright (c) 1998 Allaire Corp. http://www.allaire.com
  9. -->
  10.  
  11. <!-- ************************************************************************
  12.      Introductory Notes:
  13.  
  14.      
  15.      What is WDDX:
  16.  
  17.      WDDX stands for Web Distributed Data eXchange. WDDX is a mechanism for
  18.      exchanging complex data structures between application environments. It
  19.      has been designed with web applications in mind. WDDX consists of a 
  20.      language and platform neutral representation of instantiated data based
  21.      on XML 1.0 (which is defined using this DTD) and a set of serializer/
  22.      deserializer components for every environment that uses WDDX. The 
  23.      process of creating an XML representation of application data is called
  24.      serialization. The process of instantiating application data from a 
  25.      WDDX XML representation is called deserialization.
  26.  
  27.      The WDDX DTD:
  28.  
  29.      The WDDX DTD can be used to validate WDDX packets. Packets are
  30.      representations of instantiated data structures in application 
  31.      environments. The following is an example of a WDDX packet:
  32.  
  33.           <?xml version='1.0'?>
  34.           <!DOCTYPE wddxPacket SYSTEM 'wddx_0090.dtd'>
  35.           <wddxPacket version='0.9'>
  36.              <header/>
  37.               <data>
  38.                   <struct>
  39.                      <var name='s'>
  40.                           <string>a string</string>
  41.                       </var>
  42.                       <var name='n'>
  43.                           <number>-12.456</number>
  44.                       </var>
  45.                       <var name='d'>
  46.                          <dateTime>1998-06-12T04:32:12</dateTime>
  47.                       </var>
  48.                      <var name='b'>
  49.                           <boolean value='true'/>
  50.                       </var>
  51.                       <var name='a'>
  52.                          <array length='2'>
  53.                              <number>10</number>
  54.                              <string>second element</string>
  55.                          </array>
  56.                      </var>
  57.                       <var name='obj'>
  58.                          <struct>
  59.                                <var name='s'>
  60.                                   <string>a string</string>
  61.                              </var>
  62.                               <var name='n'>
  63.                                  <number>-12.456</number>
  64.                               </var>
  65.                          </struct>
  66.                       </var>
  67.                      <var name='r'>
  68.                         <recordset rowCount='2' fieldNames='NAME,AGE'>
  69.                             <field name='NAME'>
  70.                                 <string>John Doe</string>
  71.                                 <string>Jane Doe</string>
  72.                             </field>
  73.                             <field name='AGE'>
  74.                                 <number>34</number>
  75.                                 <number>31</number>
  76.                             </field>
  77.                         </recordset>
  78.                      </var>
  79.                   </struct>
  80.              </data>
  81.          </wddxPacket>
  82.      
  83.      It defines a root level object that is a structure (also known as 
  84.      an associative array) of six properties:
  85.  
  86.      - s which is the string 'a string',
  87.      - n which is the number -12.456,
  88.      - d which is the date-time value June 12, 1998 4:32:12am,
  89.      - b which is the boolean value true,
  90.      - a which is an array of two elements (10 and 'second element'),
  91.      - obj which is a structure with two properties s and n, and
  92.      - r which is a recordset of two rows with fields NAME and AGE.
  93.           
  94.      Basic data types:
  95.      
  96.      WDDX supports the following basic data types: boolean (true/false), 
  97.      number, date-time, and string. 
  98.      
  99.      Numbers-
  100.      Numbers are internally represented with floating point numbers. Because 
  101.      of differences between WDDX-enabled languages, the range of numbers has 
  102.      been restricted to +/-1.7E+/-308. The precision has been restricted to 
  103.      15 digits after the decimal point. These requirements are consistent 
  104.      with an 8-byte floating point representation.
  105.  
  106.      Date-time values-
  107.      Date-time values are encoded according to the full form of ISO8601,
  108.      e.g., 1998-9-15T09:05:32+4:0. Note that single-digit values for months,
  109.      days, hours, minutes, or seconds do not need to be zero-prefixed. 
  110.      While timezone information is optional, it must be successfully parsed
  111.      and used to convert to local date-time values. Efforts should me made 
  112.      to ensure that the internal representation of date-time values does not 
  113.      suffer from Y2K problems and covers a sufficient range of dates. In 
  114.      particular, years must always be represented with four digits.
  115.  
  116.      Strings-
  117.      Strings can be of arbitrary length and must not contain embedded nulls.
  118.      To facilitate the inclusion of control characters in strings, the
  119.      <string> element can contain <char code='??'/> elements. The value of
  120.      the code attribute is a two-character representation of the UTF-8 hex 
  121.      code for a given control character. For example, <char code='0C'/>
  122.      represents the form feed character. Control characters are characters
  123.      in the UTF-8 range 00-1F. Note that tab (09) and newline (0A) characters
  124.      can be included directly in XML text. The XML 1.0 specification Section
  125.      2.11 requires XML processors to not pass carriage return (0D) characters
  126.      to applications. 
  127.      
  128.      Note on end-of-line handling-
  129.      End-of-line characters have platform and programming language specific 
  130.      representations. Different application environments may use either a 
  131.      single newline (0A), a single carriage return (0D), or a carriage return 
  132.      and newline combination (0D0A). For the purposes of successful data 
  133.      encoding and translation the elements <char code='0A'/> and 
  134.      <char code='0D'/> must be used to encode newline and carriage return 
  135.      characters when they should be preserved in the deserialized string. 
  136.      Note that Section 2.11 of the XML 1.0 specification requires XML 
  137.      processors to translate all occurences of carriage returns and the 
  138.      carriage return, newline combination to a single newline character. 
  139.      Therefore, for the purposes of XML, end-of-line is represented by a 
  140.      single newline character.
  141.  
  142.      Complex data types:
  143.  
  144.      WDDX supports the following complex data types: arrays, structures, and 
  145.      recordsets.
  146.  
  147.      Arrays-
  148.      Arrays are integer-indexed collections of objects of arbitrary type. 
  149.      The starting index value is usually 0 with the notable exception of 
  150.      CFML whose arrays have an initial index value of 1. Because of these
  151.      differences working with array indices can lead to non-portable data.
  152.  
  153.      Structures-
  154.      Structures are string-indexed collections of object of arbitrary type.
  155.      In many languages they are known as associative arrays. Structures
  156.      contain one or more variables. Because some of the languages supported
  157.      by WDDX are not case-sensitive, no two variable names can differ only
  158.      by their case.
  159.  
  160.      Recordsets-
  161.      Recordsets are tabular data encapsulations: a set of named fields with 
  162.      the same number of rows of data. Only simple data types can be stored in
  163.      recordsets. For tabular data storage of complex data types, an array of 
  164.      structures should be used. Because some of the languages supported by 
  165.      WDDX are not case-sensitive, no two field names can differ only by 
  166.      their case.
  167.  
  168.      Data type comparisons:
  169.  
  170.      The following table compares the basic WDDX data types with those of 
  171.      languages/technologies commonly used on the Web.
  172.      
  173.      WDDX Type         COM              Java Type           ECMAScript Type   
  174.      **************    *************    ****************    ***************   
  175.      boolean           boolean          boolean             boolean           
  176.      number            float?           float?              number            
  177.      dateTime          DATE             ??                  Date              
  178.      string            BSTR             java.lang.String    string            
  179.      array             VARIANT array    ??                  Array             
  180.      struct            IWDDXStruct      ??                  Object            
  181.      recordset         IWDDXRecordset   ??                  WddxRecordset     
  182.  
  183.  
  184.      More on data types:
  185.  
  186.      Null values-
  187.      WDDX provides no notion of a null object. Null objects should be 
  188.      serialized to empty strings. Upon deserialization it is up to the
  189.      component performing the operation to determine whether and where 
  190.      should empty strings be deserialized to null values. Null support
  191.      is one area where future extensions are likely.
  192.  
  193.      Serialization model-
  194.      WDDX serializes data using a model of pure aggregation. It has no
  195.      mechanism for handling object references. Aliased references will
  196.      result in multiple object instances being deserialized. WDDX 
  197.      serialization applied to a data structure that has cyclical references
  198.      will most likely result in infinite iteration/recursion, depending on
  199.      the serializer implementation. Object references support is another
  200.      area of potential future investigation.
  201.  
  202.      DTD verbosity:
  203.  
  204.      This DTD is purposefully made verbose to aid the readability of WDDX
  205.      packets. If packet size becomes an issue, compressing WDDX packets
  206.      using an HTTP-safe real time compression algorithm is likely to be a
  207.      much more appropriate solution than, for example, a DTD that uses one
  208.      character element and attribute names. Some experiments conducted at
  209.      Allaire suggest that 5 - 15 fold compression rates are achievable.
  210.  
  211. -->
  212.  
  213. <!ELEMENT wddxPacket (header, data)>
  214. <!ATTLIST wddxPacket
  215.           version CDATA #FIXED "0.9">
  216.  
  217. <!ELEMENT header (comment?)>
  218.  
  219. <!ELEMENT comment (#PCDATA)>
  220.  
  221. <!ELEMENT data (boolean | number | dateTime | string | array | struct | recordset)*>
  222.  
  223. <!ELEMENT boolean EMPTY>
  224. <!ATTLIST boolean 
  225.           value (true | false) #REQUIRED>
  226.  
  227. <!ELEMENT string (#PCDATA | char)*>
  228.  
  229. <!ELEMENT char EMPTY>
  230. <!ATTLIST char 
  231.           code CDATA #REQUIRED>
  232.  
  233. <!ELEMENT number (#PCDATA)>
  234.  
  235. <!ELEMENT dateTime (#PCDATA)>
  236.  
  237. <!ELEMENT array (boolean | number | dateTime | string | array | struct | recordset)*>
  238. <!ATTLIST array 
  239.           length CDATA #REQUIRED>
  240.  
  241. <!ELEMENT struct (var*)>
  242.  
  243. <!ELEMENT var (boolean | number | dateTime | string | array | struct | recordset)>
  244. <!ATTLIST var
  245.           name CDATA #REQUIRED>
  246.  
  247. <!ELEMENT recordset (field*)>       
  248. <!ATTLIST recordset 
  249.           rowCount CDATA #REQUIRED
  250.           fieldNames CDATA #REQUIRED>
  251.  
  252. <!ELEMENT field (boolean | number | dateTime | string)*>
  253. <!ATTLIST field
  254.           name CDATA #REQUIRED>
  255.