Caucho Technology
documentation
examples
changes

amber (jpa)
ejb
database
ioc
jmx
jsf
messaging
quercus
remoting
servlet
security

hessian serialization
hessian addition
service addition
hessian with di
burlap addition
custom-protocol
simple service
client injection

burlap addition


The addition example creates a Burlap web services with a servlet and uses that web service from a JSP client.

Demo

Burlap is a lightweight XML RPC protocol. Burlap is designed to be self-describing, eliminating the requirement for external IDLs or WSDL files. Because it is as small as possible and language-independent, non-Java Burlap implementations are can easily develop comprehensive test suites.

This tutorial only requires the open source Java implementation of the Burlap client and server included in the Hessian distribution. It can be downloaded from http://www.caucho.com/hessian/ for non-Resin clients and servers.

Because Resin's EJB implementation can use Burlap as its remote procedure call protocol, EJB developers can easily expose services to clients from other languages.

Because EJB clients and servers are written without knowledge of the underlying protocol, even if you intend to deploy with another protocol, like RMI/IIOP, you can develop using Resin's Burlap.

The Burlap 1.0 spec describes the full Burlap protocol.

Files in this tutorial

WEB-INF/classes/example/MathService.javaInterface for the math service.
WEB-INF/classes/example/BurlapMathService.javaThe main service implementation.
WEB-INF/web.xmlConfigures the environment
demo.jspClient JSP

The Burlap Protocol

A Burlap call is just an HTTP POST to a URL. The arguments are serialized into the Burlap XML format and passed to the server.

Most applications will never need to look at the Burlap protocol, but it's simple enough that a basic example can help show what's happening underneath the API.

Burlap call
<burlap:call>
  <method>add</method>
  <int>2</int>
  <int>3</int>
</burlap:call>
Burlap reply
<burlap:reply>
  <int>5</int>
</burlap:reply>

The call does not need to specify the service name because the service is uniquely specified by the URL.

The following Addition example shows how to create a basic server so you can test Burlap.

A Burlap Example

Using Burlap requires three components:

  1. A remote interface
  2. The server implementation
  3. The client (JSP or servlet)

The remote interface is used by the Hessian proxy factory to create a proxy stub implementing the service's interface.

Service Implementation

Resin's Burlap provides a simple way of creating a server. Just extend BurlapServlet with your remote methods. The Burlap call will just be a POST to that servlet. BurlapServlet will introspect the service and expose the methods.

BurlapMathService.java
package example;

import com.caucho.burlap.server.BurlapServlet;

public class BurlapMathService extends BurlapServlet {
  public int add(int a, int b)
  {
    return a + b;
  }
}

Remote Interface

The Java interface describes the remote API. This example has an addition method, add().

Resin's proxy client implementation uses the remote interface to expose the API to the proxy stub. Strictly speaking, though, the Java remote interface is not required for Burlap. A non-Java client will not use the Java interface, except possibly as documentation.

MathService.java
package example;

public interface MathService {
  public int add(int a, int b);
}

Java Client

RPC clients follow the following steps in using a remote object:

  1. Determine the URL of the remote object.
  2. Obtain a proxy stub from a proxy factory.
  3. Call methods on the proxy stub.
client.jsp
<%@ page import="com.caucho.burlap.client.BurlapProxyFactory" %>
<%@ page import="example.MathService" %>
<%
BurlapProxyFactory factory = new BurlapProxyFactory();

// http://localhost:8080/resin-doc/tutorial/burlap-add/burlap/math

String url = ("http://" +
              request.getServerName() + ":" + request.getServerPort() +
              request.getContextPath() + "/burlap/math");

MathService math = (MathService) factory.create(MathService.class, url);

out.println("3 + 2 = " + math.add(3, 2));
%>
3 + 2 = 5

Demo


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