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

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

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

<section 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'>
<burlap:call>
  <method>add</method>
  <int>2</int>
  <int>3</int>
</burlap:call>
</example>

<example title='Burlap reply'>
<burlap:reply>
  <int>5</int>
</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>

</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>The remote interface is used by the Hessian proxy
factory to create a proxy stub implementing the service's interface.</p>

</section>

<section title="Service 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.  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>

</section>

<section title="Remote Interface">

<p>The Java interface describes the remote API.  This example has an
addition method, <var/add()/>.</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>

</section>

<section 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>Obtain a proxy stub from a proxy factory.
<li>Call methods on the proxy stub.
</ol>

<example title="client.jsp">
&lt;%@ page import="com.caucho.burlap.client.BurlapProxyFactory" %>
&lt;%@ page import="example.MathService" %>
&lt;%
BurlapProxyFactory factory = new BurlapProxyFactory();

// http://localhost:8080/resin-doc/protocols/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));
%>
</example>
<results>
3 + 2 = 5
</results>

</section>

  </body>
</document>
