Writing a service for the Resin SOA as a plain-old Java object (POJO) eliminates protocol dependencies and simplifies service testing.

Demo

With the Resin Service-Oriented Architecture, services can be written as plain-old Java objects (POJOs) and made available to many different protocols using simple configuration changes.

Files in this tutorial

What is a Service-Oriented Architecture?

The Resin Service-Oriented Architecture 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 JNDI. The service is implemented once and these protocols are activated with a few simple changes to the configuration file.

Service Interface

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

package example;

import javax.jws.WebMethod;
import javax.jws.WebService;

@WebService
public interface HelloService {
  /**
   * Returns "hello, world".
   */
  @WebMethod
  public HelloResult hello();
}

Notice that the service returns a HelloResult object. As seen below, HelloResult is a simple wrapper for a String. This allows type-checking and proper serialization of the returned result. There are also JAXB annotations in this case which control how the object is serialized.

package example;

import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name="hello")
public class HelloResult {

  @XmlElement
  public String value = "hello, world";

  public String toString()
  {
    return value;
  }
}

Service Implementation

The HelloService implementation is just a Java class that implements the HelloService API. For Java Web Service (JAX-WS) compatibility, the class also has @WebService and @WebMethod annotations.

package example;

import javax.jws.WebMethod;
import javax.jws.WebService;

@WebService(endpointInterface="example.HelloService")
public class HelloServiceImpl implements HelloService {
  /**
   * Returns "hello, world".
   */
  @WebMethod
  public HelloResult hello()
  {
    return new HelloResult();
  }
}

Service configuration

Services in the Resin SOA are configured with the <servlet> tag. The implementation class is given as the servlet-class attribute. It is possible to allow access to the service within the same virtual machine by registering the service in JNDI using a <jndi-name> child tag.

To expose the service as a Hessian service, use the <hessian> tag. Hessian is one of the protocols available for web services.

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 http://www.foo.com/?method=myMethod&arg1=foo&arg2=bar. 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 http://www.foo.com/myMethod/foo/bar. The <url-pattern> child tag specifies the base URL for the REST interface.

Finally, a SOAP interface is available.

<servlet-mapping url-pattern="/hello/hessian/*"
                 jndi-name="service/HelloService"
                 servlet-name="hello-hessian"
                 servlet-class="example.HelloServiceImpl">
  <protocol type="hessian"/>
</servlet-mapping>

<servlet-mapping url-pattern="/hello/rest/*"
                 servlet-name="hello-rest"
                 servlet-class="example.HelloServiceImpl">
  <protocol type="rest"/>
</servlet-mapping>

<servlet-mapping url-pattern="/hello/rest/*"
                 servlet-name="hello-soap"
                 servlet-class="example.HelloServiceImpl">
  <protocol type="soap"/>
</servlet-mapping>

Client configuration

Resin also makes it easy to access services using the <web-service-client> tag. This tag connects to a service using a URL of the form <encoding>:<protocol>:<location>. The example below shows just such a URL. The interface of the service and a JNDI name must also be given. The <web-service-client> tag creates a proxy client instance for the service and registers the proxy with the given JNDI name.

<web-service-client jndi-name="hessian/HelloService">
  <url>hessian:${webApp.url}/hello/hessian/</url>
  <interface>example.HelloService</interface>
</web-service-client>  

<web-service-client jndi-name="rest/HelloService">
  <url>rest:${webApp.url}/hello/rest/</url>
  <interface>example.HelloService</interface>
</web-service-client>

<web-service-client jndi-name="soap/HelloService">
  <url>soap:${webApp.url}/hello/soap/</url>
  <interface>example.HelloService</interface>
</web-service-client>

JSP Client Script

The client can now connect to the HelloService using any supported encoding simply by doing a lookup in JNDI.

<%@ page import="com.caucho.naming.Jndi" %>
<%@ page import="example.HelloService" %>
<%
HelloService hessianHello = (HelloService) Jndi.lookup("hessian/HelloService");
HelloService restHello = (HelloService) Jndi.lookup("rest/HelloService");
HelloService soapHello = (HelloService) Jndi.lookup("soap/HelloService");
HelloService vmHello = (HelloService) Jndi.lookup("service/HelloService");
%>
<pre>
From Hessian: <%= hessianHello.hello() %>
From REST: <%= restHello.hello() %>
From SOAP: <%= soapHello.hello() %>
From VM: <%= vmHello.hello() %>
</pre>

From Hessian: hello, world
From REST: hello, world
From SOAP: hello, world
From VM: hello, world

Demo