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

Jetty has got enough documentation to get you started; if you want more you can get support from the creators of Jetty. This post was inspired by this particular page from the docs. I setup a very small Eclipse project that can be downloaded as tar.gz or zip; alternatively, you can browse the code here.

JUnit scaffolding

Lets have a look at a small JUnit class, that implements a setUp method to bootstrap Jetty:

import org.junit.Before;
import org.mortbay.jetty.testing.HttpTester;
import org.mortbay.jetty.testing.ServletTester;
 
public class WebAppTest {
  private ServletTester tester;
  private HttpTester request;
  private HttpTester response;
 
  @Before
  public void setUp() throws Exception {
    this.tester = new ServletTester();
    this.tester.setContextPath("/");
    this.tester.addServlet(MyServlet.class, "/");
    this.tester.start();
 
    this.request = new HttpTester();
    this.response = new HttpTester();
    this.request.setMethod("GET");
    this.request.setHeader("Host", "tester");
    this.request.setVersion("HTTP/1.0");
  }

This method leverages the features provided by the ServletTester class, which will create a Jetty server for us. Instead of writing a web.xml, we can add servlets to the server programmatically. After that we start the server and create a request/response pair that can be used in the test methods.

Testing

Now you can write several test methods for every request you’d like to check. If you want to check the start page of your web application you set the URI, generate a request, send it to Jetty, receive the response and check it like so:

  @Test
  public void testHomepage() throws Exception {
    this.request.setURI("/");
    this.response.parse(tester.getResponses(request.generate()));
    assertTrue(this.response.getMethod() == null);
    assertEquals(200, this.response.getStatus());
    assertEquals("Hello World", this.response.getContent());
  }

In this simple case the MyServlet class contains a line like this:

  response.getWriter().append("Hello World");

Conclusion

Jetty is said to be highly embeddable. As far as I’ve checked it out, that’s absolutely true. Due to this it’s very easy to use Jetty inside unit tests. I haven’t tried to use Jetty with web frameworks but that should be no problem either. So if you’d like to test your servlets I recommend checking out Jetty.