hessian-serialization.ietf

RESIN 3.2 最新源码

            Hessian 2.0 has a compact object form where the field names
            are only serialized once.  Following objects only need to serialize
            their values.
          </t>

          <t>
            The object instantiation creates a new object based on a previous
            definition.  The integer value refers to the object definition.
          </t>
        </section>

        <section title="Object examples">

          <figure anchor="object_example_1">
            <preamble>Object serialization</preamble>
            <artwork>
class Car {
  String color;
  String model;
}

out.writeObject(new Car("red", "corvette"));
out.writeObject(new Car("green", "civic"));

---

O                        # object definition (#0)
  t x00 x0b example.Car  # type is example.Car
  x92                    # two fields
  x05 color              # color field name
  x05 model              # model field name

o
  x90                    # object definition #0
  x03 red                # color field value
  x08 corvette           # model field value

o
  x90                    # object definition #0
  x05 green              # color field value
  x05 civic              # model field value
            </artwork>
          </figure>

          <figure anchor="object_example_2">
            <preamble></preamble>
            <artwork>
enum Color {
  RED,
  GREEN,
  BLUE,
}

out.writeObject(Color.RED);
out.writeObject(Color.GREEN);
out.writeObject(Color.BLUE);
out.writeObject(Color.GREEN);

---

O                         # object definition #0
  t x00 x0b example.Color # type is example.Color
  x91                     # one field
  x04 name                # enumeration field is "name"

o                         # object #0
  x90                     # object definition ref #0
  x03 RED                 # RED value

o                         # object #1
  x90                     # object definition ref #0
  x05 GREEN               # GREEN value

o                         # object #2
  x90                     # object definition ref #0
  x04 BLUE                # BLUE value

x4a x01                   # object ref #1, i.e. Color.GREEN
            </artwork>
          </figure>
        </section>
      </section>

      <section title="ref" anchor="#ref">
        <figure anchor="ref_grammar">
          <preamble>Ref Grammar</preamble>
          <artwork>
ref ::= R b3 b2 b1 b0
    ::= x4a b0
    ::= x4b b1 b0
          </artwork>
        </figure>

        <t>
          An integer referring to a previous list, map, or object instance.
          As each list, map or object is read from the input stream,
          it is assigned the integer position in the stream, i.e. the first
          list or map is '0', the next 
          is '1', etc.  A later ref can then use the previous object.  Writers 
          MAY generate refs.  Parsers MUST be able to 
          recognize them.
        </t>

        <t>
          ref can refer to incompletely-read items.  For example, a circular 
          linked-list will refer to the first link before the entire list has 
          been read.
        </t>

        <t>
          A possible implementation would add each map, list, and object
          to an array as it is read.  The ref will return the corresponding
          value from the array.  To support circular structures, the
          implementation would store the map, list or object immediately,
          before filling in the contents.
        </t>

        <t>
          Each map or list is stored into an array as it is
          parsed.  ref selects one of the stored objects.  The first
          object is numbered '0'.
        </t>

        <section title="Compact: two octet reference">
          <t>
            References between 0 and 255 can be encoded by two octets
          </t>

          <t>
            value = b0
          </t>
        </section>

        <section title="Compact: three octet reference">
          <t>
            References between 0 and 255 can be encoded in three octets
          </t>

          <t>
            value = (b1 &lt;&lt; 8) + b0
          </t>
        </section>

        <section title="Ref Examples">
          <figure anchor="ref_examples">
            <preamble>Circular list</preamble>
            <artwork>
list = new LinkedList();
list.data = 1;
list.tail = list;

---
O
  x9a LinkedList
  x92
  x04 head
  x04 tail

o x90      # object stores ref #0
  x91      # data = 1
  x4b x00  # next field refers to itself, i.e. ref #0
            </artwork>
          </figure>
        </section>

        <t>
          ref only refers to list, map and objects elements.
          Strings and binary data, in particular, will only share references
          if they're wrapped in a list or map.
        </t>
      </section>

      <section title="string" anchor="#string">
        <figure anchor="string_grammar">
          <preamble>String Grammar</preamble>
          <artwork>
string ::= s b1 b0 &lt;utf8-data> string
       ::= S b1 b0 &lt;utf8-data>
       ::= [x00-x1f] &lt;utf8-data>
          </artwork>
        </figure>

        <t> 
          A 16-bit unicode character string encoded in UTF-8.  Strings are 
          encoded in chunks. x53 ('S') represents the final chunk
          and x73 ('s') represents any non-final chunk.  Each chunk
          has a 16-bit length value.
        </t>

        <t>
          The length is the number of characters, which may be different than
          the number of bytes.
        </t>

        <t>String chunks may not split surrogate pairs.</t>

        <section title="Compact: short strings">
          <t>
            Strings with length less than 32 may be encoded with a single
            octet length [x00-x1f].
          </t>

          <t>
            value = code
          </t>
        </section>

        <section title="String Examples">
          <figure anchor="string_examples">
            <artwork>
x00               # "", empty string
x05 hello         # "hello"
x01 xc3 x83       # "\u00c3"

S x00 x05 hello   # "hello" in long form

