📄 hessian-1.0-spec.xtp
字号:
<document> <header> <product>resin</product> <title>Hessian 1.0.2 Specification</title> <date>May 12, 2006</date> <description> <p>Hessian is a compact binary protocol for connecting web services.</p> <p>Because Hessian is a small protocol, J2ME devices like cell-phones can use it to connect to Resin servers. Because it's powerful, it can be used for EJB services.</p> </description> </header> <body> <localtoc/><s1 title="Design Goals"><p>The Hessian web services protocol was created as alightweight binary alternative to the XML-based web services protocols.</p><p>The <a href="http://www.caucho.com/hessian">Hessian home page</a>contains the latest information about Hessian.</p><p>Unlike older binary protocols, Hessian is both self-describingand portable across languages. The wire protocol for webservices should be invisible to application writers. Wire protocolsshould not require external schema or IDL.</p><p>Given the EJB environment, the Hessian protocol has thefollowing requirements:</p><ul><li>It must support XML as a first class object.</li><li>It must not require external IDL or schema definitions; it should beinvisible to application writers.</li><li>It must have sufficient power to serialize Java.</li><li>It must have sufficient power to support EJB.</li><li>It must allow non-Java clients to use web services.</li><li>It must allow web services to deployed as a Servlet.</li><li>It must be simple so it can be effectively tested.</li><li>It must be as fast as possible.</li><li>It should support transaction contexts.</li></ul></s1><s1 title="Serialization"><p>Hessian's object serialization has 9 primitive types:</p><ol><li><a href="#boolean">boolean</a></li><li>32-bit <a href="#int">int</a></li><li>64-bit <a href="#long">long</a></li><li>64-bit <a href="#double">double</a></li><li>64-bit <a href="#date">date</a></li><li>UTF8-encoded <a href="#string">string</a></li><li>UTF8-encoded <a href="#xml">xml</a></li><li>raw <a href="#binary">binary</a> data</li><li><a href="#remote">remote</a> objects</li></ol><p>It has 2 combining constructs:</p><ol><li><a href="#list">list</a> for lists and arrays</li><li><a href="#map">map</a> for objects and hash tables.</li></ol><p>Finally, it has 2 special contructs:</p><ol><li><a href="#null">null</a> for null values</li><li><a href="#ref">ref</a> for shared and circular object references.</li></ol><s2 title="null" type="defun"><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><example title="null">null ::= N</example></s2><s2 title="boolean" type="defun"><p>The byte <var>'F'</var> represents false and the byte <var>'T'</var>represents true.</p><def>boolean ::= T ::= F</def><example title="boolean true">T</example></s2><s2 title="int" type="defun"><p>A 32-bit signed integer. An integer is represented by thebyte <var>'I'</var> followed by the 4-bytes of the integer in big-endianorder</p><def>int ::= I b32 b24 b16 b8</def><example title="integer 300">I x00 x00 x01 x2c</example></s2><s2 title="long" type="defun"><p>A 64-bit signed integer. An long is represented by thebyte <var>'L'</var> followed by the 8-bytes of the integer in big-endian order</p><def>long ::= L b64 b56 b48 b40 b32 b24 b16 b8</def><example title="long 300">L x00 x00 x00 x00 x00 x00 x01 x2c</example></s2><s2 title="double" type="defun"><p>A 64-bit IEEE floating pointer number.</p><def>double ::= D b64 b56 b48 b40 b32 b24 b16 b8</def><example title="double 12.25">D x40 x28 x80 x00 x00 x00 x00 x00</example></s2><s2 title="date" type="defun"><p>Date represented by a 64-bits long of milliseconds since the epoch.</p><def>date ::= d b64 b56 b48 b40 b32 b24 b16 b8</def><example title="2:51:31 May 8, 1998">d x00 x00 x00 xd0 x4b x92 x84 xb8</example></s2><s2 title="string" type="defun"><p>A 16-bit unicode character string encoded in UTF-8.Strings are encoded in chunks. <var>'S'</var> represents the final chunkand <var>'s'</var> represents any initial chunk. Each chunk has a 16-bitlength value.</p><p>The length is the number of characters, which may be different thanthe number of bytes.</p><def>string ::= (s b16 b8 utf-8-data)* S b16 b8 utf-8-data</def><example title=""Hello" string">S x00 x05 hello</example></s2><s2 title="xml" type="defun"><p>An XML document encoded as a 16-bit unicode characterstring encoded in UTF-8.XML data is encoded in chunks. <var>'X'</var> represents the final chunkand <var>'x'</var> represents any initial chunk.</p><p>Each chunk has a 16-bitlength value. The length is the number of characters, which maybe different than the number of bytes.</p><def>xml ::= (x b16 b8 utf-8-data)* X b16 b8 utf-8-data</def><example title="trivial XML document">X x00 x10 <top>hello</top></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><s2 title="binary" type="defun"><p>A binary value.</p><p>Binary data is encoded in chunks. <var>'B'</var> represents the final chunkand <var>'b'</var> represents any initial chunk. Each chunk has a 16-bitlength value.</p><def>binary ::= (b b16 b8 binary-data)* B b16 b8 binary-data</def></s2><s2 title="list" type="defun"><p>An ordered list, like an array. All lists have a type string,a length, a list of objects, and a trailing 'z'.The type string may be an arbitrary UTF-8 string understoodby the service (often a Java class name, but this isn't required.)The length may be -1 to indicate that the list is variable length.</p><def>list ::= V <var>type</var>? <var>length</var>? <var>object</var>* z</def><p>Each <var>list</var> item is added to the reference list to handleshared and circular elements. See the<var>ref</var> element.</p><p>Any parser expecting a <var>list</var> must also accept a <var>null</var>or a shared <var>ref</var>.</p><results title="serialization of a Java int[] = {0, 1}">V t x00 x04 [int l x00 x00 x00 x02 I x00 x00 x00 x00 I x00 x00 x00 x01 z</results><results title="anonymous variable-length list = {0, "foobar"}">V I x00 x00 x00 x00 S x00 x06 foobar z</results><note>The valid values of <var>type</var> are not specified in thisdocument and may depend on the specific application. For example, aJava EJB server which exposes an Hessian interface can use the <var>type</var>information to instantiate the specific array type.On the other hand, a Perl server would likely ignore the contents of <var>type</var>entirely and create a generic array.</note></s2><s2 title="map" type="defun"><p>Represents serialized objects and Maps. The <var>type</var>element describes the type of the map. Objects are represented by amap from field names to their values and <var>type</var> is the classof the object itself.</p><def>map ::= M t b16 b8 type-string (<var>object</var>, <var>object</var>)* z</def><p>The <var>type</var> may be empty, i.e. a zero length. The parser isresponsible 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 theparser expects a <var>map</var>, it must also be able to support a<var>null</var> or a <var>ref</var>.</p><example title="Serialization of a Java Object">public class Car implements Serializable { String model = "Beetle"; String color = "aquamarine"; int mileage = 65536;}</example><results>M t x00 x13 com.caucho.test.Car S x00 x05 model S x00 x06 Beetle S x00 x05 color S x00 x0a aquamarine S x00 x07 mileage I x00 x01 x00 x00 z</results><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");</example><results>M I x00 x00 x00 x01 S x00 x03 fee I x00 x00 x00 x10 S x00 x03 fie I x00 x00 x01 x00 S x00 x03 foe z</results><note>The <var>type</var> is chosen by the service. Often it may be theJava classname describing the service.</note></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 theinput 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 notrequired to generate <var>refs</var>, but parsers must be able to recognize them.</p><def>ref ::= R b32 b24 b16 b8</def><p><var>ref</var> can refer to incompletely-read items. For example, acircular linked-list will refer to the first link before the entire listhas been read.</p><p>A possible implementation would add each <var>map</var> and <var>list</var> to anarray as it's read. The <var>ref</var> will return the correspondingobject from the array. To support circular structures, theimplementation would store the <var>map</var> or <var>list</var> immediately,before filling in the object's contents.</p><p>Each <list> or <array> is stored into an array as it isparsed. <ref> selects one of the stored objects. The firstobject 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 sharereferences 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 b16 b8 type-name S b16 b8 url</def><results title="EJB Session Reference">r t x00 x0c test.TestObj S x00 x24 http://slytherin/ejbhome?id=69Xm8-zW</results></s2></s1><s1 title="Call"><p>A Hessian call invokes a method on an object with an argumentlist. The object is specified by the container, e.g. for a HTTPrequest, it's the HTTP URL. The arguments arespecified by Hessian serialization.</p>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -