Improve HttpMessageConverters javadoc

[liudaomanbu]

I use the spring-boot-starter-parent 1.5.17.RELEASE.

I create my config extends WebMvcConfigurerAdapter,and overwrite the extendMessageConverters method.

I see the List<HttpMessageConverter<?>> has two MappingJackson2HttpMessageConverters and two StringHttpMessageConverters.

@Configuration
public class TestConfig extends WebMvcConfigurerAdapter {

  @Override
  public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
    System.out.println(converters);
  }
}

I try to register my TestDeserializer to jackson.
But this is only the first one to take effect.
This is the first one.

This is the second one.

I think is maybe a bug?
If it is not a bug,someone can explain?

[liudaomanbu]

I try to debug the reason and found the order of production two MappingJackson2HttpMessageConverters.

Firstly, in org.springframework.boot.autoconfigure.web.JacksonHttpMessageConvertersConfiguration, the mappingJackson2HttpMessageConverter method create a new MappingJackson2HttpMessageConverter and register to Spring container.

@Configuration
class JacksonHttpMessageConvertersConfiguration {

	@Configuration
	@ConditionalOnClass(ObjectMapper.class)
	@ConditionalOnBean(ObjectMapper.class)
	@ConditionalOnProperty(name = HttpMessageConvertersAutoConfiguration.PREFERRED_MAPPER_PROPERTY, havingValue = "jackson", matchIfMissing = true)
	protected static class MappingJackson2HttpMessageConverterConfiguration {

		@Bean
		@ConditionalOnMissingBean(value = MappingJackson2HttpMessageConverter.class, ignoredType = {
				"org.springframework.hateoas.mvc.TypeConstrainedMappingJackson2HttpMessageConverter",
				"org.springframework.data.rest.webmvc.alps.AlpsJsonHttpMessageConverter" })
		public MappingJackson2HttpMessageConverter mappingJackson2HttpMessageConverter(
				ObjectMapper objectMapper) {
			return new MappingJackson2HttpMessageConverter(objectMapper);
		}

	}
//......
}

Secondly, in org.springframework.boot.autoconfigure.web.HttpMessageConvertersAutoConfiguration, the messageConverters method create a HttpMessageConverters object.

@Configuration
@ConditionalOnClass(HttpMessageConverter.class)
@AutoConfigureAfter({ GsonAutoConfiguration.class, JacksonAutoConfiguration.class })
@Import({ JacksonHttpMessageConvertersConfiguration.class,
		GsonHttpMessageConvertersConfiguration.class })
public class HttpMessageConvertersAutoConfiguration {
	//......
	@Bean
	@ConditionalOnMissingBean
	public HttpMessageConverters messageConverters() {
		return new HttpMessageConverters((this.converters != null) ? this.converters
				: Collections.<HttpMessageConverter<?>>emptyList());
	}
	//......
}

And the constructor param this.converters has a StringHttpMessageConverter object and the last MappingJackson2HttpMessageConverter object.

Thirdly, in org.springframework.boot.autoconfigure.web.HttpMessageConverters constructor, excute the getDefaultConverters method get a List that has a new StringHttpMessageConverter object and a new MappingJackson2HttpMessageConverter object.
And the getCombinedConverters not remove the repeated objects.

public class HttpMessageConverters implements Iterable<HttpMessageConverter<?>> {
	public HttpMessageConverters(boolean addDefaultConverters,
			Collection<HttpMessageConverter<?>> converters) {
		List<HttpMessageConverter<?>> combined = getCombinedConverters(converters,
				addDefaultConverters ? getDefaultConverters()
						: Collections.<HttpMessageConverter<?>>emptyList());
		combined = postProcessConverters(combined);
		this.converters = Collections.unmodifiableList(combined);
	}
}

I think the problem may be in this getCombinedConverters method.

	private List<HttpMessageConverter<?>> getCombinedConverters(
			Collection<HttpMessageConverter<?>> converters,
			List<HttpMessageConverter<?>> defaultConverters) {
		List<HttpMessageConverter<?>> combined = new ArrayList<HttpMessageConverter<?>>();
		List<HttpMessageConverter<?>> processing = new ArrayList<HttpMessageConverter<?>>(
				converters);
		for (HttpMessageConverter<?> defaultConverter : defaultConverters) {
			Iterator<HttpMessageConverter<?>> iterator = processing.iterator();
			while (iterator.hasNext()) {
				HttpMessageConverter<?> candidate = iterator.next();
				if (isReplacement(defaultConverter, candidate)) {
					combined.add(candidate);
					iterator.remove();
				}
			}
			combined.add(defaultConverter);
			if (defaultConverter instanceof AllEncompassingFormHttpMessageConverter) {
				configurePartConverters(
						(AllEncompassingFormHttpMessageConverter) defaultConverter,
						converters);
			}
		}
		combined.addAll(0, processing);
		return combined;
	}

