RESTful Clients in Spring 3

We have discussed what REST & RESTful Web Services are and how to create RESTful Web Services in Spring 3. It is the time to talk about how to develop client applications to consume RESTful Services.

 

The main idea of RESTful Services is the ability to generate a representation that the client can understand. The XML format is the most common and popular representation being used. Since XML is a language independent format, we can develop client programs in different computer languages, e.g. Java, .NET, and other languages as long as it can understand and parse the generated XML.

 

In order to consume RESTful services, the client program is required to perform the following two main tasks:

  • HTTP handling - it needs to generate HTTP requests and be able to receive the HTTP responses
  • XML payload - it also needs to generate XML for uploading to the server, and parse the XML response from the server

 

Basically, we can use whatever libraries that we are familiar with to achieve these tasks, e.g. HttpClient and XML4J. However, Spring 3 has already provided some useful classes for this purpose.

 

RestTemplate

The RestTemplate is the core class of Spring framework for client-side access to RESTful Services. By registering a proper HTTP message converter, it is able to inject objects into the HTTP request body, and to convert response back into an object. Spring provides a MarshallingHttpMessageConverter that uses the Object-to-XML framework to achieve the conversion between XML and objects.

 

All we need to do is define it in our application context - something like the following.

  <bean id="restTemplate" class="org.springframework.web.client.RestTemplate">
<property name="messageConverters">
<list>
<bean id="messageConverter"
class="org.springframework.http.converter.xml.MarshallingHttpMessageConverter">
<property name="marshaller" ref="xstreamMarshaller" />
<property name="unmarshaller" ref="xstreamMarshaller" />
</bean>
</list>
</property>
</bean>

 

Marshalling and Unmarshalling XML

Once the MarshallingHttpMessageConverter is defined, we can choose our favourite marshaller and unmarshaller. In my example, I use the XStreamMarshaller, as it was the same marshaller used in my RESTful Services example to convert the Customer class into XML.

  <bean id="xstreamMarshaller" class="org.springframework.oxm.xstream.XStreamMarshaller">
<property name="aliases">
<props>
<prop key="customer">com.spring.controller.Customer</prop>
</props>
</property>
</bean>

 

For the details of all available marshallers, please refer to the Spring document - Marshalling XML using O/X Mappers.

 

Client Code

If everything is in-place, we can simply instantiate a RestTemplate object by calling the getBean method on the application context.

   RestTemplate restTemplate = appContext.getBean("restTemplate", RestTemplate.class);

 

We can then consume any RESTful services using the getForObject method. This method will use the pre-configured marshaller/unmarshaller to convert the response into the actual class, i.e. the Customer class.

    String url = "http://localhost:8080/restful/app/customer/1.xml";
Customer customer = (Customer) restTemplate.getForObject(url, Customer.class);

 

Or we can obtain a list of Customer classes by consuming the "app/customers.xml" service.

    String url = "http://localhost:8080/restful/app/customers.xml";
List<Customer> customers = (List) restTemplate.getForObject(url, List.class);

 

It is very easy to develop your RESTful solution using the Spring 3.0. If you are interested in my sample program, you can download the restful-client.zip file. It is an eclipse project. I have tested it with the RESTful Services mentioned in the RESTful Web Services in Spring 3.