Customizing HttpMessageConverter with Spring MVC in REST

HttpMessageConverter is a strategy interface that specifies a converter that can convert from and to HTTP requests and responses in Spring REST Restful web services. Internally Spring MVC uses it to convert the Http request to an object representation and back. Let's see following code for REST endpoint service.

@RestController
public class AccountController {
  @PostMapping("/account")
  public Account create (@RequestBody Account account){
     return accountService.create(account);
  }
}

Sending Request
Let's see API call for this endpoint. REST client consumes this endpoint with JSON object and we can specify "Content-Type" to be "application/json"

POST /restapi/account/ HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Cache-Control: no-cache

{
"name":"Arnav Rajput",
"city":"Noida",
"balance":4000202.33
}

Getting Response
We get back a 200 OK – a successful response as below:

HTTP/1.1 200 OK
Content-Type ?application/json;charset=UTF-8
Date ?Thu, 30 Mar 2017 12:46:49 GMT
Server ?Apache-Coyote/1.1
Transfer-Encoding ?chunked
{
  "accountId": 1,
  "name": "Arnav Rajput",
  "city": "Noida",
  "balance": 4000202.33
}

Client-Server Communication for this API Endpoint:

• REST Client sends a POST request to /restapi/account/ with the Accept header set to application/json to get all Account resources as Json
• AccountController is hit and returns the corresponding Account Java object as response
• Now Spring Framework then uses one of the Jackson message converters to marshall and unmarshall Java Objects to and from JSON over HTTP.

In this above code we are using @RestController, it is actually combination of @ResponseBody and @Controller as of Spring 4.0, before it we have to specify with handler method as below:

@RequestMapping(value="/account", method=RequestMethod.POST)
public @ResponseBody Account create (@RequestBody Account account){
 return accountService.create(account);
}  

@ResponseBody
In Spring MVC, @ResponseBody annotation on a AccoutnController method indicates to Spring that the return Account object of the method is serialized to JSON directly to the body of the HTTP Response. It uses "Accept" header to choose the appropriate Http Converter to marshall the object.

@RequestBody
In Spring MVC, @RequestBody annotation on the argument of a AccountController method create (@RequestBody Account account) – it indicates to Spring that the body of the HTTP Request (either in JSON or XML) is deserialized to that Account Java Object. It uses "Content-Type" header specified by the REST Client will be used to determine the appropriate converter for this.

Default Message Converters in Spring MVC
In Spring MVC Framework, there is a set of default converters automatically registered which supports a whole range of different resource representation formats - json, xml for object. In RestTemplate in Spring REST, objects passed to and returned from the methods of RestTemplate class like getForObject(), postForLocation(), and put() are converted to HTTP requests and from HTTP responses by registered HttpMessageConverters.

• StringHttpMessageConverter: it converts Strings from the HTTP request and response.
• FormHttpMessageConverter: it converts form data to/from a MultiValueMap<String, String>.
• ByteArrayHttpMessageConverter: it converts byte arrays from the HTTP request and response.
• MappingJackson2HttpMessageConverter: it converts JSON from the HTTP request and response.
• Jaxb2RootElementHttpMessageConverter: it converts Java objects to/from XML.
• SourceHttpMessageConverter: it converts javax.xml.transform.Source from the HTTP request and response.
• AtomFeedHttpMessageConverter: it converts Atom feeds.
• RssChannelHttpMessageConverter: it converts RSS feeds.

Customizing HttpMessageConverters with Spring MVC
Let's see Spring MVC configuration file.

@Configuration
@EnableWebMvc
@ComponentScan("com.doj.restapi.web.controller")
public class WebConfiguration{
 
}

In the above MVC configuration file, we are using @EnableWebMvc annotation, it automatically registered default Http message converters with application as listed above according to available library in the class path. Now, if there is a need to customize the default message converters in some way. Spring provides a WebMvcConfigurerAdapter class, which allow us to change the default list of Http Converters with our own. Now let's below changed configuration class for Spring MVC.

/**
 * 
 */
package com.doj.restapi.web.config;

import java.util.List;

import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.http.converter.xml.MarshallingHttpMessageConverter;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

/**
 * @author Dinesh.Rajput
 *
 */
@Configuration
@EnableWebMvc
@ComponentScan("com.doj.restapi.web.controller")
public class WebConfiguration extends WebMvcConfigurerAdapter{
    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
 converters.add(createXmlHttpMessageConverter());
        converters.add(new MappingJackson2HttpMessageConverter());
        super.configureMessageConverters(converters);
    }
    private HttpMessageConverter<Object> createXmlHttpMessageConverter() {
        MarshallingHttpMessageConverter xmlConverter = new MarshallingHttpMessageConverter();
        XStreamMarshaller xstreamMarshaller = new XStreamMarshaller();
        xmlConverter.setMarshaller(xstreamMarshaller);
        xmlConverter.setUnmarshaller(xstreamMarshaller);
        return xmlConverter;
    }
}

Make sure that XStream library should be in the classpath of application. Here we are creating a new converter, the MarshallingHttpMessageConverter and we are using the Spring XStream support to configure it.

Summary
In this tutorial, we have seen how Spring MVC allows us to specify and fully customize Http Message Converters to automatically marshall/unmarshall Java Entities to and from XML or JSON.