Review HttpMessageConverters semantics in Builder

Prior to this commit, the `HttpMessageConverters` builder API had
methods like "jsonMessageConverter" for configuring a specific converter
for JSON support. This converter would be always configured at a given
position, even if default converters registration is not requested.
On the other hand, `customMessageConverter` would add any converter
ahead of the list, in all cases. This difference was not conveyed as it
should by the API.

This commit makes the following changes:

* builder methods are renamed to `withJsonConverter` and variants, to
  better convey the fact that those are replacing the default converter
  for a given format.
* `customMessageConverter` is renamed to `addCustomConverter` to better
  reflect the additive aspect.
* the JavaDoc has been updated accordingly
* `withJsonConverter` and others are now only effective if the default
  registration of auto-detected converters is requested. This better
  aligns with the behavior in the reactive codecs configuration

Closes gh-35704

Author: bclozel

framework-docs/src/main/java/org/springframework/docs/web/webmvc/mvcconfig/mvcconfigmessageconverters/WebConfiguration.java

@@ -44,8 +44,8 @@ public void configureMessageConverters(HttpMessageConverters.ServerBuilder build
 				.findAndAddModules()
 				.defaultUseWrapper(false)
 				.build();
-		builder.jsonMessageConverter(new JacksonJsonHttpMessageConverter(jsonMapper))
-				.xmlMessageConverter(new JacksonXmlHttpMessageConverter(xmlMapper));
+		builder.withJsonConverter(new JacksonJsonHttpMessageConverter(jsonMapper))
+				.withXmlConverter(new JacksonXmlHttpMessageConverter(xmlMapper));
 	}
 }
 // end::snippet[]

framework-docs/src/main/kotlin/org/springframework/docs/web/webmvc/mvcconfig/mvcconfigmessageconverters/WebConfiguration.kt

@@ -26,8 +26,8 @@ class WebConfiguration : WebMvcConfigurer {
 			.findAndAddModules()
 			.defaultUseWrapper(false)
 			.build()
-		builder.jsonMessageConverter(JacksonJsonHttpMessageConverter(jsonMapper))
-			.xmlMessageConverter(JacksonXmlHttpMessageConverter(xmlMapper))
+		builder.withJsonConverter(JacksonJsonHttpMessageConverter(jsonMapper))
+			.withXmlConverter(JacksonXmlHttpMessageConverter(xmlMapper))
 	}
 }
 // end::snippet[]

spring-web/src/main/java/org/springframework/http/converter/DefaultHttpMessageConverters.java

@@ -338,43 +338,43 @@ public DefaultClientBuilder registerDefaults() {
 		}
 
 		@Override
