Understanding HTTP Message Converters in Spring Framework

1. Introduction to Message Converters

HTTP Message Converters are used to marshal and unmarshal Java Objects to and from JSON, XML, etc. over HTTP.

Marshalling means producing a stream of byte which contain enough information to be able to re-build the object. Unmarshalling is just the opposite.


With this declaration in the Spring context file, AnnotationDrivenBeanDefinitionParser registers set of conversion services, validators and message-converters.

If no <message-converters> tag are defined in the <mvc:annotation-config> block then Spring registers default set of message converters, namely –

  • ByteArrayHttpMessageConverter
  • StringHttpMessageConverter
  • ResourceHttpMessageConverter
  • SourceHttpMessageConverter
  • AllEncompassingFormHttpMessageConverter

However others like the ones mentioned below are registered only when the respective libraries are present in the classpath –

  • Jaxb2RootElementHttpMessageConverter – To convert Java objects to/from XML
  • MappingJackson2HttpMessageConverter – To convert JSON
  • MappingJacksonHttpMessageConverter – To convert JSON
  • AtomFeedHttpMessageConverter – To convert Atom feeds
  • RssChannelHttpMessageConverter – To convert RSS feeds

Note that, each HttpMessageConverter implementation has one or several associated MIME Types.

2. How do the Message Converters work?

When receiving a new request, Spring will make use of the “Accept” header to determine the media type that it needs to respond with. Spring then tries to find a registered converter that is capable of handling that specific media type – and it will use it to convert the entity and send back the response.

For receiving a request which contains JSON information – the framework will use the “Content-Type” header to determine the media-type in the request body. Spring searches for the appropriate HttpMessageConverter that can convert the body sent by the client to a Java Object.

The below diagram clarifies all –

Wokring of MessageConverters

3. Further digging into the process

@ResponseBody means that the returned value of the method will constitute the body of the HTTP response. Of course, an HTTP response can’t contain Java objects. The processed data on the server is transformed to a format suitable for REST applications, typically JSON or XML.

As discussed above, the “Accept” header specified by the Client will be used to choose the appropriate HTTP Converter to marshal/transform the processed entity to the required format in response.

Now, let’s assume that there is no the “Accept” header, the default attempt that Spring makes is to convert the response to JSON. But what if there is no corresponding MappingJackson2HttpMessageConverter JAR included in the classpath. Yes, you guessed it right, the application throws an exception –

Spring MessageConverters

But if the JAR is present in the classpath, the HTTP Response body contains –

With the above example we inferred that, MappingJackson2HttpMessageConverter is registered only when the respective libraries are present in the classpath. 

@RequestBody is often used as argument in a Controller method. It indicates to Spring that the body of the HTTP Request needs to be deserialized into its corresponding Java entity. As discussed previously, the “Content-Type” header specified by the Client will be used to determine the appropriate converter for this.

For example –

When we consume the service with “Content-Type” as application/json and HTTP request body as JSON data (as mentioned below), the @RequestBody determines the appropriate converter and deserializes the incoming JSON request data into its corresponding Java entity as specified in the controller argument.

4. Using Spring’s RestTemplate with Http Message Converters

Below is how we can retrieve a particular Resource with application/json “Accept” header –

Receive our updates to your inbox

Get more stuff like this
in your inbox

Subscribe to our mailing list and get interesting stuff and updates to your email inbox.