<title>Using Hessian</title>

<summarylist/>

<p/>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.

<p/>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.

<p/>The <a href="http://www.caucho.com/hessian">Hessian home page</a> contains the latest information about Hessian including the <a
href="http://www.caucho.com/hessian/hessian-draft-spec.xtp">Hessian
specification</a>.

<section title="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&nbsp;1.3.

<p/>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.

<example title="API for Basic service">
package hessian.test;

public interface Basic {
  public String hello();
}
</example>

<p/>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.

<example title="Hessian Client for Basic service">
package hessian.test;

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());
  }
}
</example>

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.

</section>

<section title="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.

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

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

<example title="Hello Service">
package hessian.test;

import com.caucho.hessian.server.HessianServlet;

public class BasicService extends HessianServlet implements Basic {
  public String hello()
  {
    return "Hello, world";
  }
}
</example>

</section>

<section title="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:

<ul>
<li>MicroHessianInput
<li>MicroHessianOutput
<li>HessianRemote
<li>HessianServiceException
<li>HessianProtocolException
</ul>

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.

<example title='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);
</example>

</section>

<section title="Hessian Serialization">

The Hessian classes can be used for serialization and deserialization.

<example title='Serialization'>
Object obj = ...;

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

out.writeObject(obj);
os.close();
</example>

<example title='Deserialization'>
InputStream is = new FileInputStream("test.xml");
HessianInput in = new HessianInput(is);

Object obj = in.readObject(null);
is.close();
</example>

</section>

