Configure gson in spring using GsonHttpMessageConverter

Jackson has been the default json library in springframework until version 4.1 where it added support to use Gson by configuring GsonHttpMessageConverter. Let's take a look at how to configure your spring application to use Google Gson library's Gson class.

Detailed Video Notes

Gson is a java based library that converts java objects into their JSON representation and vice versa. A common example is when you are create a REST end point via a spring @Controller where you fetch a list of objects that you want to convert into an jsonarray. Let's examine a few different configuration options within your spring boot, java config and xml based applications.

Getting started

[0:21]

Before we get started it is important to understand how spring converts objects to json. In typical spring mvc once request exits the @Controller it looks for a view to render. When specifying a @RequestBody or a @RestController we ask spring to by pass this step and write the java objects in the model directly to the response. When doing so spring will look specifically for a HttpMessageConverter associated to the mime type to perform the conversion and in our case Json. Spring configures MappingJackson2HttpMessageConverter by default so we want to swap it with GsonHttpMessageConverter so it uses Gson to convert the java objects.

For our first snippet, lets generate a spring boot application from spring initializr web page and import it into eclipse.

Configuring gson in spring boot

[1:1]

Adding gson to classpath

If you are setting up Gson to work with spring boot you will first want to look at HttpMessageConvertersAutoConfiguration as there may be configuration changes. As it exists during the write up of this tutorial the GsonHttpMessageConverter will be created if Gson is on your classpath, the application doesn't contain jackson's JsonGenerator class and if the Gson bean doesn't exist already.

@Configuration
@ConditionalOnClass(Gson.class)
@ConditionalOnMissingClass(name = "com.fasterxml.jackson.core.JsonGenerator")
@ConditionalOnBean(Gson.class)
protected static class GsonHttpMessageConverterConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public GsonHttpMessageConverter gsonHttpMessageConverter(Gson gson) {
        GsonHttpMessageConverter converter = new GsonHttpMessageConverter();
        converter.setGson(gson);
        return converter;
    }

}
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.3.1</version>
</dependency>

Excluding jackson from classpath

[1:29]

If you want to be sure that jackson isn't used or if you are experiencing conflicts you can add @EnableAutoConfiguration(exclude = { JacksonAutoConfiguration.class }) to your application class and exclude it from the spring-boot-starter-web dependency.

@SpringBootApplication
@EnableAutoConfiguration(exclude = { JacksonAutoConfiguration.class })
public class Application {
    
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
        <exclusions>
        <exclusion>
            <artifactId>jackson-databind</artifactId>
            <groupId>com.fasterxml.jackson.core</groupId>
        </exclusion>
    </exclusions>
</dependency>

If you are trying to eliminate the dependency on jackson we did notice as we worked through this tutorial that it was needed if you are using spring boot actuator specifically in EndpointAutoConfiguration class and it is a reported github issue.

Exception in thread "main" org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'configurationPropertiesReportEndpoint' defined in class path resource [org/springframework/boot/actuate/autoconfigure/EndpointAutoConfiguration.class]: Bean instantiation via factory method failed; nested exception is org.springframework.beans.BeanInstantiationException: Failed to instantiate [org.springframework.boot.actuate.endpoint.ConfigurationPropertiesReportEndpoint]: Factory method 'configurationPropertiesReportEndpoint' threw exception; nested exception is java.lang.NoClassDefFoundError: com/fasterxml/jackson/databind/ser/BeanSerializerModifier

Validate request

Let's create a controller that returns a hashmap to validate that GsonHttpMessageConverter is being used. We will modify our application.properties to include logging.level.org.springframework=DEBUG and make a request to / default request mapping. Inspecting the log we can see that the GsonHttpMessageConverter is being used.

@RestController
public class MyController {
    
    @RequestMapping(value = "/", 
            produces = { MediaType.APPLICATION_JSON_VALUE }, 
            method = RequestMethod.GET)
    public ResponseEntity<Map<String, String>> getContacts() {

        Map<String, String> dummyData = new HashMap<>();

        dummyData.put("java-examples",
                "http://www.leveluplunch.com/java/examples/");
        dummyData.put("groovy-examples",
                "http://www.leveluplunch.com/groovy/examples/");

        return new ResponseEntity<Map<String, String>>(dummyData, HttpStatus.OK);
    }
}
2015-01-18 07:33:51.673 DEBUG 18971 --- [nio-8080-exec-6] o.s.w.s.m.m.a.HttpEntityMethodProcessor  : Written [{java-examples=http://www.leveluplunch.com/java/examples/, groovy-examples=http://www.leveluplunch.com/groovy/examples/}] as "application/json" using [org.springframework.http.converter.json.GsonHttpMessageConverter@469047b8]

Customize converters using HttpMessageConverters

[2:14]

If you are having troubles with configuration just discussed or interested in customizing an existing converter by overriding a bean, spring-boot provides an alternative configuration option. This method will also allow you to have both gson and jackson on your class path. We will create a CustomConfiguration class but this could be performed in any class that contains the @Configuration annotation and create a new bean of type HttpMessageConverters. In our configuration we will instruct springframework to use the default HttpMessageConverter and then append GsonHttpMessageConverter.

@Configuration
public class CustomConfiguration {

    @Bean
    public HttpMessageConverters customConverters() {
        
        Collection<HttpMessageConverter<?>> messageConverters = new ArrayList<>();
        
        GsonHttpMessageConverter gsonHttpMessageConverter = new GsonHttpMessageConverter();
        messageConverters.add(gsonHttpMessageConverter);
        
        return new HttpMessageConverters(true, messageConverters);
    }
}

If we include the gson pom dependency and specify the customConverters it will configure GsonHttpMessageConverter to be used. Now you might be asking, if the jackson is also included on the classpath, how does this work? The default behavior of HttpMessageConverters when adding a new converter is to add it to the front of the list so since jackson is configured before it works.

Using java config

[3:7]

If you haven't moved to spring boot yet you still configure gson within your application using javaconfig by extending WebMvcConfigurerAdapter or if you need more control use WebMvcConfigurationSupport. You can read more on on how to customize the provided spring mvc configuration.

@Configuration
@EnableWebMvc
public class Application extends WebMvcConfigurerAdapter {

    @Override
    public void configureMessageConverters(List<HttpMessageConverter < ? >> converters) {
        GsonHttpMessageConverter gsonHttpMessageConverter = new GsonHttpMessageConverter();
        converters.add(gsonHttpMessageConverter);
    }
}

Configure Gson using XML configuration

[3:26]

I didn't add a specific test scenario for configuring gson in a xml based application but it would look something similar to the following:

<bean class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter">
    <property name="messageConverters">
        <list>
            <bean class="org.springframework.http.converter.json.GsonHttpMessageConverter"/>
        </list>
    </property>
</bean>

There has been a lot of debates on which java library is the fastest JSON processor and many of them might loose out to java 8 json api once support broadens. So until then pick a method and library above.

Thanks for joining in today's level up, have a great day!