By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”
The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
This Internet-Draft will expire on February 2, 2008.
2. Design Goals
3. Hessian Grammar
4. Messages and Envelopes
4.1.1. Methods and Overloading
4.1.3. Call examples
4.2.1. Envelope examples
5. Service Location (URLs)
5.1. Object Naming (non-normative)
5.2. Object naming (non-normative) Example
6. Bytecode map
§ Authors' Addresses
§ Intellectual Property and Copyright Statements
This document describes the portions of the Hessian 2.0 protocol concerning web services. The document is intended to be read by implementors of Hessian 2.0. Hessian 2.0 supports two types of network communication: remote procedure call (RPC) and message-based. These may also be viewed as synchronous and asynchronous communication.
RPC communication is based on "methods" invoked on a server. The method being invoked is specified in a Hessian 2.0 "call". Arguments to these methods are passed in the call and are serialized using the Hessian 2.0 serialization protocol. If the method was successfully invoked, the return value of the method is also serialized using Hessian 2.0 and sent to the client. If the method was not successfully invoked, a "fault" is returned to the client. RPC communication can use any underlying network protocol for transport such as HTTP or TCP.
Message-based communication is asynchronous and does not necessarily involve the use of methods, clients, or servers. Messages may or may not receive a response message. Messages simply contain other Hessian 2.0 objects. These may be simple types, aggregates like a list or map, or an "envelope". Envelopes may have headers that specify routing or other special processing information. They may also contain encrypted, signed, and/or compressed data. Thus using messages with envelopes can be useful in cases where end-to-end security is necessary. Message-based communication can also use any underlying network protocol such as HTTP or TCP and may be especially appropriate in queued message systems.
Unlike older binary protocols, Hessian is both self-describing, compact, and portable across languages. The wire protocol for web services should be invisible to application writers, it should not require external schema or IDL.
The Hessian protocol has the following design goals:
top ::= version content ::= call-1.0 ::= reply-1.0 # RPC-style call call ::= 'C' string int value* call-1.0 ::= 'c' x01 x00 <hessian-1.0-call> content ::= call # rpc call ::= fault # rpc fault reply ::= reply # rpc value reply ::= packet+ # streaming packet data ::= envelope+ # envelope wrapping content envelope ::= 'E' string env-chunk* 'Z' env-chunk ::= int (string value)* packet int (string value)* # RPC fault fault ::= 'F' (value value)* 'Z' # message/streaming message packet ::= (x4f b1 b0 <data>)* packet ::= 'P' b1 b0 <data> ::= [x70 - x7f] <data> ::= [x80 - xff] <data> # RPC reply reply ::= 'R' value reply-1.0 ::= 'r' x01 x00 <hessian-1.0-reply> version ::= 'H' x02 x00
| Figure 1 |
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.
call ::= C string int value*
| Figure 2 |
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.
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.
Method names beginning with _hessian_ are reserved.
Servers should accept calls with either the mangled method name or the unmangled method name. Clients should send the mangled method name.
add(int a, int b) -> add_int_int add(double a, double b) -> add_double_double add(shopping.Cart cart, shopping.Item item) -> add_shopping.Cart_shopping.Item
| Figure 3 |
Arguments immediately follow the method in positional order. Argument values use Hessian's serialization.
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.
bean = new qa.Bean("foo", 13); System.out.println(remote.eq(bean, bean)); --- H x02 x00 C x02 eq # method name = "eq" x92 # two arguments M x07 qa.Bean # first argument x03 foo x9d Z Q x00 # second argument (ref to first)
| Figure 4 |
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.
H x02 x00 # Hessian 2.0 C # RPC call x04 add2 # method "add2" x92 # two arguments x92 # 2 - argument 1 x93 # 3 - argument 2
| Figure 5 |
H x02 x00 # Hessian 2.0 R # reply x95 # int 5
| Figure 6 |
envelope ::= E string env-chunk* Z env-chunk ::= int (string value)* packet int (string value)*
| Figure 7 |
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".
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.
H x02 x00 # Hessian 2.0 E # envelope x06 Header # "Header" adds headers, body is identity x90 # no headers x87 # final packet (7 bytes) R # RPC reply x05 hello # "hello" x90 # no footers Z # end of envelope
| Figure 8 |
Chunked Identity Envelope
H x02 x00 # Hessian 2.0 E x06 Header # "Header" envelope does nothing to the body x90 # no headers x87 # final packet (7 bytes) C # RPC call x05 hello # hello() x91 # one arg x90 # no footers x90 # no headers x8d # final packet (13 bytes) x05 hello, world # hello, world x90 # no footers Z # end of envelope
| Figure 9 |
H x02 x00 E x09 Deflation # "Deflation" envelope compresses the body x90 # no headers P x10 x00 # single chunk (4096) x78 x9c x4b... # compressed message x90 # no footers Z # end of envelope
| Figure 10 |
packet ::= (x4f b1 b0 <data>) packet ::= 'P' b1 b0 <data> ::= [x70-x7f] b0 <data> ::= [x80-xff] <data>
| Figure 11 |
A Hessian message contains a sequence of Hessian serialized objects. Messages can be used for multihop data transfer or simply for storing serialized data.
reply ::= R value fault ::= F map
| Figure 12 |
A successful reply returns a single value and possibly some header information.
Integer 5 Envelope
H x02 x00 R x95
| Figure 13 |
Failed calls return a fault.
Each fault has a number of informative fields, expressed like <map> entries. The defined fields are code, message, and detail. code is one of a short list of strings defined below. message is a user-readable message. detail is an object representing the exception.
Remote Call throws FileNotFoundException
F H x04 code x10 ServiceException x07 message x0e File Not Found x06 detail M x1d java.io.FileNotFoundException Z Z
| Figure 14 |
- The Hessian request has some sort of syntactic error.
- The requested object does not exist.
- The requested method does not exist.
- A required header was not understood by the server.
- The called method threw an exception.
The call and response tags include a major and minor byte. The current version is 2.0.
Hessian services are identified by URLs. Typically, these will be HTTP URLs, although protocols would be possible as well.
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.
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.
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.
As an example, the following format is used for EJB:
| Figure 15 |
http://hostname/hessian 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.
/ejb-name, 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 ejb-name corresponds to the ejb-name in the deployment descriptor.
object-id 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.
# Example Entity Home Identifier http://localhost/hessian/my-entity-bean # Example Entity Bean Identifier http://localhost/hessian/my-entity-bean?ejbid=slytherin # Example Session Home Identifier http://localhost/hessian/my-session-bean # Example Session Bean Identifier http://localhost/hessian/my-session-bean?ejbid=M9Zs1Zm
| Figure 16 |
Hessian is organized as a bytecode protocol. A Hessian reader is essentially a switch statement on the initial octet.
x00 - x42 # reserved x43 # rpc call ('C') x44 # reserved x45 # envelope ('E') x46 # fault ('F') x47 # reserved x48 # hessian version ('H') x49 - x4f # reserved x4f # packet chunk ('O') x50 # packet end ('P') x51 # reserved x52 # rpc result ('R') x53 - x59 # reserved x5a # terminator ('Z') x5b - x5f # reserved x70 - x7f # final packet (0 - 4096) x80 - xff # final packet for envelope (0 - 127)
| Figure 17 |
|Caucho Technology Inc.|
|P.O. Box 9001|
|La Jolla, CA 92038|
|Caucho Technology Inc.|
|P.O. Box 9001|
|La Jolla, CA 92038|
Copyright © The IETF Trust (2007).
This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.
This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM 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.
The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at firstname.lastname@example.org.