Consuming web service using Spring

With the adoption of SOA in companies, we have many web applications accessing web services which are local and external. My application currently interacts with web services built by other team with in the organization and also with third party. Java frameworks offer different ways to consume web services and we will have a look what spring framework has to offer.

Consuming web services with Spring is very simple. With Spring you will be able to configure a web service client using XML bean configuration. Spring takes care of creating the client stub when the applications starts. You can then access the web service from the Spring bean container.

Spring provides remoting support for web services via JAX-WS with the help of two factory beans, namely LocalJaxWsServiceFactoryBean and JaxWsPortProxyFactoryBean. I will use the latter as it returns a proxy that implements our business service interface. For this tutorial, I will take a public web service available at WebserviceX.NET. For demo, I have taken the whois lookup service. Here is our bean configuration:

<bean id="whoisService" class="org.springframework.remoting.jaxws.JaxWsPortProxyFactoryBean">
<property name="wsdlDocumentUrl"  value="http://www.webservicex.net/whois.asmx?wsdl" />
<property name="namespaceUri"     value="http://www.webservicex.net" />
<property name="serviceName"      value="whois" />
<property name="portName"         value="whoisSoap" />
<property name="serviceInterface" value="com.spweb.services.WhoIsService" />
</bean>

Now, lets have a closer look at the bean configuration. I have defined five properties; wsdlDocumentUrl holds the WSDL URL for the web service we are going to consume. namespaceUri
defines the namespace, you can get this details from the WSDL file. Next comes the serviceName and portName of the web service. And the final property is the service interface. We will have to create the service interface so that we can interact with web service.

When the spring application starts, the bean gets created and we will be able to access the web service through this bean. To access, I injected the bean to one of my controller (I am using MVC) and call the necessary methods through my service interface. Now, lets have a look at our service interface. Its a simple java interface with some annotations and will have all the methods that we call. Here is our service interface:

@WebService(name = "whoisSoap",
targetNamespace = "http://www.webservicex.net")
public interface WhoIsService {

@WebMethod(operationName = "GetWhoIS",
action = "http://www.webservicex.net/GetWhoIS")
@WebResult(name = "GetWhoISResult", 
targetNamespace = "http://www.webservicex.net")
@RequestWrapper(localName = "GetWhoIS", 
targetNamespace = "http://www.webservicex.net",
className = "net.webservicex.GetWhoIS")
@ResponseWrapper(localName = "GetWhoISResponse", 
targetNamespace = "http://www.webservicex.net", 
className = "net.webservicex.GetWhoISResponse")
public String getWhoIs(@WebParam(name = "HostName", 
targetNamespace = "http://www.webservicex.net")String domain);
}

In order to work with web services, you need to study the WSDL file carefully. All the details come from this file. The first annotation is @WebService, which is used to define the interface as a service endpoint interface. In this case, I have specified the two properties namely, name and targetNamespace. The name property holds the name of wsdl:portType and targetNamespace holds the namespace of the the WSDL.

Next we declare methods which will be called. To tie these methods to the web service calls we use the @WebMethod annotation. The annotation specifies the operation name and action URL. Along with this, we also specify @WebResult,@RequestWrapper,@ResponseWrapper. These annotations provide information regarding request and response data types. The @WebParam is used to map the method parameters with the parameters of the web service.

Finally to consume the web service, I simple call the method as shown below:

if(whoService!=null) {
resultString = whoService.getWhoIs("hostname.com");
}

I do not create a instance of the service bean, instead it gets injected when the application starts. Here are few other points to note, I didn't use the Spring web service. The only jar dependency I had was saaj-impl apart from the spring framework's jars.

Building RESTful web service using Jersey

Jersey is an open source reference implementation of JSR-311. The implementation provides support for annotations defined in JSR-311 and other APIs making it easy for developers to build RESTful web service. In this tutorial we will build a simple Hello World web service using Jersey.

Before we code, let’s have a look at basics.

What is a RESTful web service?

Representational state transfer (REST) is a style of software architecture for distributed hypermedia systems. It’s not a standard but makes use of widely accepted standards like HTTP,HTML, XML and URL.

A client application using REST is viewed as state machine. The client references a Web resource using a URL. A representation of the resource called is returned to the client. It can be HTML, XML, plain text etc.

What is Jersey?

Like I earlier - Jersey is the open source JAX-RS (JSR 311) reference implementation for building RESTful web services. Jersey 1.0.2 implements JAX-RS 1.0 and is shipped with GlassFish server. You can download the jars from Jersey site: https://jersey.dev.java.net/

Building our frist RESTful web service

I have kept our first web service as simple as possible. It would just serve a text “Hello World”! You can grab the source code here. I have used ServletContainer to expose the service. This way you will be able to deploy our service in any servlet container.

In REST, a service is called resource. Jersey provides annotation what make developers job easy and quick. Here is our resource (HelloWorldResource.java):

package rest.resource;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;

@Path("helloworld")
public class HelloWorldResource {
 
 @GET
 @Produces("text/plain")
 public String getMessage() {
  return "Hello World";
 }
}

Remove the annotations and you get a simple POJO. So, in short what we are doing here is adding some annotations to a POJO and deploying it as a service. Let me explain the annotation you see in the above code.

@Path defines a relative URI path for accessing the service. What you see is a very simple path. JAX-RS allows you to embed variables in URI making it path templates.

@GET annotation designates the request method. JAX-RS supports @POST, @PUT, @DELETE and @HEAD along with @GET method.

@Produces annotation is used to specify the MIME types for a resource representation that is sent back to the client. In our case, we are returning a plain text.

We will discuss other annotation is the coming tutorials. With this, we have out first service ready. To deploy this in a servlet container we need to configure web.xml to process requests coming to the server. In web.xml file, we declare a serlvet-class with appropriate parameters as shown below:

<servlet>
<servlet-name>Jersey</servlet-name>
<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
 <init-param>
 <param-name>com.sun.jersey.config.property.packages</param-name>
<param-value>rest.resource</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Jersey</servlet-name>
<url-pattern>/jersey/*</url-pattern>
</servlet-mapping>

Please note that in my servlet-mapping, I have the url-pattern as /jersey/*. This is not the only method to specify REST resources class in web.xml. I will explain other methods in a separate article.You can access our new RESTful service using the URL http://localhost:8080/restweb/jersey/helloworld.