Design Goals

Serialization

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 ::= N

boolean

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

boolean ::= T
        ::= F

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

I x00 x00 x01 x2c

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

L x00 x00 x00 x00 x00 x00 x01 x2c

double

A 64-bit IEEE floating pointer number.

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

D x40 x28 x80 x00 x00 x00 x00 x00

date

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

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

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 ::= (s b16 b8 utf-8-data)* S b16 b8 utf-8-data

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

X x00 x10 <top>hello</top>

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.

V t x00 x04 [int
  l x00 x00 x00 x02
  I x00 x00 x00 x00
  I x00 x00 x00 x01
  z

V I x00 x00 x00 x00
  S x00 x06 foobar
  z

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.

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

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

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

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

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

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

Call

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)

As an example, the following format is used for EJB:

http://hostname/hessian/ejb-name?id=object-id

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.

http://localhost/hessian/my-entity-bean

http://localhost/hessian/my-entity-bean?ejbid=slytherin

http://localhost/hessian/my-session-bean

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.

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

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.

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

Headers are (string, object) pairs that preceed the arguments.

The value of the header can be any serialized object.

For example, a request might include a transaction context in a header.

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.

Reply

Value

A successful reply returns a single value and possibly some header information.

r x01 x00
  I x00 x00 x00 x05
  z

Faults

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

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

Metadata (non-normative)

Obsolete meta data properties

Micro Hessian

Formal Definitions

Copyright and Licensing

Changes

changes in 1.0.2

• Clarified that length of XML and strings is in characters (Petr Gladkikh)

changes in 1.0

• Removed unidirectional messages.

changes in V3

• Added unidirectional messages
• Removed 'v' from reply
• changed length code to 'l'
• made type and length optional

changes in V2

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