Webservices with Hessian and Burlap

Java /

Developing webservices with Hessian or Burlap can be really fun. While Hessian is a binary protocol, Burlap is the XML-based counterpart; both can be used for RPC over HTTP. They can be used to serialize any object but they’re predestined to connect web services. It’s as easy as this:

  • create an interface for your webservice
  • implement this interface in a class that extends either HessianServlet or BurlapServlet
  • deploy a HessianServlet or BurlapServlet in your application server and configure it to use your newly created service
  • use the HessianProxyFactory or BurlapProxyFactory to create an instance of your service that transparently talks to the deployed servlet.

I wrote a little test application that demonstrates the aforementioned steps in action. You can download the Eclipse project as tar.gz or zip or browse the code here. I haven’t used Spring, but if you plan to integrate Hessian or Burlap into your Spring-powered application have a look at the API docs.

If you try to run the code don’t upgrade Hessian to version 3.0.8 as this will result in and infinite loop in the init method of the HessianServlet. This has been reported here and there and it is fixed in version 3.1.2 – so wait until this version reaches the Maven repositories.

How to?

Lets go a little bit into detail how to expose a service with Hessian and Burlap to the web. First, we’ll create an interface for our service:

public interface Calculator {
  public int add(int a, int b);
  public int sub(int a, int b);
  public int div(int a, int b);
  public int mul(int a, int b);
}

Next, this Calculator service will be implemented in a class that either extends HessianServlet or BurlapServlet. Have a look at the latter variant:

public class CalculatorService extends BurlapServlet
                               implements Calculator {
  public int add(int a, int b) { return a + b; }
  public int sub(int a, int b) { return a - b; }
  public int div(int a, int b) { return a / b; }
  public int mul(int a, int b) { return a * b; }
}

As you can see you can concentrate on the implementation of the methods provided by the Calculator interface.

Before you can access the service, you’ll have to deploy the CalculatorService servlet in an application server. To stick with this example you would take the default BurlapServlet and set its init parameters service-class and api-class to CalculatorService and Calculator respectively.

Finally, you can access the service with a client: create an instance of your service with the HessianProxyFactory or BurlapProxyFactory and requests to the service will be made transparently.

String url = "http://www.example.com/calc";
BurlapProxyFactory factory = new BurlapProxyFactory();
Calculator calc = (Calculator) factory.create(Calculator.class, url);

Now you can make calls like calc.add(1,2) – it’s as easy as this.

Testing

In a post about testing web applications I showed how to use Jetty for this purpose. We can do this here again and you can have a look at the complete code here. The important part is this:

ServletTester tester;
...
Class burlapServlet = BurlapServlet.class;
String serviceName = CalculatorService.class.getName();
String apiName = Calculator.class.getName();
...
ServletHolder servletHolder = tester.addServlet(burlapServlet, "/calc");
servletHolder.setInitParameter("service-class", serviceName);
servletHolder.setInitParameter("api-class", apiName);

This hands the init parameters to the BurlapServlet. Once you’ve done that you can start requests with a client.

Conclusion

It was said that you should just use Hessian or Burlap if you don’t have to worry about interoperability. I think that this has changed in two ways.

First, there are implementations available for various languages. If you plan to support one of these, you’re all set:

  • Java
  • Python
  • C++
  • .NET C#
  • D
  • Erlang
  • PHP
  • Ruby

Second, both tools are very easy to use. From a page about the design goals for Burlap:

If browsers mess up the simple cookie spec, the SOAP, XML Schema, SOAP Attachment, WSDL, and more! specs, are likely to cause interoperability and testing problems, like CORBA/IIOP did. Burlap tries to eliminate ambiguity so these problems never show up in the first place.

This might be true and it will be interesting how these technologies will develop in the future. But I guess that we’ll always have heavyweight and lightweight tools at our disposal (doh, who would have thought).

That being said, I think that Hessian and Burlap do a perfect job: you can expose a service to the web without worrying about writing servlets, a protocol or even a schema for the protocol. Since it’s really fun using these tools I fully recommend them.