hessian-serialization.ietf

RESIN 3.2 最新源码

<?xml version="1.0"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">

<rfc category="std" ipr="full3978" docName="hessian.txt">

<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>

<?rfc toc="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="no" ?>

  <front>
    <title>Hessian 2.0 Serialization Protocol</title>
    <author initials="S." surname="Ferguson" fullname="Scott Ferguson">
      <organization>Caucho Technology Inc.</organization>
      <address>
        <postal>
          <street>P.O. Box 9001</street>
          <city>La Jolla</city>
          <region>CA</region>
          <code>92038</code>
          <country>USA</country>
        </postal>
        <email>[e-mail]</email>
      </address>
    </author>
    <author initials="E." surname="Ong" fullname="Emil Ong">
      <organization>Caucho Technology Inc.</organization>
      <address>
        <postal>
          <street>P.O. Box 9001</street>
          <city>La Jolla</city>
          <region>CA</region>
          <code>92038</code>
          <country>USA</country>
        </postal>
        <email>[e-mail]</email>
      </address>
    </author>
    <date month="August" year="2007" />
  </front>
  
  <middle>
    <section title="Introduction">
      <t>
        Hessian is a dynamically-typed, binary serialization and Web
Services protocol designed for object-oriented transmission.
      </t>
    </section>

    <section title="Design Goals">
      <t>
        Hessian is dynamically-typed, compact, and portable across languages.
      </t>
      <t>
      The Hessian protocol has the following design goals:
      </t>
      <list style="symbols">
        <t>
          It must self-describe the serialized types, i.e. not require
external schema or interface definitions.
        </t>
        <t>It must be language-independent, including supporting
scripting languages.</t>
        <t>It must be readable or writable in a single pass.</t>
        <t>It must be as compact as possible.</t>
        <t>
          It must be simple so it can be effectively tested and implemented.
        </t>
        <t>It must be as fast as possible.</t>
        <t>It must support Unicode strings.</t>
        <t>
          It must support 8-bit binary data without escaping or using 
          attachments.
        </t>
        <t>
          It must support encryption, compression, signature, and
          transaction context envelopes.
        </t>
      </list>
    </section>

    <section title="Hessian Grammar">
      <figure anchor="serialization_grammar">
        <preamble>Serialization Grammar</preamble>
        <artwork>
           # starting production
top        ::= value

           # 8-bit binary data split into 64k chunks
binary     ::= 'b' b1 b0 &lt;binary-data> binary # non-final chunk
           ::= 'B' b1 b0 &lt;binary-data>        # final chunk
           ::= [x20-x2f] &lt;binary-data>        # binary data of 
                                                 #  length 0-15

           # boolean true/false
boolean    ::= 'T'
           ::= 'F'

           # definition for an object (compact map)
class-def  ::= 'O' type int string*

           # time in UTC encoded as 64-bit long milliseconds since 
           #  epoch
date       ::= 'd' b7 b6 b5 b4 b3 b2 b1 b0

           # 64-bit IEEE double
double     ::= 'D' b7 b6 b5 b4 b3 b2 b1 b0
           ::= x67                   # 0.0
           ::= x68                   # 1.0
           ::= x69 b0                # byte cast to double 
                                     #  (-128.0 to 127.0)
           ::= x6a b1 b0             # short cast to double
           ::= x6b b3 b2 b1 b0       # 32-bit float cast to double

           # 32-bit signed integer
int        ::= 'I' b3 b2 b1 b0
           ::= [x80-xbf]             # -x10 to x3f
           ::= [xc0-xcf] b0          # -x800 to x7ff
           ::= [xd0-xd7] b1 b0       # -x40000 to x3ffff

           # list/vector length 
length     ::= 'l' b3 b2 b1 b0
           ::= x6e int

           # list/vector
list       ::= 'V' type? length? value* 'z'
           ::= 'v' int int value*    # type-ref, length

           # 64-bit signed long integer
long       ::= 'L' b7 b6 b5 b4 b3 b2 b1 b0
           ::= [xd8-xef]             # -x08 to x0f
           ::= [xf0-xff] b0          # -x800 to x7ff
           ::= [x38-x3f] b1 b0       # -x40000 to x3ffff
           ::= x77 b3 b2 b1 b0       # 32-bit integer cast to long

           # map/object
map        ::= 'M' type? (value value)* 'z'  # key, value map pairs

           # null value
null       ::= 'N'

           # Object instance
object     ::= 'o' int value*

           # value reference (e.g. circular trees and graphs)
ref        ::= 'R' b3 b2 b1 b0    # reference to nth map/list/object in 
                                  #  stream
           ::= x4a b0             # reference to 1-255th map/list/object
           ::= x4b b1 b0          # reference to 1-65535th map/list/object

           # UTF-8 encoded character string split into 64k chunks
string     ::= 's' b1 b0 &lt;utf8-data> string  # non-final chunk
           ::= 'S' b1 b0 &lt;utf8-data>         # string of length 
                                             #  0-65535
           ::= [x00-x1f] &lt;utf8-data>         # string of length 
                                             #  0-31

           # map/list types for OO languages
type       ::= 't' b1 b0 &lt;type-string>         # type name
           ::= x75 int                         # type reference

           # main production