-		public ClientBuilder stringMessageConverter(HttpMessageConverter<?> stringMessageConverter) {
+		public ClientBuilder withStringConverter(HttpMessageConverter<?> stringMessageConverter) {
 			setStringMessageConverter(stringMessageConverter);
 			return this;
 		}
 
 		@Override
-		public ClientBuilder jsonMessageConverter(HttpMessageConverter<?> jsonMessageConverter) {
+		public ClientBuilder withJsonConverter(HttpMessageConverter<?> jsonMessageConverter) {
 			setJsonMessageConverter(jsonMessageConverter);
 			return this;
 		}
 
 		@Override
-		public ClientBuilder xmlMessageConverter(HttpMessageConverter<?> xmlMessageConverter) {
+		public ClientBuilder withXmlConverter(HttpMessageConverter<?> xmlMessageConverter) {
 			setXmlMessageConverter(xmlMessageConverter);
 			return this;
 		}
 
 		@Override
-		public ClientBuilder smileMessageConverter(HttpMessageConverter<?> smileMessageConverter) {
+		public ClientBuilder withSmileConverter(HttpMessageConverter<?> smileMessageConverter) {
 			setSmileMessageConverter(smileMessageConverter);
 			return this;
 		}
 
 		@Override
-		public ClientBuilder cborMessageConverter(HttpMessageConverter<?> cborMessageConverter) {
+		public ClientBuilder withCborConverter(HttpMessageConverter<?> cborMessageConverter) {
 			setCborMessageConverter(cborMessageConverter);
 			return this;
 		}
 
 		@Override
-		public ClientBuilder yamlMessageConverter(HttpMessageConverter<?> yamlMessageConverter) {
+		public ClientBuilder withYamlConverter(HttpMessageConverter<?> yamlMessageConverter) {
 			setYamlMessageConverter(yamlMessageConverter);
 			return this;
 		}
 
 		@Override
-		public ClientBuilder customMessageConverter(HttpMessageConverter<?> customConverter) {
+		public ClientBuilder addCustomConverter(HttpMessageConverter<?> customConverter) {
 			addCustomMessageConverter(customConverter);
 			return this;
 		}
@@ -391,20 +391,21 @@ public HttpMessageConverters build() {
 				this.resourceMessageConverter = new ResourceHttpMessageConverter(false);
 				detectMessageConverters();
 			}
-			List<HttpMessageConverter<?>> allConverters = new ArrayList<>();
-			List<HttpMessageConverter<?>> partConverters = new ArrayList<>();
-			partConverters.addAll(this.getCustomConverters());
-			partConverters.addAll(this.getCoreConverters());
-
-			allConverters.addAll(this.getCustomConverters());
-			allConverters.addAll(this.getBaseConverters());
-			if (this.resourceMessageConverter != null) {
-				allConverters.add(this.resourceMessageConverter);
+			List<HttpMessageConverter<?>> partConverters = new ArrayList<>(this.getCustomConverters());
+			List<HttpMessageConverter<?>> allConverters = new ArrayList<>(this.getCustomConverters());
+			if (this.registerDefaults) {
+				partConverters.addAll(this.getCoreConverters());
+				allConverters.addAll(this.getBaseConverters());
+				if (this.resourceMessageConverter != null) {
+					allConverters.add(this.resourceMessageConverter);
+				}
 			}
 			if (!partConverters.isEmpty() || !allConverters.isEmpty()) {
 				allConverters.add(new AllEncompassingFormHttpMessageConverter(partConverters));
 			}
-			allConverters.addAll(this.getCoreConverters());
+			if (this.registerDefaults) {
+				allConverters.addAll(this.getCoreConverters());
+			}
 			if (this.configurer != null) {
 				allConverters.forEach(this.configurer);
 			}
@@ -422,43 +423,43 @@ public ServerBuilder registerDefaults() {
 		}
 
 		@Override
-		public ServerBuilder stringMessageConverter(HttpMessageConverter<?> stringMessageConverter) {
+		public ServerBuilder withStringConverter(HttpMessageConverter<?> stringMessageConverter) {
 			setStringMessageConverter(stringMessageConverter);
 			return this;
 		}
 
 		@Override
-		public ServerBuilder jsonMessageConverter(HttpMessageConverter<?> jsonMessageConverter) {
+		public ServerBuilder withJsonConverter(HttpMessageConverter<?> jsonMessageConverter) {
 			setJsonMessageConverter(jsonMessageConverter);
 			return this;
 		}
 
 		@Override
-		public ServerBuilder xmlMessageConverter(HttpMessageConverter<?> xmlMessageConverter) {
+		public ServerBuilder withXmlConverter(HttpMessageConverter<?> xmlMessageConverter) {
 			setXmlMessageConverter(xmlMessageConverter);
 			return this;
 		}
 
 		@Override
-		public ServerBuilder smileMessageConverter(HttpMessageConverter<?> smileMessageConverter) {
+		public ServerBuilder withSmileConverter(HttpMessageConverter<?> smileMessageConverter) {
 			setSmileMessageConverter(smileMessageConverter);
 			return this;
 		}
 
 		@Override
-		public ServerBuilder cborMessageConverter(HttpMessageConverter<?> cborMessageConverter) {
+		public ServerBuilder withCborConverter(HttpMessageConverter<?> cborMessageConverter) {
 			setCborMessageConverter(cborMessageConverter);
 			return this;
 		}
 
 		@Override
-		public ServerBuilder yamlMessageConverter(HttpMessageConverter<?> yamlMessageConverter) {
+		public ServerBuilder withYamlConverter(HttpMessageConverter<?> yamlMessageConverter) {
 			setYamlMessageConverter(yamlMessageConverter);
 			return this;
 		}
 
 		@Override
-		public ServerBuilder customMessageConverter(HttpMessageConverter<?> customConverter) {
+		public ServerBuilder addCustomConverter(HttpMessageConverter<?> customConverter) {
 			addCustomMessageConverter(customConverter);
 			return this;
 		}
@@ -476,24 +477,24 @@ public HttpMessageConverters build() {
 				this.resourceRegionMessageConverter = new ResourceRegionHttpMessageConverter();
 				detectMessageConverters();
 			}
-			List<HttpMessageConverter<?>> allConverters = new ArrayList<>();
-			List<HttpMessageConverter<?>> partConverters = new ArrayList<>();
-
-			partConverters.addAll(this.getCustomConverters());
-			partConverters.addAll(this.getCoreConverters());
-
-			allConverters.addAll(this.getCustomConverters());
-			allConverters.addAll(this.getBaseConverters());
-			if (this.resourceMessageConverter != null) {
-				allConverters.add(this.resourceMessageConverter);
-			}
-			if (this.resourceRegionMessageConverter != null) {
-				allConverters.add(this.resourceRegionMessageConverter);
+			List<HttpMessageConverter<?>> partConverters = new ArrayList<>(this.getCustomConverters());
+			List<HttpMessageConverter<?>> allConverters = new ArrayList<>(this.getCustomConverters());
+			if (this.registerDefaults) {
+				partConverters.addAll(this.getCoreConverters());
+				allConverters.addAll(this.getBaseConverters());
+				if (this.resourceMessageConverter != null) {
+					allConverters.add(this.resourceMessageConverter);
+				}
+				if (this.resourceRegionMessageConverter != null) {
+					allConverters.add(this.resourceRegionMessageConverter);
+				}
 			}
 			if (!partConverters.isEmpty() || !allConverters.isEmpty()) {
 				allConverters.add(new AllEncompassingFormHttpMessageConverter(partConverters));
 			}
-			allConverters.addAll(this.getCoreConverters());
+			if (this.registerDefaults) {
+				allConverters.addAll(this.getCoreConverters());
+			}
 			if (this.configurer != null) {
 				allConverters.forEach(this.configurer);
 			}

spring-web/src/main/java/org/springframework/http/converter/HttpMessageConverters.java

@@ -21,8 +21,10 @@
 /**
  * Utility for building and configuring an immutable collection of {@link HttpMessageConverter}
  * instances for {@link #forClient() client} or {@link #forServer() server} usage. You can
- * ask to {@link Builder#registerDefaults() register default converters with classpath detection},
- * add custom converters and post-process configured converters.
+ * ask to {@link Builder#registerDefaults() register default converters with classpath detection}
+ * and {@link Builder#withJsonConverter(HttpMessageConverter) override specific converters} that were detected.
+ * Custom converters can be independently added in front of default ones.
+ * Finally, {@link Builder#configureMessageConverters(Consumer) default and custom converters can be configured}.
  *
  * @author Brian Clozel
  * @since 7.0
@@ -79,7 +81,7 @@ interface Builder<T extends Builder<T>> {
 
 		/**
 		 * Register default converters using classpath detection.
-		 * Manual registrations like {@link #jsonMessageConverter(HttpMessageConverter)} will
+		 * Manual registrations like {@link #withJsonConverter(HttpMessageConverter)} will
 		 * override auto-detected ones.
 		 */
 		T registerDefaults();
@@ -90,53 +92,53 @@ interface Builder<T extends Builder<T>> {
 		 * @param stringMessageConverter the converter instance to use
 		 * @see StringHttpMessageConverter
 		 */
-		T stringMessageConverter(HttpMessageConverter<?> stringMessageConverter);
+		T withStringConverter(HttpMessageConverter<?> stringMessageConverter);
 
 		/**
 		 * Override the default Jackson 3.x JSON {@code HttpMessageConverter}
 		 * with any converter supporting the JSON format.
 		 * @param jsonMessageConverter the converter instance to use
 		 * @see org.springframework.http.converter.json.JacksonJsonHttpMessageConverter
 		 */
-		T jsonMessageConverter(HttpMessageConverter<?> jsonMessageConverter);
+		T withJsonConverter(HttpMessageConverter<?> jsonMessageConverter);
 
 		/**
 		 * Override the default Jackson 3.x XML {@code HttpMessageConverter}
 		 * with any converter supporting the XML format.
 		 * @param xmlMessageConverter the converter instance to use
 		 * @see org.springframework.http.converter.xml.JacksonXmlHttpMessageConverter
 		 */
-		T xmlMessageConverter(HttpMessageConverter<?> xmlMessageConverter);
+		T withXmlConverter(HttpMessageConverter<?> xmlMessageConverter);
 
 		/**
 		 * Override the default Jackson 3.x Smile {@code HttpMessageConverter}
 		 * with any converter supporting the Smile format.
 		 * @param smileMessageConverter the converter instance to use
 		 * @see org.springframework.http.converter.smile.JacksonSmileHttpMessageConverter
 		 */
-		T smileMessageConverter(HttpMessageConverter<?> smileMessageConverter);
+		T withSmileConverter(HttpMessageConverter<?> smileMessageConverter);
 
 		/**
 		 * Override the default Jackson 3.x CBOR {@code HttpMessageConverter}
 		 * with any converter supporting the CBOR format.
 		 * @param cborMessageConverter the converter instance to use
 		 * @see org.springframework.http.converter.cbor.JacksonCborHttpMessageConverter
 		 */
-		T cborMessageConverter(HttpMessageConverter<?> cborMessageConverter);
+		T withCborConverter(HttpMessageConverter<?> cborMessageConverter);
 
 		/**
 		 * Override the default Jackson 3.x Yaml {@code HttpMessageConverter}
 		 * with any converter supporting the Yaml format.
 		 * @param yamlMessageConverter the converter instance to use
 		 * @see org.springframework.http.converter.yaml.JacksonYamlHttpMessageConverter
 		 */
-		T yamlMessageConverter(HttpMessageConverter<?> yamlMessageConverter);
+		T withYamlConverter(HttpMessageConverter<?> yamlMessageConverter);
 
 		/**
-		 * Add a custom {@code HttpMessageConverter} to the list of converters.
+		 * Add a custom {@code HttpMessageConverter} to the list of converters, ahead of the default converters.
 		 * @param customConverter the converter instance to add
 		 */
-		T customMessageConverter(HttpMessageConverter<?> customConverter);
+		T addCustomConverter(HttpMessageConverter<?> customConverter);
 
 		/**
 		 * Add a consumer for configuring the selected message converters.

spring-web/src/main/java/org/springframework/web/client/DefaultRestClientBuilder.java

@@ -498,7 +498,7 @@ private List<HttpMessageConverter<?>> initMessageConverters() {
 		}
 		else {
 			if (this.messageConverters != null) {
-				this.messageConverters.forEach(builder::customMessageConverter);
+				this.messageConverters.forEach(builder::addCustomConverter);
 			}
 			if (this.convertersConfigurer != null) {
 				this.convertersConfigurer.accept(builder);