Hessian 2.0 Draft Specification

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.

Index

binary	A binary value
boolean	The byte 'F' represents false and the byte 'T' represents true
date	Date represented by a 64-bits long of milliseconds since the epoch, GMT
double	A 64-bit IEEE floating pointer number
int	A 32-bit signed integer
list	An ordered list, like an array
long	A 64-bit signed integer
map	Represents serialized objects and Maps
null	Null represents a null pointer
ref	An integer referring to a previous list or map instance
remote	A reference to a remote object
string	A 16-bit unicode character string encoded in UTF-8
xml	An XML document encoded as a 16-bit unicode character string encoded in UTF-8

Hessian 2 is a compaction of the Hessian protocol. All Hessian 1 codes are understood by Hessian 2. The extended codes provide compact formats for common values, e.g. storing an integer zero as a single byte instead of Hessian 1's 5 bytes.

Unlike older binary protocols, Hessian is both self-describing and portable across languages. The wire protocol for web services should be invisible to application writers. Wire protocols should not require external schema or IDL.

null

Null represents a null pointer.

The byte 'N' represents the null pointer.

null values are allowed in place of any string, xml, binary, list, map, or remote.

null

null ::= N

boolean

The byte 'F' represents false and the byte 'T' represents true.

boolean ::= T ::= F

boolean true

T

int

A 32-bit signed integer. An integer is represented by the byte 'I' followed by the 4-bytes of the integer in big-endian order

int ::= I b32 b24 b16 b8

integer 300

I x00 x00 x01 x2c

Compact: single octet integers

Integers between -16 and 31 are represented by a single byte in the range x80 to xaf. The value of the integer is b0 - x90.

int ::= [x80-xaf]

The integer zero is represented by x90, -1 is represented by x8f and 17 is represented by xa1

Compact: two octet integers (byte)

Integers between -2048 and 2047 are encoded in two bytes with the leading byte in the range xd0 to xdf. The value of the integer is 256 * (b0 - xd8) + b1.

int ::= [xc0-xcf] b1

The integer zero is represented by xd8 x00, -256 is represented by xd7 x00 and 513 is represented by xda x01

Compact: three octet integers (short)

Integers between -262144 and 262143 are encoded in three bytes with the leading byte in the range x58 to x5f. The value of the integer is 65536 * (b0 - x5c) + 256 * b1 + b0.

int ::= [xd0-xd7] b1 b2

The integer zero is represented by xd4 x00 x00, -65536 is represented by xd3 x00 x00 and 65537 is represented by xd5 x00 x01

long

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

long ::= L b64 b56 b48 b40 b32 b24 b16 b8

long 300

L x00 x00 x00 x00 x00 x00 x01 x2c

Compact: single octet longs

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

long ::= [xd8-xef]

The long zero is represented by xe0, -1 is represented by xdf and 15 is represented by xef

Compact: two octet longs (byte)

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

long ::= [xf0-xff] b1

The long zero is represented by xf8 x00, -256 is represented by xf7 x00 and 513 is represented by xfa x01

Compact: three octet longs (short)

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

long ::= [x38-x3f] b1 b2

The long zero is represented by x3c x00 x00, -65536 is represented by x3b x00 x00 and 65537 is represented by x3d x00 x01

double

A 64-bit IEEE floating pointer number.

double ::= D b64 b56 b48 b40 b32 b24 b16 b8

double 12.25

D x40 x28 x80 x00 x00 x00 x00 x00

date

Date represented by a 64-bits long of milliseconds since the epoch, GMT.

date ::= d b64 b56 b48 b40 b32 b24 b16 b8

2:51:31 May 8, 1998 GMT

d x00 x00 x00 xd0 x4b x92 x84 xb8

string

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

The length is the number of characters, which may be different than the number of bytes.

String chunks may not split surrogate pairs.

string ::= (s b16 b8 utf-8-data)* S b16 b8 utf-8-data

"Hello" string

S x00 x05 hello

Compact: short strings

Strings with length less than 15 may be encoded with a single length byte [x00-x0f].

string ::= [x00-x0f] string-data

"Hello" string

x05 hello

xml

An XML document encoded as a 16-bit unicode character string encoded in UTF-8. XML data is encoded in chunks. 'X' represents the final chunk and 'x' represents any initial chunk.

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

xml ::= (x b16 b8 utf-8-data)* X b16 b8 utf-8-data

trivial XML document

X x00 x10 <top>hello</top>

Note: Because this document does not define the language mapping, implementations are free to return a string when reading an xml entity.

binary

A binary value.

Binary data is encoded in chunks. 'B' represents the final chunk and 'b' represents any initial chunk. Each chunk has a 16-bit length value.

binary ::= (b b16 b8 binary-data)* B b16 b8 binary-data

list

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 understood by 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.

list ::= V type? length? object* z

Each list item is added to the reference list to handle shared and circular elements. See the ref element.

Any parser expecting a list must also accept a null or a shared ref.

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

anonymous variable-length list = {0, "foobar"}

V I x00 x00 x00 x00 S x00 x06 foobar z

Note: The valid values of type are not specified in this document and may depend on the specific application. For example, a Java EJB server which exposes an Hessian interface can use the type information to instantiate the specific array type. On the other hand, a Perl server would likely ignore the contents of type entirely and create a generic array.

Compact: repeated list

Hessian 2.0 allows a compact form of the list for successive lists of the same type where the length is known beforehand. The type and length are encoded by integers, where the type is a reference to an earlier specified type.

list ::= 'v' int (type) int (length) object*

int[] {0, 1}

