Caucho maker of Resin Server | Application Server (Java EE Certified) and Web Server


 

Resin Documentation

home company docs 
app server 
 Resin Server | Application Server (Java EE Certified) and Web Server
 

hessian


Hessian is a simple binary protocol for connecting web services. The com.caucho.hessian.client and com.caucho.hessian.server packages do not require any other Resin classes, so can be used in smaller clients, like applets.

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.

The Hessian specification itself is a short and interesting description.

Hessian Client

Using a Hessian service from a Java client is like calling a method. The HessianProxyFactory creates proxies which act like normal Java objects, with possibility that the method might throw a protocol exception if the remote connection fails. Using HessianProxyFactory requires JDK 1.3.

Each service will have a normal Java interface describing the service. The trivial hello, world example just returns a string. Because the Hessian services support Java serialization, any Java type can be used.

API for Basic service
package example;

public interface Basic {
  public String hello();
}

The following is an example of a standalone Hessian client. The client creates a HessianProxyFactory. The client uses the factory to create client stubs with the given target URL and a Java interface for the API. The returned object is a stub implementing the API.

Hessian Client for Basic service
package example;

import com.caucho.hessian.client.HessianProxyFactory;

public class BasicClient {
  public static void main(String []args)
    throws Exception
  {
    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());
  }
}

That's it! There are no more complications to using the client. The service can add methods and use any Java type for parameters and results.

Hessian Service

While most Hessian services will use Resin-CMP or Resin-EJB, to take advantage of the benefits of EJB, the Hessian library makes it possible to write services by extending HessianServlet.

Any public method is treated as a service method. So adding new methods is as easy as writing a normal Java class.

Because the service is implemented as a Servlet, it can use all the familiar servlet data in the ServletContext, just like a normal servlet.

Hello Service
package example;

public class BasicService implements Basic {
  private String _greeting = "Hello, world";

  public void setGreeting(String greeting)
  {
    _greeting = greeting;
  }

  public String hello()
  {
    return _greeting;
  }
}

Configuration with Dependency Injection in Resin 3.0

resin-web.xml
<web-app xmlns="http://caucho.com/ns/resin">
  <servlet servlet-name="hello"
           servlet-class="com.caucho.hessian.server.HessianServlet">
    <init>
      <home resin:type="example.BasicService">
        <greeting>Hello, world</greeting>
      </home>

      <home-api>example.Basic</home-api>
    </init>
  </servlet>

  <servlet-mapping url-pattern="/hello"
                   servlet-name="hello"/>
</web-app>

Configuration for standard web.xml

Since the HessianServlet is a standard servlet, it can also be configured in the standard servlet configuration.

web.xml
<web-app>
  <servlet>
   <servlet-name>hello</servlet-name>
   <servlet-class>com.caucho.hessian.server.HessianServlet</servlet-class>
    <init-param>
      <param-name>home-class</param-name>
      <param-value>example.BasicService</param-value>
    </init-param>
    <init-param>
      <param-name>home-api</param-name>
      <param-value>example.Basic</param-value>
    </init-param>
  </servlet>

  <servlet-mapping>
    <url-pattern>/hello</url-pattern>
    <servlet-name>hello</servlet-name>
  </servlet-mapping>
</web-app>

Hessian Serialization

The Hessian classes can be used for serialization and deserialization. Hessian's serialization forms the basis for the protocol and taking control of the serialization lets application use Hessian more efficiently than the proxy interface for specialized application protocols.

Serialization
Object obj = ...;

OutputStream os = new FileOutputStream("test.xml");
Hessian2Output out = new Hessian2Output(os);

out.writeObject(obj);
os.close();
Deserialization
InputStream is = new FileInputStream("test.xml");
Hessian2Input in = new Hessian2Input(is);

Object obj = in.readObject(null);
is.close();

When serializing Java objects more complex than primitives or Strings, make sure the classes for those objects implement java.io.Serializable.

Hessian with large binary data

