hessian-2.0-spec.xtp

RESIN 3.2 最新源码

</s3>

<s3 title="Arguments">

<p>Arguments immediately follow the method in positional order.
Argument values use Hessian's serialization.</p>

<p>All arguments share references, i.e. the reference list
starts with the first argument and continues for all other arguments.
This lets two arguments share values.</p>

<example title="remote.eq(bean, bean)">
bean = new qa.Bean("foo", 13);

System.out.println(remote.eq(bean, bean));
</example>
<results>
c x02 x00
  m x00 x02 eq
  M t x00 x07 qa.Bean
    S x00 x03 foo
    I x00 x00 x00 x0d
    z
  R x00 x00 x00 x00
  z
</results>

<p>The number and type of arguments are fixed by the remote method.
Variable length arguments are forbidden.  Implementations
may take advantage of the expected type to improve performance.</p>

</s3>

<s3 title="Call examples">

<example title="obj.add2(2,3) call">
c x02 x00         # call for Hessian 2.0
  m x00 x04 add2  # method "add2"
  x92             # 2 - argument 1
  x93             # 3 - argument 2
  z               # end of argument marker
</example>

<example title="obj.add2(2,3) reply">
r x02 x00
  x95
  z
</example>

</s3>

</s2>

<s2 title="Envelope">

<def>
envelope ::= E x02 x00 m b1 b0 &lt;method-string> env-chunk* z

env-chunk ::= int (string object)* binary int (string object)*
</def>

<p>A Hessian envelope wraps a Hessian message, adding headers and footers
and possibly compressing or encrypting the wrapped message.  The envelope
type is identified by a method string, e.g.
"com.caucho.hessian.io.Deflation" or
"com.caucho.hessian.security.X509Encryption".
</p>

<p>Some envelopes may chunk the data, providing multiple header/footer
chunks.  For example, a signature envelope might chunk a large
streaming message to reduce the amount of buffering required to validate
the signatures.</p>

<s3 title="Envelope examples">

<example title="identity envelope">
E x02 x00
  m x00 x08 Identity   # "Identity" envelope does nothing to the body
  x90                  # no headers
  B x00 x0a            # binary wrapped body (12 bytes)
    p x02 x00          # wrapped message
    x05 hello          # "hello"
    z                  # end of wrapped message
  x90                  # no footers
  z                    # end of envelope
</example>

<example title="chunked identity envelope">
E x02 x00
  m x00 x08 Identity   # "Identity" envelope does nothing to the body
  x90                  # no headers
  B x00 x0c            # binary header for wrapped body (10 bytes)
    p x02 x00          # wrapped message
    x07 hello,         # "hello, "
    z                  # end of wrapped message
  x90                  # no footers

  x90                  # no headers
  B x00 x08            # binary wrapped body (10 bytes)
    p x02 x00          # wrapped message
    x05 world          # world
    z
  x90                  # no footers
  z                    # end of envelope
</example>

</s3>

<example title="compression envelope">
E x02 x00
  m x00 x09 Deflation  # "Deflation" envelope compresses the body
  x90                  # no headers
  B x00 x0a            # binary wrapped body (32 bytes)
    x78 x9c x4b...     # compressed message
  x90                  # no footers
  z                    # end of envelope
</example>

</s2>

<s2 title="Message">

<def>
message ::= p x02 x00 object* z
</def>

<p>A Hessian message contains a sequence
of Hessian serialized objects.  Messages can be used for multihop data
transfer or simply for storing serialized data.
</p>

</s2>

<s2 title="Reply">

<def>
valid-reply ::= r x02 x00 header* object z
fault-reply ::= r x02 x00 header* fault z
</def>

<s3 title="Value">
  
<p>A successful reply returns a single value and possibly
some header information.  </p>
  
<example title="integer 5 result">
r x01 x00
  I x00 x00 x00 x05
  z
</example>

</s3>
<s3 title="Faults">
<p>Failed calls return a <var>fault</var>.</p>

<p>Each fault has a number of informative fields, expressed like
&lt;map&gt; entries.  The defined fields are <var>code</var>, <var>message</var>,
and <var>detail</var>. <var>code</var> is one of a short list of strings
defined below.  <var>message</var> is a user-readable message.
<var>detail</var> is an object representing the exception.  In Java,
<var>detail</var> will be a serialized exception.</p>

<results title="Remote Call throws FileNotFoundException">
r x01 x00
  f
  S x00 x04 code
  S x00 x10 ServiceException

  S x00 x07 message
  S x00 x0e File Not Found

  S x00 x06 detail
  M t x00 x1d java.io.FileNotFoundException
    z
  z
</results>

<deftable>
<tr>
  <td>ProtocolException</td>
  <td>The Hessian request has some sort of syntactic error.</td>
</tr>
<tr>
  <td>NoSuchObjectException</td>
  <td>The requested object does not exist.</td>
</tr>
<tr>
  <td>NoSuchMethodException</td>
  <td>The requested method does not exist.</td>
</tr>
<tr>
  <td>RequireHeaderException</td>
  <td>A required header was not understood by the server.</td>
</tr>
<tr>
  <td>ServiceException</td>
  <td>The called method threw an exception.</td>
</tr>
</deftable>

</s3>

</s2>

