Burlap
Resin 3.1

Documentation
Examples
Changes

Overview
Quick Start
Installation
Command-Line
Configuration
Admin
Amber
Clustering
Caching
Database
Deployment
EJB 3.0
Embedding
Filters
Hessian
HMTP
IoC
JSP
Logging
Messaging
Performance
Quercus/PHP
Remoting
Scheduled Tasks
Security
Server Push
Servlets
Third-party
Troubleshooting
Virtual Hosting
Watchdog
WebApp
XML and XSLT

Hessian
Hessian 1.0 spec
Hessian 2.0 draft spec
Java Binding
Burlap
Burlap 1.0 Spec
Burlap Design Notes
Hessian Messaging
Java Binding
Hessian
Burlap 1.0 Spec

Burlap is a simple XML-based protocol for connecting web services. The com.caucho.burlap.client and com.caucho.burlap.server packages do not require any other Resin classes, so can be used in smaller clients, like applets.

Because Burlap 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.

Burlap Client

Using a Burlap service from a Java client is like calling a method. The BurlapProxyFactory creates proxies which act like normal Java objects, with possibility that the method might throw a protocol exception if the remote connection fails. Using BurlapProxyFactory requires JDK 1.3.

Each service will have a normal Java interface describing the service. The trivial hello, world example just returns a string. Because the Burlap services support Java serialization, any Java type can be used.

API for Basic service
package burlap.test;

public interface Basic {
  public String hello();
}

The following is an example of a standalone Burlap client. The client creates a BurlapProxyFactory. 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.

Burlap Client for Basic service
package burlap.test;

import java.net.URL;

import com.caucho.burlap.client.BurlapProxyFactory;

public class BasicClient {
  public static void main(String []args)
    throws Exception
  {
    URL url = new URL("http://www.caucho.com/burlap/test/basic");

    BurlapProxyFactory factory = new BurlapProxyFactory();
    Basic basic = (Basic) factory.create(Basic.class, url);

    System.out.println("Hello: " + basic.hello());
  }
}

There are no more complications to using the client. The service can add methods and use any Java type for parameters and results.

Burlap Service

While most Burlap services will use Resin-CMP or Resin-EJB, to take advantage of the benefits of EJB, the Burlap library makes it possible to write services by extending BurlapServlet.

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

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

Hello Service
package burlap.test;

import com.caucho.burlap.server.BurlapServlet;

public class BasicService extends BurlapServlet implements Basic {
  public String hello()
  {
    return "Hello, world";
  }
}

Burlap Client for a cell-phone

Burlap can be used for even small Java devices. The following classes from com.caucho.burlap.client can be extracted into a J2ME jar:

  • MicroBurlapInput
  • MicroBurlapOutput
  • BurlapRemote
  • BurlapServiceException
  • BurlapProtocolException

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.

Hello, world
import javax.microedition.io.Connector;
import javax.microedition.io.HttpConnection;

...

MicroBurlapInput in = new MicroBurlapInput();

String url = "http://www.caucho.com/burlap/test/basic";

HttpConnection c = (HttpConnection) Connector.open(url);

c.setRequestMethod(HttpConnection.POST);

OutputStream os = c.openOutputStream();
MicroBurlapOutput out = new MicroBurlapOutput(os);

out.call("hello", null);

os.flush();

is = c.openInputStream();

MicroBurlapInput in = new MicroBurlapInput(is);
Object value = in.readReply(null);

Burlap Serialization

The Burlap classes can be used for serialization and deserialization.

Serialization
Object obj = ...;

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

out.writeObject(obj);
os.close();
Deserialization
InputStream is = new FileInputStream("test.xml");
BurlapInput in = new BurlapInput(is);

Object obj = in.readObject(null);
is.close();

Java Binding
Hessian
Burlap 1.0 Spec
Copyright © 1998-2006 Caucho Technology, Inc. All rights reserved.
Resin ® is a registered trademark, and Quercustm, Ambertm, and Hessiantm are trademarks of Caucho Technology.