V t x00 x04 [int u x02 x90 x91 z v x01 x02 x90 x91

map

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

map ::= M t b16 b8 type-string (object, object)* z

The type 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.

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

Serialization of a Java Object

public class Car implements Serializable { String model = "Beetle"; String color = "aquamarine"; int mileage = 65536; }

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

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 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

Note: The type is chosen by the service. Often it may be the Java classname describing the service.

Compact: object definition and instantiation

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

The object definition includes a manadatory type string, the number of fields, the field names, and the values for the first object. The first integer is the length of the type string.

Object definition
map ::= 'O' int type-string int string* object*

The object instantiation creates a new object based on a previous definition.

The integer is a reference to the object definition.

Object instantiation
map ::= 'o' int object*

Object serialization

class Car { String color; String model; } out.writeObject(new Car("red", "corvette")); out.writeObject(new Car("green", "civic"));

O x9b example.Car -- type of the object length is int(12) x92 -- number of fields encoded as an int(2) x05 color -- field names x05 model x03 red -- data for object x08 corvette o x91 -- second object x91 = int(1) x05 green x05 civic

ref

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

ref ::= R b32 b24 b16 b8

ref 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.

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

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

circular list

list = new LinkedList(); list.head = 1; list.tail = list;

M t x00 x0a LinkedList S x00 x04 head I x00 x00 x00 x01 S x00 x04 tail R x00 x00 x00 x00 z

Note: ref only refers to list and map elements. string and binary, in particular, will only share references if they're wrapped in a list or map.

remote

A reference to a remote object. The remote has a type and a utf-8 string representing the object's URL.

remote ::= r t b16 b8 type-name S b16 b8 url

EJB Session Reference

r t x00 x0c test.TestObj S x00 x24 http://slytherin/ejbhome?id=69Xm8-zW

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.

obj.add2(2,3) call
c x01 x00 m x00 x04 add2 I x00 x00 x00 x02 I x00 x00 x00 x03 z

Object Naming (non-normative)

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.

Object naming (non-normative)

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 Bean Identifier
http://localhost/hessian/my-entity-bean?ejbid=slytherin

Example Session Bean Identifier
http://localhost/hessian/my-session-bean?ejbid=M9Zs1Zm

Methods and Overloading

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.

Servers should accept calls with either the mangled method name or the unmangled method name. Clients should send the mangled method name.

Arguments

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.

remote.eq(bean, bean)
bean = new qa.Bean("foo", 13); System.out.println(remote.eq(bean, bean));

c x01 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

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.

Headers

Call with Distributed Transaction Context
c x01 x00 H x00 x0b transaction r t x00 x28 com.caucho.hessian.xa.TransactionManager S x00 x23 http://hostname/xa?ejbid=01b8e19a77 m x00 x05 debug I x00 x03 x01 xcb z

Versioning

The call and response tags include a major and minor byte. The current version is 1.0.

valid-reply ::= r x01 x00 header* object z
fault-reply ::= r x01 x00 header* fault z

Value

Faults

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. In Java, detail will be a serialized exception.

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

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

_hessian_getAttribute(String key) returns a string. The following attributes are predefined by this spec:

attribute	meaning
java.api.class	Java interface for this URL
java.home.class	Java interface for this service
java.object.class	Java interface for a service object
java.ejb.primary.key.class	Java EJB primary key class

"java.api.class" returns the client proxy's Java API class for the current URL. "java.home.class" returns the API class for the factory URL, i.e. without any "?id=XXX" query string. "java.object.class" returns the API class for object instances.

In the case of services with no object instances, i.e. non-factory services, all three attributes will return the same class name.

Obsolete meta data properties

attribute	meaning
home-class	Java class for the home interface.
remote-class	Java class for the object interface.
primary-key-class	Java class for the primary key.

top     ::= call
        ::= reply

call    ::= 'c' x02 x00 header* method object* 'z'

reply   ::= 'r' x02 x00 header* object 'z'
        ::= 'r' x01 x00 header* fault 'z'

object  ::= null
        ::= boolean
        ::= int
        ::= long
        ::= double
        ::= date
        ::= string
        ::= xml
        ::= binary
        ::= remote
        ::= ref
        ::= list
        ::= map

header  ::= H b16 b8 header-string object
method  ::= m b16 b8 method-string

fault   ::= f (object object)* z

list    ::= 'V' type? length? object* z
        ::= 'v' int int object*

map     ::= 'M' type? (object object)* 'z'
        ::= 'O' int type-string int string* object*
        ::= 'o' int object*

remote  ::= 'r' type? string

type    ::= t b16 b8 type-string

length  ::= 'l' b32 b24 b16 b8
        ::= 'u' int

null    ::= 'N'

boolean ::= 'T'
        ::= 'F'

int     ::= 'I' b32 b24 b16 b8
        ::= [x80-xaf]
        ::= [xc0-xcf] b8
        ::= [xd0-xd7] b16 b8

long    ::= 'L' b64 b56 b48 b40 b32 b24 b16 b8
        ::= [xd8-xef]
        ::= [xf0-xff] b8
        ::= [x38-x3f] b16 b8
        ::= 'a' b32 b24 b16 b8

double  ::= 'D' b64 b56 b48 b40 b32 b24 b16 b8

date    ::= 'd' b64 b56 b48 b40 b32 b24 b16 b8

string  ::= ('s' b16 b8 string-data)* 'S' b16 b8 string-data
        ::= [x00-x0f] string-data

xml     ::= ('x' b16 b8 xml-data)* 'X' b16 b8 xml-data

binary  ::= ('b' b16 b8 binary-data)* 'B' b16 b8 binary-data

ref     ::= 'R' b32 b24 b16 b8

Copyright and Licensing

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.

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.

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.