<s2 title="Versioning">

<p>The call and response tags include a major and minor byte.  The
current version is 2.0.</p>

</s2>

</s1>

<s1 title="Service Location (URLs)">

<p>Hessian services are identified by URLs.  Typically, these will be
HTTP URLs, although protocols would be possible as well.</p>

<s2 title="Object Naming (non-normative)">

<p>
URLs are flexible
enough to encode object instances as well as simple
static service locations.  The URL uniquely identifies the
Hessian object.  Thus, Hessian can support
object-oriented services, e.g. naming services, entity beans, or
session beans, specified by the URL without requiring extra method parameters
or headers.</p>

<p>Object naming may use the query string convention that "?id=XXX"
names the object "XXX" in the given service.  This convention is recommented,
but not required.</p>

<p>For example, a stock quote service might have a
factory interface like http://foo.com/stock and object instances
like http://foo.com?id=PEET.  The factory interface would return valid
object references through the factory methods.</p>

</s2>

<s2 title="Object naming (non-normative)">

<p>As an example, the following format is used for EJB:</p>

<def>
http://hostname/hessian<var>/ejb-name</var>?id=<var>object-id</var>
</def>

<p><var>http://hostname/hessian</var> identifies the EJB container.
In Resin-EJB, this will refer to the EJB Servlet. 
"/hessian" is the servlet prefix (url-pattern.)  HTTP is just used as
an example; Hessian does not require the use of HTTP.
</p>

<p><var>/ejb-name</var>, the path info of the request, identifies the EJB name,
specifically the home interface.  EJB containers can contain several
entity and session beans, each with its own EJB home.  The <var>ejb-name</var>
corresponds to the ejb-name in the deployment descriptor.
</p>

<p><var>object-id</var> identifies the specific object.  For entity beans, the
object-id encodes the primary key.  For session beans, the object-id encodes
a unique session identifier.  Home interfaces have no ";ejbid=..." portion.
</p>

<example title="Example Entity Home Identifier">
http://localhost/hessian/my-entity-bean
</example>

<example title="Example Entity Bean Identifier">
http://localhost/hessian/my-entity-bean?ejbid=slytherin
</example>

<example title="Example Session Home Identifier">
http://localhost/hessian/my-session-bean
</example>

<example title="Example Session Bean Identifier">
http://localhost/hessian/my-session-bean?ejbid=M9Zs1Zm
</example>

</s2>

</s1>

<s1 title="Bytecode map">

<p>Hessian is organized as a bytecode protocol.  A Hessian
implementation is essentially a big switch statement on the initial
bytecode.</p>

<def title="Bytecode Encoding">
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          # reserved
x58          # utf-8 xml final chunk ('X')
x59 - 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          # utf-8 XML non-final chunk ('x')
x79          # reserved
x7a          # list/map terminator ('z')
x7b - x7f    # reserved
x80 - xbf    # one-byte compact int (-x10 to x3f, x90 is 0)
xc0 - xcf    # two-byte compact int (-x800 to x3ff)
xd0 - xd7    # three-byte compact int (-x40000 to x3ffff)
</def>

</s1>

<s1 title="Copyright and Licensing">

<p>
Copyright 2000-2007 Caucho Technology, Inc. All Rights Reserved.
</p>

<p>Any party may implement this protocol for any purpose without royalty
or license fee, provided that the implementation conforms to this
specification.   Caucho Technology reserves the right to create a
test suite, freely available without royalty or license fee, to
validate implementation conformance.  The limited permissions granted
herein are perpetual and may not be revoked by Caucho Technology or
its successors or assigns.</p>

<p>This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published and
distributed, in whole or in part, without restriction of any kind,
provided that the above copyright notice and these paragraphs are
included on all such copies and derivative works.</p>

<p>This document and the information contained herein is provided on an
"AS IS" basis and CAUCHO TECHNOLOGY DISCLAIMS ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.</p>

</s1>

<s1 title="Changes">

<s2 title="changes in 2.0 draft 2">

<ul>
<li>Added envelope ('E') syntax.</li>
<li>Added post/message ('p') syntax.</li>
<li>Changed encoding to avoid name conflicts.</li>
<li>Split object definition/instance.</li>
<li>Expanded int and string single-byte range.</li>
</ul>

</s2>

<s2 title="changes in 2.0 draft 1">

<ul>
<li>Added compact encoding.</li>
</ul>

</s2>

<s2 title="changes in 1.0.2">

<ul>
<li>Clarified that length of XML and strings is in characters (Petr Gladkikh)
</li></ul>
</s2>

<s2 title="changes in 1.0">

<ul>
<li>Removed unidirectional messages.
</li></ul>
</s2>

<s2 title="changes in V3">

<ul>
<li>Added unidirectional messages
</li><li>Removed 'v' from reply
</li><li>changed length code to 'l'
</li><li>made <var>type</var> and <var>length</var> optional
</li></ul>

</s2>

<s2 title="changes in V2">

<ul>
<li>EJB naming: clarified examples especially for session beans (John Mitchell)
</li><li>Formal definitions: clarified grammar and added missing object (John Mitchell)
</li><li>Formal definitions: initial binary should use 'b' (John Mitchell)
</li></ul>

</s2>

</s1>
</body></document>