hessian-2.0-spec.xtp

RESIN 3.2 最新源码

  z
</results>

<results title="anonymous variable-length list = {0, &quot;foobar&quot;}">
V
  x90                # integer 0
  x06 foobar         # "foobar"
  z
</results>

<example title="repeated list type">
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
</example>

</s3>

</s2>

<s2 title="long" type="defun">

<def>
long ::= L b7 b6 b5 b4 b3 b2 b1 b0
     ::= [xd8-xef]
     ::= [xf0-xff] b0
     ::= [x38-x3f] b1 b0
     ::= x77 b3 b2 b1 b0
</def>

<p>A 64-bit signed integer.  An long is represented by the
byte <var>'L'</var> followed by the 8-bytes of the integer in big-endian order
</p>

<s3 title="Compact: single octet longs">

<p>Longs between -8 and 15 are represented by a single byte in the
range <code>xd8</code> to <code>xef</code>.
The value of the long is <code>code - xe0</code>.</p>

</s3>

<s3 title="Compact: two octet longs (byte)">

<p>Longs between -2048 and 2047 are encoded in two bytes with
the leading byte in the range <code>xf0</code> to <code>xff</code>.
The value of the long is <code>256 * (code - xf8) + b0</code>.</p>

</s3>

<s3 title="Compact: three octet longs (short)">

<p>Longs between -262144 and 262143 are encoded in three bytes with
the leading byte in the range <code>x38</code> to <code>x3f</code>.
The value of the long is <code>65536 * (code - x3c) + 256 * b1 + b0</code>.</p>

</s3>

<s3 title="Compact: four octet longs (int)">

<p>Longs between which fit into 32-bits are encoded in five bytes with
the leading byte <code>x77</code>.</p>

</s3>

<example title="long examples">
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
</example>

</s2>

<s2 title="map" type="defun">

<def>
map        ::= M type? (object object)* z
           ::= 'o' int object*

object-def ::= 'O' type int string*
</def>

<p>Represents serialized objects and Maps. The <var>type</var>
element describes the type of the map.  Objects are represented by a
map from field names to their values and <var>type</var> is the class
of the object itself.</p>

<p>The <var>type</var> 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.</p>

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

<note>The <var>type</var> is chosen by the service.  Often it may be the
Java classname describing the service.</note>

<s3 title="Compact: object definition">

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

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

</s3>

<s3 title="Compact: object instantiation">

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

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

</s3>

<s3 title="map examples">

<example title="A sparse array">
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
</example>

<example title="Serialization of a Java Object">
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
</example>

<example title="Compact Object serialization">
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
</example>

<example title="Enumeration serialization">
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
</example>

</s3>

</s2>

<s2 title="null" type="defun">

<def title="null grammar">
null ::= N
</def>

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

<p>The byte <var>'N'</var> represents the null pointer.</p>

<p><var>null</var> values are allowed in place of any <var>string</var>, <var>xml</var>,
<var>binary</var>, <var>list</var>, <var>map</var>, or <var>remote</var>.</p>
</s2>

<s2 title="ref" type="defun">
<p>An integer referring to a previous <var>list</var> or <var>map</var>
instance.  As each <var>list</var> or <var>map</var> is read from the
input stream, it is assigned the integer position in the stream,
i.e. the first <var>list</var> or <var>map</var> is '0', the next is '1', etc.
A later <var>ref</var> can then use the previous object.  Writers are not
required to generate <var>refs</var>, but parsers must be able to recognize them.
</p>

<def>
ref ::= R b3 b2 b1 b0
</def>

<p><var>ref</var> 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.</p>

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

<p>Each &lt;list&gt; or &lt;array&gt; is stored into an array as it is
parsed.  &lt;ref&gt; selects one of the stored objects.  The first
object is numbered '0'.</p>

<example title="circular list">
list = new LinkedList();
list.head = 1;
list.tail = list;
</example>
<results>
M t x00 x0a LinkedList
  S x00 x04 head
  I x00 x00 x00 x01
  S x00 x04 tail
  R x00 x00 x00 x00
  z