When a distributed application needs to send large amounts of binary data, it can be more efficient to use InputStream to avoid allocating large byte arrays. Only the final argument of the method may be an InputStream, since the data is read during invocation. For example, a file downloading service could be implemented efficiently using Hessian.

In this example, the client needs to take control of the Hessian protocol directly, because the proxy interface would require buffering the entire file before the call returns.

file upload API
package example;

public interface Upload {
  public void upload(String filename, InputStream data);
}

If the result is an InputStream, it is very important that the InputStream.close() be put in an finally block, because Hessian will not close the underlying HTTP stream until all the data is read and the input stream is closed.

file download API
package example;

public interface Download {
  public InputStream download(String filename, InputStream data);
}
Download Java Code
InputStream is = fileProxy.download("test.xml");

try {
  ... // read data here
} finally {
  is.close();
}

Hessian Debugging

Hessian debugging requires 3.1.3 or later.

Hessian servlet debugging is enabled in a two-step process. First, the "debug" init-param must be set in the web.xml. Second, the java.util.logging level for com.caucho.hessian.servlet must be set to "fine". The configuration in a Resin server might look like the following:

resin-web.xml enabling debugging
<web-app xmlns="http://caucho.com/ns/resin">

  <servlet-mapping url-pattern="/my-bean"
                   servlet-class="example.MyBean">
    <init debug="true"/>
  </servlet-mapping>

  <log name="com.caucho.hessian.server" level="fine"
          path="stdout:"/>

</web-app>

The output might look like the following:

sample debugging output
public class MyBean extends HessianServlet {
  public example.Combine combine(String a, String b)
}


[2007/05/08 02:51:31.000] call 2.0
[2007/05/08 02:51:31.000]   method "combine"
[2007/05/08 02:51:31.000]   "hello"
[2007/05/08 02:51:31.000]   "world"
[2007/05/08 02:51:31.000] reply 2.0
[2007/05/08 02:51:31.000]   /* defun example.Combine [a, b] */
[2007/05/08 02:51:31.000]   object example.Combine (#1)
[2007/05/08 02:51:31.000]     a: "hello"
[2007/05/08 02:51:31.000]     b: "world"

Hessian Streaming

Hessian 3.1.3 introduces a streaming API. Applications can use streaming to send periodic data, e.g. for a Comet-style Flash monitoring application that continually receives updates.

Streaming
import com.caucho.hessian.io.*;

void send(OutputStream os)
{
  Hessian2StreamingOutput out;
  out = new Hessian2StreamingOutput(os);

  Object data;

  while ((data = getNextChunk()) != null) {
    out.writeObject(data);
  }

  out.close();
}

Streaming might be used in combination with Comet-style servlets as provided by Resin.

Hessian Client for a cell-phone

Hessian can be used for even small Java devices. The following classes from com.caucho.hessian.client can be extracted into a J2ME jar:

  • MicroHessianInput
  • MicroHessianOutput
  • HessianRemote
  • HessianServiceException
  • HessianProtocolException

The following example shows the code for using a cell phone as a client. It's a bit more complicated than using the proxy, since the client is responsible for creating the connection and writing the data.

Hello, world
import javax.microedition.io.Connector;
import javax.microedition.io.HttpConnection;

...

MicroHessianInput in = new MicroHessianInput();

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

HttpConnection c = (HttpConnection) Connector.open(url);

c.setRequestMethod(HttpConnection.POST);

OutputStream os = c.openOutputStream();
MicroHessianOutput out = new MicroHessianOutput(os);

out.call("hello", null);

os.flush();

is = c.openInputStream();

MicroHessianInput in = new MicroHessianInput(is);
Object value = in.readReply(null);

Copyright © 1998-2015 Caucho Technology, Inc. All rights reserved. Resin ® is a registered trademark. Quercustm, and Hessiantm are trademarks of Caucho Technology.

Cloud-optimized Resin Server is a Java EE certified Java Application Server, and Web Server, and Distributed Cache Server (Memcached).
Leading companies worldwide with demand for reliability and high performance web applications including SalesForce.com, CNET, DZone and many more are powered by Resin.

home company docs 
app server