hessian-serialization.ietf

RESIN 3.2 最新源码

      </section>

      <section title="int" anchor="#int">
        <figure anchor="integer_grammar">
          <preamble>Integer Grammar</preamble>
          <artwork>
int ::= 'I' b3 b2 b1 b0
    ::= [x80-xbf]
    ::= [xc0-xcf] b0
    ::= [xd0-xd7] b1 b0
          </artwork>
        </figure>

        <t>
          A 32-bit signed integer.  An integer is represented by the
          octet x49 ('I') followed by the 4 octets of the integer
          in big-endian order.
        </t>

        <t>
          value = (b3 &lt;&lt; 24) + (b2 &lt;&lt; 16) + (b1 &lt;&lt; 8) + b0;
        </t>

        <section title="Compact: single octet integers">
          <t>
            Integers between -16 and 47 can be encoded by a single octet in the
            range x80 to xbf.
          </t>

          <t>
            value = code - 0x90
          </t>
        </section>

        <section title="Compact: two octet integers">
          <t>
            Integers between -2048 and 2047 can be encoded in two octets with
            the leading byte in the range xc0 to xcf.
          </t>

          <t>
            value = ((code - 0xc8) &lt;&lt; 8) + b0;
          </t>
        </section>

        <section title="Compact: three octet integers">
          <t>
            Integers between -262144 and 262143 can be encoded in three bytes 
            with the leading byte in the range xd0 to xd7.
          </t>

          <t>
            value = ((code - 0xd4) &lt;&lt; 16) + (b1 &lt;&lt; 8) + b0;
          </t>
        </section>

        <section title="Integer Examples">
          <figure anchor="integer_examples">
            <artwork>
x90                # 0
x80                # -16
xbf                # 47

xc8 x00            # 0
xc0 x00            # -2048
xc7 x00            # -256
xcf xff            # 2047

xd4 x00 x00        # 0
xd0 x00 x00        # -262144
xd7 xff xff        # 262143

I x00 x00 x00 x00  # 0
I x00 x00 x01 x2c  # 300
            </artwork>
          </figure>
        </section>
      </section>

      <section title="list" anchor="#list">
        <figure anchor="list_grammar">
          <preamble>List Grammar</preamble>
          <artwork>
list ::= V type? length? value* z
     ::= v int int value*
          </artwork>
        </figure>

        <t>
          An ordered list, like an array.  All lists have a type string, a 
          length, a list of values, and a trailing octet x7a ('z').
          The type string may be an arbitrary UTF-8 string understood by
          the service. The length may be omitted to indicate that
          the list is variable length.
        </t>

        <t>
          Each list item is added to the reference list to handle shared and 
          circular elements.  See the ref element.
        </t>

        <t>
          Any parser expecting a list must also accept a null or a shared ref.
        </t>

        <t>
          The valid values of type are not specified in this document and 
          may depend on the specific application.  For example, a server 
          implemented in a language with static typing which exposes an Hessian 
          interface can use the type information to instantiate the specific 
          array type.  On the other hand, a server written in a dynamicly-typed 
          language would likely ignore the contents of type entirely and create 
          a generic array.
        </t>

        <section title="Compact: repeated list">
          <t>
            Hessian 2.0 allows a compact form of the list for successive lists 
            of the same type where the length is known beforehand.  The type 
            and length are encoded by integers, where the type is a reference 
            to an earlier specified type.
          </t>
        </section>

        <section title="List examples">
          <figure anchor="list_example_1">
            <preamble>
              Serialization of a typed int array: int[] = {0, 1}
            </preamble>
            <artwork>
