Hessian - Objective-C 2.0 Implementation

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