Revision as of 10:40, 9 July 2008

The Hessian binary web service protocol makes web services usable without requiring a large framework, and without learning yet another alphabet soup of protocols. Because it is a binary protocol, it is well-suited to sending binary data without any need to extend the protocol with attachments.

Hessian Downloads

See http://www.caucho.com/hessian for the current downloadable Java versions.

The Hessian name

Hessian was named after Hessian cloth, which is the British term for Burlap, and the binary Hessian protocol derives from Caucho's XML Burlap protocol.

The name burlap was originally chosen since burlap is a practical, simple, and useful, but extremely ordinary material, reflecting the design goals for the two protocols. Other RPC and web service protocols may strive for excitement and world domination; Hessian just gets things done.

Hessian Java API Overview

Main article: Hessian Java API Overview

Sample Java Client

   String url = "http://www.caucho.com/hessian/test/basic";

   HessianProxyFactory factory = new HessianProxyFactory();
   Basic basic = (Basic) factory.create(Basic.class, url);

   System.out.println("hello(): " + basic.hello());

Specifications

Hessian 1.0.1 spec

Hessian 1.0 Grammar - quick, terse summary of the protocol

Hessian 2.0 Grammar - draft proposal for Hessian 2.0

Language Implementations

.NET C#

Microsoft .NET compatible version of HessianC# is available under the LGPL by Dimitri Minich, Vitaliy Byelyenkiy and Andre Voltmann

See http://www.hessiancsharp.org/

Objective-C

Byron Wright has released of Hessian for Objective-C at http://www.bluebearstudio.com/hessianobjc/

Objective-C

Main article: Hessian: Objective-C

Byron Wright has released of Hessian for Objective-C at http://www.bluebearstudio.com/hessianobjc/

Objective-C 2.0

Fredrik Olsson of Jayway AB has released a Hessian implementation for Objective-C 2.0. For use with iPhone OS 2.0 and Mac OS X 10.5 and later.

Introduction to HessianKit

HessianKit is a Framework for Objective-C 2.0 to allow Mac OS X 10.5, and iPhone 2.0 applications to seamlessly communicate with hessian web services.

The three main goals of HessianKit are:

• To be as compliant and forgiving as possible.
• Provide seamless Objective-C experience against web services implemented in Java.
• Avoid glue-code.

The example code is written to be compatible with, and mirror the example code from Hessian Java API Overview.

HessianKit is available under Apache License 2 at http://sourceforge.net/projects/hessiankit

The Service API

Assume the following Hessian service's API is provided as a plain old Java interface.

Hello, World API - Java

 public interface BasicAPI {
     public String hello();
 }

Client Implementation

The client must declare the same interface in Objective-C.

Hello, World API - Objective-C

 @protocol BasicAPI
 -(NSString*)hello;
 @end

Then creating a client is as simple as creating an API interface:

Hello, World Client - Objective-C

 NSURL* url = [NSURL URLWithString@"http://www.caucho.com/hessian/test/basic"];
 id<BasicAPI> proxy = (id<BasicApi>)[CWHessianConnection proxyWithURL:url protocol:@protocol(basicAPI)];
 NSLog(@"hello: %@", [proxy hello]);

Method naming

Since Java and Objective-C differ in the naming of methods, some translation must be done when sending call tho the hessian web service. Method names are first looked up using the class method CWHessianArchiver methodNameForSelector:], if a method name is not returned, the method name to use will be generated with these steps:

1. Split the selector name on ':' delimiter character.
2. Capitalize first charter of all splitted parts but the first.
3. Join splitted parts without delimiter.
4. If method takes one or more arguments the nme is mangled by appending "__#" where # is the number of arguments.

Example of method translations

 doFoo      ==>  doFoo
 getFoo:    ==>  getFoo__1
 doFoo:bar: ==>  doFooBar__2
 doFugly::: ==>  doFugly__3

Supported Types

Use the following types when declaing an Objective-C protocol to mirror the web service's Java interface.

Argument and Return types

 BOOL         - Maps to Java boolean, transfered as Hessian boolean. 
 int32_t      - Maps to Java int, transfered as Hessian int. 
 int64_t      - Maps to Java long, transfered as Hessian long.
 float        - Maps to Java float, transfered as Hessian float. 
 double       - Maps to Java double, transfered as Hessian double.
 id<NSCoding> - Maps to Java java.lang.Object or java.util.Map, transfered as typed Hessian map.

The use of int32_t and int64_t is encourage, but not required, for clarity over int and long long. The size of int32_t and int64_t are guaranteed over both 32 and 64 bit applications in Mac OS X as well as iPhone.

Cocoa classes with special treatment

 NSArray      - Maps to Java array or java.util.List, tansfered as Hessian list. 
 NSDictionary - Maps to Java java.util.Map, or domain class, trabsfered as Hessian map. 
 NSData       - Maps to Java byte array, transfered as Hessian binary data. 
 NSDate       - Maps to Java long or java.util.Date, transfered as Hessian date. 
 NSString     - Maps to Java java.lang.String, transfered as Hessian string.
 NSXMLNode    - Maps to Java org.w3c.dom.Node, transfered as Hessian xml.

Typed maps in responses will be decoded as objects of the specified type if the type can be found. The class name is searched as follows:

1. If a class mapping from [CWHessianUnacrhiver classForClassName:] exist create and initialize mapped class.
2. Else if no mapping found found strip package from class name.
3. If stripped name is an existing class create and initialize an object of this class.
4. Else if protocol mapping from [CWHessianUnacrhiver protocolForClassName:] exists create and initialize a dynamic subclass of CWValueObject conforming to the protocol.
5. Else if no mapping found and stripped name is an existing protocol create and initialize a dynamic subclass of CWValueObject conforming to the protocol.
6. As last resort return as a NSDictionary object

See http://sourceforge.net/projects/hessiankit

PHP

A PHP implementation of Hessian is available under the GPL at http://hessianphp.sourceforge.net by Manolo Gómez.

Also see http://www.hessianphp.org/wiki/index.php

Ruby

Main article: Hessian - Ruby Implementation

Christer Sandberg has implemented a Ruby Hessian client at http://rubyforge.org/projects/hessian:

"I just wanted to inform you all that I have made another Ruby Hessian client. It has support for chunks for both strings, xml and binary data and it provides proper encoding and decoding for UTF-8."

Pankaj Mishra has implemented a Ruby Hessian client at http://sourceforge.net/projects/hessianruby under the LGPL.

Links

http://hessian.caucho.com

Dinamica

Technical article about integrating Hessian with our open source J2EE framework "Dinamica"

dinamica-hessian.pdf

The article explains how to return disconnected recordsets (a Dinamica feature) using a Hessian service. In the example, a customer record, all its orders and the detail records for every order are returned using a single recordset and a very simple hessian service.

Former MTS/COM+/VB6 programmers will recognize this technique.

Spring Framework

The Spring Framework includes support for Hessian. The Spring Manual provides an overview.

RIFE

RIFE aims to offer a viable solution for rapid web application development in Java without being troubled by the complex implications of J2EE. RIFE offers an alternative approach to web application development and design. It builds upon the Java platform, but offers all required tools and APIs to implement and perform all common website related tasks in a fast, intuitive and consistent manner.

RIFE has a page describing its [http://rifers.org/wiki/display/RIFE/Support+for+Hessian+web+services support for Hessian web services].