hessian-serialization

http://hessian.caucho.com/doc/hessian-serialization.html

Table of Contents

1.  Introduction
2.  Design Goals
3.  Hessian Grammar
4.  Serialization
    4.1.  binary data
        4.1.1.  Compact: short binary
        4.1.2.  Binary Examples
    4.2.  boolean
        4.2.1.  Boolean Examples
    4.3.  date
        4.3.1.  Compact: date in minutes
        4.3.2.  Date Examples
    4.4.  double
        4.4.1.  Compact: double zero
        4.4.2.  Compact: double one
        4.4.3.  Compact: double octet
        4.4.4.  Compact: double short
        4.4.5.  Compact: double float
        4.4.6.  Double Examples
    4.5.  int
        4.5.1.  Compact: single octet integers
        4.5.2.  Compact: two octet integers
        4.5.3.  Compact: three octet integers
        4.5.4.  Integer Examples
    4.6.  list
        4.6.1.  Compact: fixed length list
        4.6.2.  List examples
    4.7.  long
        4.7.1.  Compact: single octet longs
        4.7.2.  Compact: two octet longs
        4.7.3.  Compact: three octet longs
        4.7.4.  Compact: four octet longs
        4.7.5.  Long Examples
    4.8.  map
        4.8.1.  Map examples
    4.9.  null
    4.10.  object
        4.10.1.  Compact: class definition
        4.10.2.  Compact: object instantiation
        4.10.3.  Object examples
    4.11.  ref
        4.11.1.  Ref Examples
    4.12.  string
        4.12.1.  Compact: short strings
        4.12.2.  String Examples
    4.13.  type
    4.14.  Compact: type references
5.  Reference Maps
    5.1.  value reference
    5.2.  class reference
    5.3.  type reference
6.  Bytecode map
§  Authors' Addresses
§  Intellectual Property and Copyright Statements

---

 TOC 

1.  Introduction

Hessian is a dynamically-typed, binary serialization and Web Services protocol designed for object-oriented transmission.

---

 TOC 

2.  Design Goals

Hessian is dynamically-typed, compact, and portable across languages.

The Hessian protocol has the following design goals:

• It must self-describe the serialized types, i.e. not require external schema or interface definitions.
• It must be language-independent, including supporting scripting languages.
• It must be readable or writable in a single pass.
• It must be as compact as possible.
• It must be simple so it can be effectively tested and implemented.
• It must be as fast as possible.
• It must support Unicode strings.
• It must support 8-bit binary data without escaping or using attachments.
• It must support encryption, compression, signature, and transaction context envelopes.

---

 TOC 

3.  Hessian Grammar

---

Serialization Grammar

           # starting production
top        ::= value

           # 8-bit binary data split into 64k chunks
binary     ::= x41 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
           ::= [x34-x37] <binary-data>        # binary data of
                                                 #  length 0-1023

           # boolean true/false
boolean    ::= 'T'
           ::= 'F'

           # definition for an object (compact map)
class-def  ::= 'C' string int string*

           # time in UTC encoded as 64-bit long milliseconds since
           #  epoch
date       ::= x4a b7 b6 b5 b4 b3 b2 b1 b0
           ::= x4b b3 b2 b1 b0       # minutes since epoch

           # 64-bit IEEE double
double     ::= 'D' b7 b6 b5 b4 b3 b2 b1 b0
           ::= x5b                   # 0.0
           ::= x5c                   # 1.0
           ::= x5d b0                # byte cast to double
                                     #  (-128.0 to 127.0)
           ::= x5e b1 b0             # short cast to double
           ::= x5f b3 b2 b1 b0       # 32-bit float cast to double

           # 32-bit signed integer
int        ::= '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
list       ::= x55 type value* 'Z'   # variable-length list
	   ::= 'V' type int value*   # fixed-length list
           ::= x57 value* 'Z'        # variable-length untyped list
           ::= x58 int value*        # fixed-length untyped list
	   ::= [x70-77] type value*  # fixed-length typed list
	   ::= [x78-7f] value*       # fixed-length untyped list

           # 64-bit signed long integer
long       ::= '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
           ::= x59 b3 b2 b1 b0       # 32-bit integer cast to long

           # map/object
map        ::= 'M' type (value value)* 'Z'  # key, value map pairs
	   ::= 'H' (value value)* 'Z'       # untyped key, value

           # null value
null       ::= 'N'

           # Object instance
object     ::= 'O' int value*
	   ::= [x60-x6f] value*

           # value reference (e.g. circular trees and graphs)
ref        ::= x51 int            # reference to nth map/list/object

           # UTF-8 encoded character string split into 64k chunks
string     ::= x52 b1 b0 <utf8-data> string  # non-final chunk
           ::= 'S' b1 b0 <utf8-data>         # string of length
                                             #  0-65535
           ::= [x00-x1f] <utf8-data>         # string of length
                                             #  0-31
           ::= [x30-x34] <utf8-data>         # string of length
                                             #  0-1023

           # map/list types for OO languages
type       ::= string                        # type name
           ::= int                           # type reference

           # main production
value      ::= null
           ::= binary
           ::= boolean
           ::= class-def value
           ::= date
           ::= double
           ::= int
           ::= list
           ::= long
           ::= map
           ::= object
           ::= ref
           ::= string

 Figure 1 

---

---

 TOC 

4.  Serialization

Hessian's object serialization has 8 primitive types:

1. raw binary data
2. boolean
3. 64-bit millisecond date
4. 64-bit double
5. 32-bit int
6. 64-bit long
7. null
8. UTF8-encoded string

It has 3 recursive types:

1. list for lists and arrays
2. map for maps and dictionaries
3. object for objects

Finally, it has one special contruct:

1. ref for shared and circular object references.

Hessian 2.0 has 3 internal reference maps:

1. An object/list reference map.
2. An class definition reference map.
3. A type (class name) reference map.