V
  t x00 x04 [int     # encoding of int[] type
  x6e x02            # length = 2
  x90                # integer 0
  x91                # integer 1
  z
            </artwork>
          </figure>

          <figure anchor="list_example_2">
            <preamble>Anonymous variable-length list = {0, "foobar"}</preamble>
            <artwork>
V
  t x00 x04 [int     # encoding of int[] type
  x6e x02            # length = 2
  x90                # integer 0
  x91                # integer 1
  z
            </artwork>
          </figure>

          <figure anchor="list_example_3">
            <preamble>Repeated list type</preamble>
            <artwork>
V
  t x00 x04 [int   # type for int[] (save as type #1)
  x63 x02          # length 2
  x90              # integer 0
  x91              # integer 1
  z

v
  x91              # type reference to int[] (integer #1)
  x92              # length 2
  x92              # integer 2
  x93              # integer 3
            </artwork>
          </figure>
        </section>
      </section>

      <section title="long" anchor="#long">
        <figure anchor="long_grammar">
          <preamble>Long Grammar</preamble>
          <artwork>
long ::= L b7 b6 b5 b4 b3 b2 b1 b0
     ::= [xd8-xef]
     ::= [xf0-xff] b0
     ::= [x38-x3f] b1 b0
     ::= x77 b3 b2 b1 b0
          </artwork>
        </figure>

        <t>
          A 64-bit signed integer.  An long is represented by the
          octet x4c ('L' )
          followed by the 8-bytes of the integer in big-endian order.
        </t>

        <section title="Compact: single octet longs">
          <t>
            Longs between -8 and 15 are represented by a single octet in the
            range xd8 to xef.
          </t>

          <t>
             value = (code - 0xe0)
          </t>
        </section>

        <section title="Compact: two octet longs">
          <t>
            Longs between -2048 and 2047 are encoded in two octets with
            the leading byte in the range xf0 to xff.
          </t>

          <t>
             value = ((code - 0xf8) &lt;&lt; 8) + b0
          </t>
        </section>

        <section title="Compact: three octet longs">
          <t>
            Longs between -262144 and 262143 are encoded in three octets with
            the leading byte in the range x38 to x3f.
          </t>

          <t>
             value = ((code - 0x3c) &lt;&lt; 16) + (b1 &lt;&lt; 8) + b0
          </t>
        </section>

        <section title="Compact: four octet longs">
          <t>
            Longs between which fit into 32-bits are encoded in five octets with
            the leading byte x77.
          </t>

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

        <section title="Long Examples">
          <figure anchor="long_examples">
            <artwork>
xe0                  # 0
xd8                  # -8
xef                  # 15

xf8 x00              # 0
xf0 x00              # -2048
xf7 x00              # -256
xff xff              # 2047

x3c x00 x00          # 0
x38 x00 x00          # -262144
x3f xff xff          # 262143

x77 x00 x00 x00 x00  # 0
x77 x00 x00 x01 x2c  # 300

L x00 x00 x00 x00 x00 x00 x01 x2c  # 300
            </artwork>
          </figure>
        </section>
      </section>

      <section title="map" anchor="#map">
        <figure anchor="map_grammar">
          <preamble>Map Grammar</preamble>
          <artwork>
map        ::= M type? (value value)* z
          </artwork>
        </figure>

        <t>
          Represents serialized maps and can represent objects.
          The type element describes the type of the map.
        </t>

        <t>
          The type may be empty, i.e. a zero length.  The parser is responsible 
          for choosing a type if one is not specified.  For objects, 
          unrecognized keys will be ignored.
        </t>

        <t>
          Each map is added to the reference list.  Any time the parser expects 
          a map, it must also be able to support a null or a ref.
        </t>

        <t>The type is chosen by the service.</t>

        <section title="Map examples">
          <figure anchor="map_example_1">
            <preamble>A sparse array</preamble>
            <artwork>
map = new HashMap();
map.put(new Integer(1), "fee");
map.put(new Integer(16), "fie");
map.put(new Integer(256), "foe");

---

M
  x91       # 1
  x03 fee   # "fee"

  xa0       # 16
  x03 fie   # "fie"

  xb9 x00   # 256
  x03 foe   # "foe"

  z
            </artwork>
          </figure>

          <figure anchor="map_example_2">
            <preamble>Map Representation of a Java Object</preamble>
            <artwork>
public class Car implements Serializable {
  String color = "aquamarine";
  String model = "Beetle";
  int mileage = 65536;
}

---
M
  t x00 x13 com.caucho.test.Car  # type

  x05 color                # color field
  x0a aquamarine

  x05 model                # model field
  x06 Beetle

  x07 mileage              # mileage field
  I x00 x01 x00 x00
  z
            </artwork>
          </figure>
      </section>
      </section>

      <section title="null" anchor="#null">
        <figure anchor="null_grammar">
          <preamble>Null Grammar</preamble>
          <artwork>
null ::= N
          </artwork>
        </figure>

        <t>Null represents a null pointer.</t>

        <t>The octet 'N' represents the null value.</t>
      </section>

      <section title="object" anchor="#object">
        <figure anchor="object_grammar">
          <preamble>Object Grammar</preamble>
          <artwork>
object     ::= 'o' int value*

class-def  ::= 'O' type int string*
          </artwork>
        </figure>

        <section title="Compact: class definition">
          <t>
            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 definition includes a mandatory type string, the number 
            of fields, and the field names.  The object definition is stored in 
            the object definition map and will be referenced by object 
            instances with an integer reference.
          </t>
        </section>

        <section title="Compact: object instantiation">
          <t>