<document>

The Resin-EJB implementation uses Burlap as its remote procedure call protocol and its object serialization protocol. Because Burlap is simple, clients from other languages can easily access the EJB services.

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.

A working draft of the Burlap 1.0 draft spec is now available.

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

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

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

Burlap is a very simple, yet complete, RPC protocol. It's main purpose is to make testing and debugging of remote procedure calls easier. Since it's simple, its performance should be usable for almost all sites. Even if the final deployed site will use other protocols, you can use Burlap to speed development.

Using Burlap requires three components:

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

These three components are also needed for any EJB implementation; they're just a bit more complicated in EJB. When testing this example, you can create WEB-INF/classes/test/Hello.java and WEB-INF/classes/test/HelloRpcServlet.java and Resin will handle the compilation for you.

The Java interface describes the remote API. This example has a single method, hello(). Because you need to treat remote calls with more care than local calls, the Hello interface throws a RemoteException.

package test; import javax.ejb.*; import java.rmi.*; public interface Hello extends Remote { public String hello() throws RemoteException; }

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.

This simplifies creating services. You can ignore the complexities of EJB and just get going.

package test; import java.rmi.*; import com.caucho.burlap.*; public class HelloRpcServlet extends BurlapServlet implements Hello { public String hello() throws RemoteException { return "Hello, world"; } }

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

1. Create a handle to the remote object.
2. Obtain a stub from the handle.
3. Call methods on the stub.

The handle is a locator to the remote service. The handle is a pair consisting of:

1. the URL locating the remote server
2. the Java class of the remote interface

<%@ page import="com.caucho.burlap.*, test.*" %> <% String url = "http://localhost:8080/servlet/test.HelloRpcServlet/"; BurlapHomeHandle handle = new BurlapHomeHandle(url); Hello hello = (Hello) handle.getEJBHome(); %> message: <%= hello.hello() %> <results> message: Hello, world </results>

Since the example uses the burlap protocol, you can use 'telnet' as a simple client.

<results> unix> telnet localhost 8080 Trying 127.0.0.1... Connected to localhost (127.0.0.1). Escape character is '^]'. POST /servlet/test.HelloRpcServlet HTTP/1.0 Content-Length: 54 <burlap:call> <method>hello</method> </burlap:call> HTTP/1.0 200 OK Server: Resin/1.3.s010312 Content-Length: 73 Date: Tue, 13 Mar 2001 03:15:27 GMT <burlap:reply> <string>Hello, world</string> </burlap:reply> </results>

The results have some added whitespace to make the example more readable. The server doesn't bother trying to pretty-print the results.

</document>