<document>
  <header>
    <product>resin-ee</product>
    <resin-2.0>$ee/ejb-tut/burlap.xtp</resin-2.0>
    <title>Burlap Hello</title>
  </header>

  <body>
    <summary/>
<p>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.</p>

<p>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.</p>

<p>A working draft of the
<a href="../../burlap-draft-spec.xtp">Burlap 1.0 draft spec</a> is
now available.</p>

<section title='Burlap'>

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

<example title='Burlap call'>
&lt;burlap:call>
  &lt;method>add&lt;/method>
  &lt;int>2&lt;/int>
  &lt;int>3&lt;/int>
&lt;/burlap:call>
</example>

<example title='Burlap reply'>
&lt;burlap:reply>
  &lt;int>5&lt;/int>
&lt;/burlap:reply>
</example>

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

</section>

<section title="Why Burlap?">

<p>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.</p>

</section>

<section title="A Burlap Example">
<p>Using Burlap requires three components:</p>
<ol>
<li>A remote interface
<li>The server implementation
<li>The client (JSP or servlet)
</ol>

<p>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.</p>
</section>

<section title="Remote Interface">

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

<example title="Hello.java">
package test;

import javax.ejb.*;
import java.rmi.*;

public interface Hello extends Remote {
  public String hello() throws RemoteException;
}
</example>

</section>

<section title="Server Implementation">

<p>Resin's Burlap provides a simple way of creating a server.  Just extend
<code/BurlapServlet/> with your remote methods.  The Burlap call will just
be a POST to that servlet.</p>

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

<example title="HelloRpcServlet.java">
package test;

import java.rmi.*;
import com.caucho.burlap.*;

public class HelloRpcServlet extends BurlapServlet implements Hello {
  public String hello() throws RemoteException
  {
    return "Hello, world";
  }
}
</example>

</section>
<section title="Client">

<p>RPC clients follow the following steps in using a remote object:</p>
<ol>
<li>Create a <var/handle/> to the remote object.
<li>Obtain a <var/stub/> from the handle.
<li>Call methods on the <var/stub/>.
</ol>

<p>The handle is a locator to the remote service.  The handle is
a pair consisting of:</p>
<ol>
<li>the URL locating the remote server
<li>the Java class of the remote interface
</ol>

<example title="hello.jsp">
&lt;%@ page import="com.caucho.burlap.*, test.*" %>
&lt;%
String url = "http://localhost:8080/servlet/test.HelloRpcServlet/";

BurlapHomeHandle handle = new BurlapHomeHandle(url);
Hello hello = (Hello) handle.getEJBHome();
%>
message: &lt;%= hello.hello() %>
</example>
<results>
message: Hello, world
</results>

</section>

<section title="Burlap protocol for the example">

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

<results>
unix> <var/telnet localhost 8080/>
Trying 127.0.0.1...
Connected to localhost (127.0.0.1).
Escape character is '^]'.
<var/POST /servlet/test.HelloRpcServlet HTTP/1.0/>
<var/Content-Length: 54/>

<var/&lt;burlap:call>/>
<var/&lt;method>hello&lt;/method>/>
<var/&lt;/burlap:call>/>

HTTP/1.0 200 OK
Server: Resin/1.3.s010312
Content-Length: 73
Date: Tue, 13 Mar 2001 03:15:27 GMT

&lt;burlap:reply>
&lt;string>Hello, world&lt;/string>
&lt;/burlap:reply>
</results>

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

</section>
  </body>
</document>
