<document>
  <header>
    <product>resin</product>
    <title>Burlap Addition</title>
    <description>
      <p>The addition example creates a Burlap web services
with a servlet and uses that web service from a
JSP client.</p>
    </description>
    <type>tutorial</type>
    <tutorial-startpage>demo.jsp</tutorial-startpage>
  </header>

  <body>
    <summary/>
<s1>

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

<p>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 <a href="http://caucho.com/hessian/">http://www.caucho.com/hessian/</a>
for non-Resin clients and servers.</p>

<p>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.</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>The <a href="doc|burlap-1.0-spec.xtp">Burlap 1.0 spec</a> describes
the full Burlap protocol.</p>
</s1>

<s1 title="Files in this tutorial">
<deftable>
<tr>
  <td><viewfile-link file="WEB-INF/classes/example/MathService.java"/></td>
  <td>Interface for the math service.</td>
</tr>
<tr>
  <td><viewfile-link file="WEB-INF/classes/example/BurlapMathService.java"/></td>
  <td>The main service implementation.</td>
</tr>
<tr>
  <td><viewfile-link file="WEB-INF/web.xml"/></td>
  <td>Configures the environment</td>
</tr>
<tr>
  <td><viewfile-link file="demo.jsp"/></td>
  <td>Client JSP</td>
</tr>
</deftable>
</s1>

<s1 title="The Burlap Protocol">

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

<p>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.</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 call does not need to specify the service name because the
service is uniquely specified by the URL.</p>

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

</s1>

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

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

</s1>

<s1 title="Service Implementation">

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

<example title="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;
  }
}
</example>

</s1>

<s1 title="Remote Interface">

<p>The Java interface describes the remote API.  This example has an
addition method, <var>add()</var>.</p>

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

<example title="MathService.java">
package example;

public interface MathService {
  public int add(int a, int b);
}
</example>

</s1>

<s1 title="Java Client">

<p>RPC clients follow the following steps in using a remote object:</p>
<ol>
<li>Determine the URL of the remote object.
</li><li>Obtain a proxy stub from a proxy factory.
</li><li>Call methods on the proxy stub.
</li></ol>

<example title="client.jsp">
&lt;%@ page import="com.caucho.burlap.client.BurlapProxyFactory" %&gt;
&lt;%@ page import="example.MathService" %&gt;
&lt;%
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));
%&gt;
</example>
<results>
3 + 2 = 5
</results>

</s1>

  </body>
</document>
