📄 hessian-2.0-spec.xtp
字号:
<document> <header> <product>resin</product> <title>Hessian 2.0 Specification (Draft 2)</title> <date>Jul 8, 2006</date> <description> <p>Hessian is a compact binary protocol for cross-platform web services and messaging.</p> </description> </header> <body> <localtoc/><s1 title="Design Goals"><p>The <a href="http://hessian.caucho.com">Hessian home page</a>contains the latest information about Hessian.</p><p>Unlike older binary protocols, Hessian is both self-describing,compact, and portable across languages. The wire protocol for webservices should be invisible to application writers, it should not requireexternal schema or IDL.</p><p>The Hessian protocol has the following design goals:</p><ul><li>It must not require external IDL or schema definitions,i.e. the protocol should be invisible to application code.</li><li>It must have sufficient power to serialize Java, including circular references.</li><li>It must be language-independent. In particular, it must allow non-Java clients to use web services.</li><li>It must be simple so it can be effectively tested and implemented.</li><li>It must be as fast as possible.</li><li>It must be as compact as possible.</li><li>It must support unicode strings.</li><li>It must support 8-bit binary data (i.e. without encoding or using attachments.)</li><li>It must allow web services to deployed as a Servlet.</li><li>It must have sufficient power to support EJB.</li><li>It must support encryption, compression, signature, andtransaction context envelopes.</li><li>Hessian 2.0 must be backwards compatible with Hessian 1.0.Hessian 2.0 parsers must be read Hessian 1.0 messages.</li></ul></s1><s1 title="Hessian 2.0 Grammar"><def title="Serialization Grammar"> # starting productiontop ::= object # 8-bit binary data split into 64k chunksbinary ::= 'b' b1 b0 <binary-data> binary # non-final chunk ::= 'B' b1 b0 <binary-data> # final chunk ::= [x20-x2f] <binary-data> # binary data of length 0-15 # boolean true/falseboolean ::= 'T' ::= 'F' # time in UTC encoded as 64-bit long milliseconds since epochdate ::= 'd' b7 b6 b5 b4 b3 b2 b1 b0 # 64-bit IEEE doubledouble ::= '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 integerint ::= '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/vectorlist ::= 'V' type? length? object* 'z' ::= 'v' int int object* # type-ref, length # 64-bit signed long integerlong ::= '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/objectmap ::= 'M' type? (object object)* 'z' # key, value map pairs ::= 'o' int object* # Object instance - type-ref # null valuenull ::= 'N' # main production for object serializationobject ::= null ::= binary ::= boolean ::= date ::= double ::= int ::= list ::= long ::= map ::= object-def object ::= remote ::= ref ::= string ::= xml # definition for an object (compact map)object-def ::= 'O' type int string* # Object reference (e.g. circular trees and graphs)ref ::= 'R' b3 b2 b1 b0 # reference to nth map/list in stream ::= x4a b0 # reference to 1-255th map/list ::= x4b b1 b0 # reference to 1-65535th map/list # UTF-8 encoded character string split into 64k chunksstring ::= 's' b1 b0 <string-data> string # non-final chunk ::= 'S' b1 b0 <string-data> # string of length 0-65535 ::= [x00-x1f] <string-data> # string of length 0-31 # map/list types for OO languagestype ::= 't' b1 b0 <type-string> # type name ::= x75 int # type reference # UTF-8 encoded XML dataxml ::= 'x' b1 b0 <xml-data> xml ::= 'X' b1 b0 <xml-data></def><def title="Envelope/Messaging/RPC Grammar">top ::= call ::= envelope ::= message ::= reply # RPC-style callcall ::= 'c' x02 x00 method object* 'z' # Envelope for encryption/headersenvelope ::= 'E' x02 x00 env-chunk* 'z' # header, body, footerenv-chunk ::= int (string object)* binary int (string object)*fault ::= 'f' (object object)* 'z' # message/streaming messagemessage ::= 'p' x02 x00 object* 'z' ::= 'P' x02 x00 object* 'z' # RPC method name (possibly mangled for overloading)method ::= 'm' b1 b0 <method-string> # RPC replyreply ::= 'r' x02 x00 object 'z' # successful message/reply ::= 'r' x02 x00 fault 'z' # exception/fault reply</def></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><p>Hessian 2.0 has 3 reference maps:</p><ol><li>An object/list reference map.</li><li>A type (class) reference map.</li><li>An object definition reference map.</li></ol><s2 title="binary data" type="defun"><def title="binary grammar">binary ::= b b1 b0 <binary-data> binary ::= B b1 b0 <binary-data> ::= [x20-x2f] <binary-data></def><p>Binary data is encoded in chunks. <var>'B'</var> represents the final chunkand <var>'b'</var> represents any non-final chunk. Each chunk has a 16-bitlength value.</p><s3 title="Compact: short binary"><p>Binary data with length less than 15 may be encoded with a singlelength byte [x20-x2f].</p></s3><s3 title="binary data examples"><def title="binary data examples">x20 # zero-length binary datax23 x01 x02 x03 # 3 byte dataB x10 x00 .... # 4k final chunk of datab x04 x00 .... # 1k non-final chunk of data</def></s3></s2><s2 title="boolean" type="defun"><def title="boolean grammar">boolean ::= T ::= F</def><p>The byte <var>'F'</var> represents false and the byte <var>'T'</var>represents true.</p><example title="boolean examples">T # trueF # false</example></s2><s2 title="date" type="defun"><def>date ::= d b7 b6 b5 b4 b3 b2 b1 b0</def><p>Date represented by a 64-bit long of milliseconds since the epoch, GMT.</p><example title="2:51:31 May 8, 1998 GMT">d x00 x00 x00 xd0 x4b x92 x84 xb8</example></s2><s2 title="double" type="defun"><def title="double grammar">double ::= D b7 b6 b5 b4 b3 b2 b1 b0 ::= x67 ::= x68 ::= x69 b0 ::= x6a b1 b0 ::= x6b b3 b2 b1 b0</def><p>A 64-bit IEEE floating pointer number.</p><s3 title="Compact: double zero"><p>The double 0.0 can be represented by the byte <code>x67</code></p></s3><s3 title="Compact: double one"><p>The double 1.0 can be represented by the byte <code>x68</code></p></s3><s3 title="Compact: double byte"><p>Doubles between -128.0 and 127.0 with no fractional componentcan be represented in two bytes by casting the byte value to a double.</p></s3><s3 title="Compact: double short"><p>Doubles between -32768.0 and 32767.0 with no fractional componentcan be represented in three bytes by casting the short value to a double.</p></s3><s3 title="Compact: double float"><p>Doubles which are equivalent to their 32-bit float representationcan be represented as the 4-byte float and then cast to double.</p></s3><s3 title="double examples"><example title="double examples">x67 # 0.0x68 # 1.0x69 x00 # 0.0x69 x80 # -128.0x69 xff # 127.0x70 x00 x00 # 0.0x70 x80 x00 # -32768.0x70 xff xff # 32767.0D x40 x28 x80 x00 x00 x00 x00 x00 # 12.25</example></s3></s2><s2 title="int" type="defun"><def title="integer grammar">int ::= 'I' b3 b2 b1 b0 ::= [x80-xbf] ::= [xc0-xcf] b0 ::= [xd0-xd7] b1 b0</def><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><s3 title="Compact: single octet integers"><p>Integers between -16 and 47 can be encoded by a single byte in therange <code>x80</code> to <code>xbf</code>.The value of the integer is <code>code - x90</code>.</p></s3><s3 title="Compact: two octet integers (byte)"><p>Integers between -2048 and 2047 can be encoded in two bytes withthe leading byte in the range <code>xc0</code> to <code>xcf</code>.The value of the integer is <code>256 * (code - xc8) + b0</code>.</p></s3><s3 title="Compact: three octet integers (short)"><p>Integers between -262144 and 262143 can be encoded in three bytes withthe leading byte in the range <code>xd0</code> to <code>xd7</code>.The value of the integer is <code>65536 * (code - xd4) + 256 * b1 + b0</code>.</p></s3><s3 title="int examples"><example title="integer examples">x90 # 0x80 # -16xbf # 47xc8 x00 # 0xc0 x00 # -2048xc7 x00 # -256xcf xff # 2047xd4 x00 x00 # 0xd0 x00 x00 # -262144xd7 xff xff # 262143I x00 x00 x00 x00 # 0I x00 x00 x01 x2c # 300</example></s3></s2><s2 title="list" type="defun"><def title="list grammar">list ::= V type? length? object* z ::= v int int object*</def><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><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><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><s3 title="Compact: repeated list"><p>Hessian 2.0 allows a compact form of the list for successive lists ofthe same type where the length is known beforehand.The type and length are encoded by integers, where the type is a reference toan earlier specified type.</p></s3><s3 title="list examples"><results title="serialization of a Java int[] = {0, 1}">V t x00 x04 [int # encoding of int[] type x6e x02 # length = 2 x90 # integer 0 x91 # integer 1⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -