From 12937680b7b68fb03119945dbd95e1f97f763bc8 Mon Sep 17 00:00:00 2001 From: Sebastien Deleuze Date: Mon, 31 Aug 2015 21:48:15 +0200 Subject: [PATCH] Add a section about message converters customization in the refdoc Issue: SPR-13411 --- src/asciidoc/web-mvc.adoc | 98 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) diff --git a/src/asciidoc/web-mvc.adoc b/src/asciidoc/web-mvc.adoc index f781d38da5..3b7be8bd04 100644 --- a/src/asciidoc/web-mvc.adoc +++ b/src/asciidoc/web-mvc.adoc @@ -4566,6 +4566,28 @@ classpath. .. `RssChannelHttpMessageConverter` converts RSS feeds -- added if Rome is present on the classpath. +See <> for more information about how to customize these +default converters. + +[NOTE] +==== +Jackson JSON and XML converters are created using `ObjectMapper` instances created by +{javadoc-baseurl}/org/springframework/http/converter/json/Jackson2ObjectMapperBuilder.html[`Jackson2ObjectMapperBuilder`] +in order to provide a better default configuration. + +This builder customizes Jackson's default properties with the following ones: + +. http://fasterxml.github.io/jackson-databind/javadoc/2.6/com/fasterxml/jackson/databind/DeserializationFeature.html#FAIL_ON_UNKNOWN_PROPERTIES[`DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES`] is disabled. +. http://fasterxml.github.io/jackson-databind/javadoc/2.6/com/fasterxml/jackson/databind/MapperFeature.html#DEFAULT_VIEW_INCLUSION[`MapperFeature.DEFAULT_VIEW_INCLUSION`] is disabled. + +It also automatically registers the following well-known modules if they are detected on the classpath: + +. https://github.com/FasterXML/jackson-datatype-jdk7[jackson-datatype-jdk7]: support for Java 7 types like `java.nio.file.Path`. +. https://github.com/FasterXML/jackson-datatype-joda[jackson-datatype-joda]: support for Joda-Time types. +. https://github.com/FasterXML/jackson-datatype-jsr310[jackson-datatype-jsr310]: support for Java 8 Date & Time API types. +. https://github.com/FasterXML/jackson-datatype-jdk8[jackson-datatype-jdk8]: support for other Java 8 types like `Optional`. +==== + [[mvc-config-customize]] @@ -5299,6 +5321,82 @@ And the same in XML, use the `` element: +[[mvc-config-message-converters]] +=== Message Converters + +Customization of `HttpMessageConverter` can be achieved in Java config by overriding +{javadoc-baseurl}/org/springframework/web/servlet/config/annotation/WebMvcConfigurerAdapter.html#configureMessageConverters-java.util.List-[`configureMessageConverters()`] +if you want to replace the default converters created by Spring MVC, or by overriding +{javadoc-baseurl}/org/springframework/web/servlet/config/annotation/WebMvcConfigurerAdapter.html#extendMessageConverters-java.util.List-[`extendMessageConverters()`] +if you just want to customize them or add additional converters to the default ones. + +Below is an example that adds Jackson JSON and XML converters with a customized +`ObjectMapper` instead of default ones: + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- + @Configuration + @EnableWebMvc + public class WebConfiguration extends WebMvcConfigurerAdapter { + + @Override + public void configureMessageConverters(List> converters) { + Jackson2ObjectMapperBuilder builder = new Jackson2ObjectMapperBuilder() + .indentOutput(true) + .dateFormat(new SimpleDateFormat("yyyy-MM-dd")) + .modulesToInstall(new ParameterNamesModule()); + converters.add(new MappingJackson2HttpMessageConverter(builder.build())); + converters.add(new MappingJackson2XmlHttpMessageConverter(builder.xml().build())); + } + + } +---- + +In this example, `Jackson2ObjectMapperBuilder` is used to create a common configuration for +both `MappingJackson2HttpMessageConverter` and `MappingJackson2XmlHttpMessageConverter` with +indentation enabled, a customized date format and the registration of +https://github.com/FasterXML/jackson-module-parameter-names[jackson-module-parameter-names] +that adds support for accessing parameter names (feature added in Java 8). + +[NOTE] +==== +Enabling indentation with Jackson XML support requires +http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.codehaus.woodstox%22%20AND%20a%3A%22woodstox-core-asl%22[`woodstox-core-asl`] +dependency in addition to http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22jackson-dataformat-xml%22[`jackson-dataformat-xml`] one. +==== + +Other interesting Jackson modules are available: + +. https://github.com/zalando/jackson-datatype-money[jackson-datatype-money]: support for `javax.money` types (unofficial module) +. https://github.com/FasterXML/jackson-datatype-hibernate[jackson-datatype-hibernate]: support for Hibernate specific types and properties (including lazy-loading aspects) + +It is also possible to do the same in XML: + +[source,xml,indent=0] +[subs="verbatim,quotes"] +---- + + + + + + + + + + + + + + +---- + + + [[mvc-config-advanced-java]] === Advanced Customizations with MVC Java Config As you can see from the above examples, MVC Java config and the MVC namespace provide