value      ::= null
           ::= binary
           ::= boolean
           ::= date
           ::= double
           ::= int
           ::= list
           ::= long
           ::= map
           ::= class-def value
           ::= ref
           ::= string
        </artwork>
      </figure>
    </section>

    <section title="Serialization">
      <t>Hessian's object serialization has 8 primitive types:</t>
      <list style="numbers">
        <t>raw <xref target="#binary">binary</xref> data</t>
        <t><xref target="#boolean">boolean</xref></t>
        <t>64-bit <xref target="#date">date</xref></t>
        <t>64-bit <xref target="#double">double</xref></t>
        <t>32-bit <xref target="#int">int</xref></t>
        <t>64-bit <xref target="#long">long</xref></t>
        <t><xref target="#null">null</xref></t>
        <t>UTF8-encoded <xref target="#string">string</xref></t>
      </list>

      <t>It has 3 recursive types:</t>
      <list style="numbers">
        <t><xref target="#list">list</xref> for lists and arrays</t>
        <t><xref target="#map">map</xref> for maps and dictionaries</t>
        <t><xref target="#object">object</xref> for objects</t>
      </list>

      <t>Finally, it has one special contruct:</t>
      <list style="numbers">
        <t>
          <xref target="#ref">ref</xref> for shared and circular object 
          references.
        </t>
      </list>

      <t>Hessian 2.0 has 3 internal reference maps:</t>
      <list style="numbers">
        <t>An <xref target="#ref-map">object/list reference map</xref>.</t>
        <t>An <xref target="#class-map">class definition reference map</xref>.</t>
        <t>A <xref target="#type-map">type (class name) reference map</xref>.</t>
      </list>

      <section title="binary data" anchor="#binary">
        <figure anchor="binary_grammar">
          <preamble>Binary Grammar</preamble>
          <artwork>
binary ::= b b1 b0 &lt;binary-data> binary
       ::= B b1 b0 &lt;binary-data>
       ::= [x20-x2f] &lt;binary-data>
          </artwork>
        </figure>

        <t>
          Binary data is encoded in chunks.  The octet x42 ('B') encodes
          the final chunk and x62 ('b') represents any non-final chunk.
          Each chunk has a 16-bit length value.
        </t>

        <t>
          len = 256 * b1 + b0
        </t>

        <section title="Compact: short binary">
          <t>
            Binary data with length less than 15 may be encoded by a single
            octet length [x20-x2f].
          </t>

          <t>
            len = code - 0x20
          </t>
        </section>

        <section title="Binary Examples">
          <figure anchor="binary_examples">
            <artwork>
x20               # zero-length binary data

x23 x01 x02 x03   # 3 octet data

B x10 x00 ....    # 4k final chunk of data

b x04 x00 ....    # 1k non-final chunk of data
            </artwork>
          </figure>
        </section>
      </section>

      <section title="boolean" anchor="#boolean">
        <figure anchor="boolean_grammar">
          <preamble>Boolean Grammar</preamble>
          <artwork>
boolean ::= T
        ::= F
          </artwork>
        </figure>

        <t>The octet 'F' represents false and the octet T represents true.</t>

        <section title="Boolean Examples">
          <figure anchor="boolean_examples">
            <artwork>
T   # true
F   # false
            </artwork>
          </figure>
        </section>
      </section>

      <section title="date" anchor="#date">
        <figure anchor="date_grammar">
          <preamble>Date Grammar</preamble>
          <artwork>
date ::= d b7 b6 b5 b4 b3 b2 b1 b0
          </artwork>
        </figure>

        <t>
          Date represented by a 64-bit long of milliseconds since the
          Jan 1 1970 00:00H, UTC.
        </t>

        <section title="Date Examples">
          <figure anchor="date_examples">
            <artwork>
d x00 x00 x00 xd0 x4b x92 x84 xb8   # 2:51:31 May 8, 1998 UTC
            </artwork>
          </figure>
        </section>
      </section>

      <section title="double" anchor="#double">
        <figure anchor="double_grammar">
          <preamble>Double Grammar</preamble>
          <artwork>
double ::= D b7 b6 b5 b4 b3 b2 b1 b0
       ::= x67
       ::= x68
       ::= x69 b0
       ::= x6a b1 b0
       ::= x6b b3 b2 b1 b0
          </artwork>
        </figure>

        <t>A 64-bit IEEE floating pointer number.</t>

        <section title="Compact: double zero">
          <t>The double 0.0 can be represented by the octet x67</t>
        </section>

        <section title="Compact: double one">
          <t>The double 1.0 can be represented by the octet x68</t>
        </section>

        <section title="Compact: double octet">
          <t>
            Doubles between -128.0 and 127.0 with no fractional component
            can be represented in two octets by casting the byte value to a 
            double.
          </t>

          <t>
            value = (double) b0
          </t>
        </section>

        <section title="Compact: double short">
          <t>
            Doubles between -32768.0 and 32767.0 with no fractional component
            can be represented in three octets by casting the short value to a 
            double.
          </t>

          <t>
            value = (double) (256 * b1 + b0)
          </t>
        </section>

        <section title="Compact: double float">
          <t>
            Doubles which are equivalent to their 32-bit float representation
            can be represented as the 4-octet float and then cast to double.
          </t>
        </section>

        <section title="Double Examples">
          <figure anchor="double_examples">
            <artwork>
x67          # 0.0
x68          # 1.0

x69 x00      # 0.0
x69 x80      # -128.0
x69 xff      # 127.0

x70 x00 x00  # 0.0
x70 x80 x00  # -32768.0
x70 xff xff  # 32767.0

D x40 x28 x80 x00 x00 x00 x00 x00  # 12.25
            </artwork>
          </figure>
        </section>