<document>
  <header>
    <product>resin</product>
    <resin-2.0>$resin/ref/hessian.xtp</resin-2.0>
    <title>Hessian</title>
    <description>
      <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>

      <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>

      <p>The <a href="hessian-1.0-spec.xtp">Hessian specification</a>
itself is a short and interesting description.</p>
    </description>
  </header>

  <body>
    <summary/>


<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 example;

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

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

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

  public String hello()
  {
    return _greeting;
  }
}
</example>

<section title="Configuration with Dependency Injection in Resin 3.0">

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

      &lt;home-api>example.Basic&lt;/home-api>
    &lt;/init>
  &lt;/servlet>

  &lt;servlet-mapping url-pattern="/hello"
                   servlet-name="hello"/>
&lt;/web-app>
</example>

</section>

<section title="Configuration for standard web.xml">

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

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

  &lt;servlet-mapping>
    &lt;url-pattern>/hello&lt;/url-pattern>
    &lt;servlet-name>hello&lt;/servlet-name>
  &lt;/servlet-mapping>
&lt;/web-app>
</example>

</section>

</section>

<section title="Hessian Serialization">

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

<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>

<section title="Hessian with large binary data">

<p>When a distributed application needs to send large amounts of
binary data, it can be more efficient to
use <code>InputStream</code> and <code>OutputStream</code> to
avoid allocating large byte arrays.  For example, a file
downloading service could be implemented efficiently using Hessian.</p>

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

<example title="client download code">
OutputStream os = conn.getOutputStream();

HessianOutput out = new HessianOutput(os);
out.startCall("download");
out.writeString("my-file.txt");
out.completeCall();

InputStream is = conn.getInputStream();

HessianInput in = new HessianInput(is);

in.startReply();

InputStream is = in.readInputStream();

... // save the input stream data somewhere

in.completeReply();
</example>

<p>An upload servlet would also take control of the Hessian protocol
to avoid buffering the data argument.  Like the client, the implementation
is straightforward, although more complicated than the basic service.</p>

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

  </body>
</document>