</results>

<note><var>ref</var> only refers to <var>list</var> and <var>map</var> elements.
<var>string</var> and <var>binary</var>, in particular, will only share
references if they're wrapped in a <var>list</var> or <var>map</var>.</note>

</s2>

<s2 title="remote" type="defun">
<p>A reference to a remote object.  The remote has a
<var>type</var> and a utf-8 string representing the object's URL.</p>

<def>
remote ::= r t b1 b0 &lt;type-name> string
</def>

<results title="EJB Session Reference">
r t x00 x0c test.TestObj
  S x00 x24 http://slytherin/ejbhome?id=69Xm8-zW
</results>

</s2>

<s2 title="string" type="defun">

<def title="string grammar">
string ::= s b1 b0 &lt;utf-8-data> string
       ::= S b1 b0 &lt;utf-8-data>
       ::= [x00-x1f] &lt;utf-8-data>
</def>

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

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

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

<s3 title="Compact: short strings">

<p>Strings with length less than 32 may be encoded with a single
byte length [x00-x1f].</p>

</s3>

<s3 title="string examples">

<example title="String examples">
x00             # "", empty string
x05 hello       # "hello"
x01 xc3 x83     # "\u00c3"

S x00 x05 hello # "hello"
</example>

</s3>

</s2>

<s2 title="xml" type="defun">

<def title="xml grammar">
xml ::= x b1 b0 &lt;utf-8-data> xml
    ::= X b1 b0 utf-8-data
</def>
<p>An XML document encoded as a 16-bit unicode character
string encoded in UTF-8.
XML data is encoded in chunks.  <var>'X'</var> represents the final chunk
and <var>'x'</var> represents any initial chunk.</p>

<p>Each chunk has a 16-bit
length value.  The length is the number of characters, which may
be different than the number of bytes.</p>

<example title="trivial XML document">
X x00 x10 &lt;top&gt;hello&lt;/top&gt;
</example>

<note>Because this document does not define the language mapping,
implementations are free to return a string when reading an <var>xml</var>
entity.</note>

</s2>

</s1>

<s1 title="Messages and Envelopes">

<p>Hessian message syntax organizes serialized data for messaging and RPC
applications.  The envelope syntax enables compression,
encryption, signatures, and any routing or context headers to wrap a
Hessian message.</p>

<ul>
<li>Call ('c'): contains a Hessian RPC call, with a method name and arguments.</li>
<li>Envelope ('E'): wraps a Hessian message for compression, encryption, etc.  Envelopes can be nested.</li>
<li>Message ('p'): contains a sequence of serialized Hessian objects.</li>
<li>Reply ('r'): contains a reply to a Hessian RPC call.</li>
</ul>

<s2 title="Call">

<def>
call ::= c x02 x00 m b1 b0 &lt;method-string> object* z
</def>

<p>A Hessian call invokes a method on an object with an argument
list.  The object is specified by the container, e.g. for a HTTP
request, it's the HTTP URL.  The arguments are
specified by Hessian serialization.</p>

<s3 title="Methods and Overloading">

<p>Method names must be unique.  Two styles of overloading are
supported: overloading by number of argumetns and overloading
by argument types.  Overloading is permitted by
encoding the argument types in the method names.  The types of
the actual arguments must not be used to select the methods.</p>

<p>Method names beginning with <var>_hessian_</var> are reserved.</p>

<p>Servers should accept calls with either the mangled method name
or the unmangled method name.  Clients should send the mangled method name.</p>

<note>See the Java binding for a possible overloading scheme.</note>

<example>add(int a, int b)</example>
<results>add_int_int</results>
<example>add(double a, double b)</example>
<results>add_double_double</results>
<example>add(shopping.Cart cart, shopping.Item item)</example>
<results>add_shopping.Cart_shopping.Item</results>