This method use the isReplacement method in double cycle to check repeated objects.
But the code don't remove the repeated objects.
For repeated object,the combined first and the exist converter,then add the repeated default converter object.

[liudaomanbu]

demo.zip
This is the problem demo code.

[bclozel]

Hello @liudaomanbu,

I think this is by design, see the HttpMessageConverters javadoc:

/**
 * Create a new {@link HttpMessageConverters} instance with the specified converters.
 * @param addDefaultConverters if default converters should be added
 * @param converters converters to be added. Items are added just before any default
 * converter of the same type (or at the front of the list if no default converter is
 * found) The {@link #postProcessConverters(List)} method can be used for further
 * converter manipulation.
 */

There's even a test for this exact behavior. I'm still marking that for team-attention as I'd like to know if there are things we should improve in this area.

[wilkinsona]

It is indeed by design. See #1293 for details. One thing that we should do is clarify the javadoc on HttpMessageConverters as one constructor is currently misleading:

spring-boot/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/http/HttpMessageConverters.java

Lines 70 to 77 in 228e054

	/**
	* Create a new {@link HttpMessageConverters} instance with the specified additional
	* converters.
	* @param additionalConverters additional converters to be added. New converters will
	* be added to the front of the list, overrides will replace existing items without
	* changing the order. The {@link #getConverters()} methods can be used for further
	* converter manipulation.
	*/

.

[liudaomanbu]

It is indeed by design. See #1293 for details. One thing that we should do is clarify the javadoc on HttpMessageConverters as one constructor is currently misleading:

spring-boot/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/http/HttpMessageConverters.java

Lines 70 to 77 in 228e054

/**

• Create a new {@link HttpMessageConverters} instance with the specified additional
• converters.
• @param additionalConverters additional converters to be added. New converters will
• be added to the front of the list, overrides will replace existing items without
• changing the order. The {@link #getConverters()} methods can be used for further
• converter manipulation.
  */
  .

Thank you for your answer,I think the javadoc on HttpMessageConverters shoule be fixed.
My understanding of it is that after replace,the default converter should be remove.

But I also have question about the design.
When parsing parameters,only first matched HttpMessageConverter can parsing.
Even if the first matched HttpMessageConverter fails, other matched HttpMessageConverters not get the chance to parsing parameters.
So ,I think the same type HttpMessageConverter have multiple objects is meaningless

[liudaomanbu]

Hello @liudaomanbu,

I think this is by design, see the HttpMessageConverters javadoc:

/**
 * Create a new {@link HttpMessageConverters} instance with the specified converters.
 * @param addDefaultConverters if default converters should be added
 * @param converters converters to be added. Items are added just before any default
 * converter of the same type (or at the front of the list if no default converter is
 * found) The {@link #postProcessConverters(List)} method can be used for further
 * converter manipulation.
 */

There's even a test for this exact behavior. I'm still marking that for team-attention as I'd like to know if there are things we should improve in this area.

Thank you for your answer.

[wilkinsona]

Even if the first matched HttpMessageConverter fails, other matched HttpMessageConverters not get the chance to parsing parameters.
So ,I think the same type HttpMessageConverter have multiple objects is meaningless

It's only meaningless if an earlier HttpMessageConverter will always match (return true from canRead or canWrite) and therefore prevent a latter converter from being called. That isn't always the case. Different MappingJackson2HttpMessageConverter instances may be configured with different supported media types or may even be subclassed to implement custom canRead or canWrite behaviour. This need to fall back to the default converters was overlooked originally and is the problem that is described in and fixed by #1293.

[liudaomanbu]

Even if the first matched HttpMessageConverter fails, other matched HttpMessageConverters not get the chance to parsing parameters.
So ,I think the same type HttpMessageConverter have multiple objects is meaningless

It's only meaningless if an earlier HttpMessageConverter will always match (return true from canRead or canWrite) and therefore prevent a latter converter from being called. That isn't always the case. Different MappingJackson2HttpMessageConverter instances may be configured with different supported media types or may even be subclassed to implement custom canRead or canWrite behaviour. This need to fall back to the default converters was overlooked originally and is the problem that is described in and fixed by #1293.

Thanks.