<document>
  <header>
    <product>resin</product>
    <title>A Simple Service for Resin Remoting</title>
    <description>
      <p>Writing a service for the Resin remoting as a plain-old Java object (POJO)
      eliminates protocol dependencies and simplifies service testing.
      </p>
    </description>
    <type>tutorial</type>
    <tutorial-startpage>demo.jsp</tutorial-startpage>
  </header>

  <body>
    <localtoc/>

  <s1>
<p>With the Resin remoting, services can be written as 
plain-old Java objects (POJOs) and made available to many different protocols
using simple configuration changes.
</p>
</s1>

<s1 title="See Also">

<ul>
<li><a href="../../doc/resin-remoting.xtp">Resin remoting</a> for a full
description.</li>
</ul>

</s1>

<s1 title="Files in this tutorial">
<deftable>
<tr>
  <th>File</th>
  <th>Description</th>
</tr>
<tr>
  <td><viewfile-link file="WEB-INF/classes/example/HelloService.java"/></td>
  <td>Interface for the hello service.</td>
</tr>
<tr>
  <td><viewfile-link file="WEB-INF/classes/example/HelloServiceImpl.java"/></td>
  <td>The main service implementation.</td>
</tr>
<!--
<tr>
  <td><viewfile-link file="WEB-INF/classes/example/HelloResult.java"/></td>
  <td>The result object</td>
</tr>
-->
<tr>
  <td><viewfile-link file="WEB-INF/resin-web.xml"/></td>
  <td>Configures the environment</td>
</tr>
<tr>
  <td><viewfile-link file="demo.jsp"/></td>
  <td>Client JSP</td>
</tr>
<tr>
  <td><viewfile-link file="demo.php"/></td>
  <td>Client PHP</td>
</tr>
</deftable>
</s1>

<s1 title="Introduction">
<p></p>
<figure src="soa.png"/>
<p>
The Resin remoting is an infrastructure that
allows a service to be exposed via many different service protocols.
For example in this tutorial, there is a plain-old Java object (POJO) that
implements a service and this service is made available using REST, SOAP,
Hessian, and WebBeans.  The service is implemented once and these protocols
are activated with a few simple changes to the configuration file.
</p>
</s1>

<s1 title="Service Interface">

<p>In this example, the service interface is for a simple Hello, World service.
There is a single method, <code>hello()</code> that the service must implement
and the client may invoke.</p>

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

public interface HelloService {
  /**
   * Returns "hello, world".
   */
  public String hello();
}
</example>

</s1>

<s1 title="Service Implementation">

<p>The HelloService implementation is just a Java class that implements
the HelloService API.  It can optionally use EJB annotations like @Remote,
@Stateless or @TransactionAttribute.</p>

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

public class HelloServiceImpl implements HelloService {
  /**
   * Returns "hello, world".
   */
  public String hello()
  {
    return "hello, world";
  }
}
</example>

</s1>

<s1 title="Service configuration">

<p>Services for Resin remoting are configured with the &lt;servlet>
tag.  The implementation class is given as
the <code>servlet-class</code> attribute.
It is possible to allow access to the service within the same virtual machine
by registering the service as a WebBeans singleton with &lt;bean>.
</p>

<p>
To expose the service as a Hessian service, use the &lt;hessian> tag.
Hessian is one of the <em>protocols</em> available for web services.
</p>

<!--
<p>
Here a REST interface is also exposed.  In this
example, the REST interface uses the default
query-based binding that interprets URLs of the form
<url>http://www.foo.com/?method=myMethod&amp;arg1=foo&amp;arg2=bar</url>.
to be a call to the method "myMethod" with two arguments,
"foo" and "bar".  Other custom bindings are possible, including
for example a path-based binding that with URLs of the form
<url>http://www.foo.com/myMethod/foo/bar</url>.
The &lt;url-pattern> child tag specifies the base URL for the REST interface.
</p>
-->
<p>
Finally, a SOAP interface is available, using CXF or XFire.
</p>

<example title="remoting service for hessian">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;servlet-mapping url-pattern="/hello/hessian/*"
                   servlet-class="example.HelloServiceImpl">
    &lt;protocol uri="hessian:"/>
  &lt;/servlet-mapping>

&lt;/web-app>
</example>
<!--
<example title="removing service for rest">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;servlet-mapping url-pattern="/hello/hessian/*"
                   servlet-class="example.HelloServiceImpl">
    &lt;protocol type="rest"/>
  &lt;/servlet-mapping>

&lt;/web-app>
</example>
-->
<example title="remote service for CXF">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;servlet-mapping url-pattern="/hello/hessian/*"
                   servlet-class="example.HelloServiceImpl">
    &lt;protocol uri="cxf:"/>
  &lt;/servlet-mapping>

&lt;/web-app>
</example>

<example title="service as WebBeans singleton">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;bean class="example.HelloServiceImpl" name="vm"/>

&lt;/web-app>
</example>

</s1>

<s1 title="Client configuration">

<p>
Resin also makes it easy to access services using the 
&lt;remote-client> tag.  This tag connects to a service
using a URI of the form <i>&lt;protocol>:url=&lt;location></i>.
The example below shows just such a URL.  The interface of the service
is required.  The &lt;remote-client> tag
creates a proxy client instance for the service and registers the
proxy with WebBeans.
</p>

<example title="&lt;remote-client>">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;remote-client interface="example.HelloService" name="hessian">
    &lt;uri>hessian:url=${webApp.url}/hello/hessian/&lt;/uri>
  &lt;/remote-client>  

  &lt;remote-client interface="example.HelloService" name="rest">
    &lt;uri>rest:url=${webApp.url}/hello/rest/&lt;/uri>
  &lt;/web-service-client>

  &lt;remote-client interface="example.HelloService" name="soap">
      &lt;uri>xfire:url=${webApp.url}/hello/soap/&lt;/url>
  &lt;/remote-client>

&lt;/web-app>
</example>

</s1>

<s1 title="JSP Client Script">

<p>The client can now connect to the HelloService using any supported
encoding simply by doing a WebBeans injection.</p>

<example title="demo.jsp">
&lt;%@ page import="javax.webbeans.Named" %>
&lt;%@ page import="example.HelloService" %>
&lt;%!
@Named("hessian") HelloService _hessianHello;
@Named("rest") HelloService _restHello;
@Named("soap") HelloService _soapHello;
@Named("vm") HelloService _vmHello;
%>
&lt;pre>
From Hessian: &lt;%= _hessianHello.hello() %>
From REST: &lt;%= _restHello.hello() %>
From SOAP: &lt;%= _soapHello.hello() %>
From VM: &lt;%= _vmHello.hello() %>
&lt;/pre>
</example>
<results>
From Hessian: hello, world
From REST: hello, world
From SOAP: hello, world
From VM: hello, world
</results>

</s1>

<s1 title="PHP Client Script">

<p>The client can now connect to the HelloService
using PHP with the <code>java_bean()</code> method.</p>

<example title="demo.php">
&lt;?php
$hessian = java_bean("hessian");
$rest = java_bean("rest");
$soap = java_bean("soap");
$vm = java_bean("vm");
?>
&lt;pre>
From Hessian: &lt;?= $hessian->hello() ?>
From REST: &lt;?= $rest->hello() ?>
From SOAP: &lt;?= $soap->hello() ?>
From VM: &lt;?= $vm->hello() ?>
&lt;/pre>
</example>
<results>
From Hessian: hello, world
From REST: hello, world
From SOAP: hello, world
From VM: hello, world
</results>

</s1>

  </body>
</document>