s x00 x07 hello,  # "hello, world" split into two chunks
  x05 world
            </artwork>
          </figure>
        </section>
      </section>

      <section title="type" anchor="#type">
        <figure anchor="type_grammar">
          <preamble>Type Grammar</preamble>
          <artwork>
type ::= 't' b1 b0 &lt;type-string>
     ::= x4a b0
          </artwork>
        </figure>

        <t>A <xref target="#map">map</xref> or <xref target="#list">list</xref>
        MAY include a type attribute indicating the type name of the
        map or list for object-oriented languages.</t>

        <t>Each type is added to the <xref target="#type-map">type map</xref>
        for future reference.</t>
      </section>

        <section title="Compact: type references">
          <t>
            Repeated type strings MAY use the
            <xref target="#type-map">type map</xref> to refer to a previously
            used type.  The type reference is zero-based over all the
            types encountered during parsing.
          </t>
        </section>
    </section>

    <section title="Reference Maps">
      <t>Hessian 2.0 has 3 internal reference maps:</t>
      <list style="numbers">
        <t>An map/object/list reference map.</t>
        <t>An class definition map.</t>
        <t>A type (class name) map.</t>
      </list>

      <t>The value reference map lets Hessian support arbitrary
      graphs, and recursive and circular data structures.</t>

      <t>The class and type maps improve Hessian efficiency by
      avoiding repetition of common string data.</t>

      <section title="value reference" anchor="#ref-map">
        <t>Hessian supports arbitrary graphs by
        adding <xref target="#list">list</xref>,
        <xref target="#object">object</xref>, and 
        <xref target="#map">map</xref> as it encounters them in
        the bytecode stream.</t>

        <t>Parsers MUST store each list, object and map in the reference
        map as they are encountered.</t>

        <t>The stored objects can be used with a <xref target="#ref">ref</xref>
        bytecode.</t>
      </section>

      <section title="class reference" anchor="#class-map">
        <t>Each <xref target="#object">object definition</xref> is
        automatically added to the class-map.  Parsers MUST add a
        class definition to the class map as each is encountered.
        Following object instances will refer to the defined class.</t>
      </section>

      <section title="type reference" anchor="#type-map">
        <t>The <xref target="#type">type</xref> strings for
        <xref target="#map">map</xref> and <xref target="#list">list</xref>
        values are stored in a type map for reference.</t>

        <t>Parsers MUST add a type string to the type map as
        each is encountered.</t>
    </section>
    </section>

    <section title="Bytecode map">

      <t>
        Hessian is organized as a bytecode protocol.  A Hessian reader 
        is essentially a switch statement on the initial octet.
      </t>

      <figure anchor="bytecode_encoding">
        <preamble>Bytecode Encoding</preamble>
        <artwork>
x00 - x1f    # utf-8 string length 0-32
x20 - x2f    # binary data length 0-16
x30 - x37    # reserved
x38 - x3f    # long from -x40000 to x3ffff
x40 - x41    # reserved
x42          # 8-bit binary data final chunk ('B')
x43          # reserved ('C' streaming call)
x44          # 64-bit IEEE encoded double ('D')
x45          # reserved ('E' envelope)
x46          # boolean false ('F')
x47          # reserved
x48          # reserved ('H' header)
x49          # 32-bit signed integer ('I')
x4a          # reference to 1-256th map/list
x4b          # reference to 1-65536th map/list
x4c          # 64-bit signed long integer ('L')
x4d          # map with optional type ('M')
x4e          # null ('N')
x4f          # object definition ('O')
x50          # reserved ('P' streaming message/post)
x51          # reserved
x52          # reference to map/list - integer ('R')
x53          # utf-8 string final chunk ('S')
x54          # boolean true ('T')
x55          # reserved
x56          # list/vector ('V')
x57 - x62    # reserved
x62          # 8-bit binary data non-final chunk ('b')
x63          # reserved ('c' call for RPC)
x64          # UTC time encoded as 64-bit long milliseconds since 
             #  epoch ('d')
x65          # reserved
x66          # reserved ('f' for fault for RPC)
x67          # double 0.0
x68          # double 1.0
x69          # double represented as byte (-128.0 to 127.0)
x6a          # double represented as short (-32768.0 to 327676.0)
x6b          # double represented as float
x6c          # list/vector length ('l')
x6d          # reserved ('m' method for RPC call)
x6e          # list/vector compact length
x6f          # object instance ('o')
x70          # reserved ('p' - message/post)
x71          # reserved
x72          # reserved ('r' reply for message/RPC)
x73          # utf-8 string non-final chunk ('s')
x74          # map/list type ('t')
x75          # type-ref
x76          # compact vector ('v')
x77          # long encoded as 32-bit int
x78 - x79    # reserved
x7a          # list/map terminator ('z')
x7b - x7f    # reserved
x80 - xbf    # one-octet compact int (-x10 to x3f, x90 is 0)
xc0 - xcf    # two-octet compact int (-x800 to x3ff)
xd0 - xd7    # three-octet compact int (-x40000 to x3ffff)
xd8 - xef    # one-octet compact long (-x8 to x10, xe0 is 0)
xf0 - xff    # two-octet compact long (-x800 to x3ff, xf8 is 0)
        </artwork>
      </figure>

    </section>
  </middle>

  <back>
  </back>
 
</rfc>