Polish

Author: rstoyanchev

spring-web-reactive/src/main/java/org/springframework/web/reactive/config/DelegatingWebReactiveConfiguration.java

@@ -51,8 +51,8 @@ public void setConfigurers(List<WebReactiveConfigurer> configurers) {
 	}
 
 	@Override
-	protected void configureRequestedContentTypeResolver(RequestedContentTypeResolverBuilder builder) {
-		this.configurers.configureRequestedContentTypeResolver(builder);
+	protected void configureContentTypeResolver(RequestedContentTypeResolverBuilder builder) {
+		this.configurers.configureContentTypeResolver(builder);
 	}
 
 	@Override

spring-web-reactive/src/main/java/org/springframework/web/reactive/config/EnableWebReactive.java

@@ -31,19 +31,19 @@
  * <pre class="code">
  * &#064;Configuration
  * &#064;EnableWebReactive
- * &#064;ComponentScan(basePackageClasses = { MyConfiguration.class })
- * public class MyWebConfiguration {
+ * &#064;ComponentScan(basePackageClasses = MyConfiguration.class)
+ * public class MyConfiguration {
  *
  * }
  * </pre>
  *
- * <p>To customize the imported configuration, implement the interface
- * {@link WebReactiveConfigurer} and override individual methods, e.g.:
+ * <p>To customize the imported configuration implement
+ * {@link WebReactiveConfigurer} and override individual methods as shown below:
  *
  * <pre class="code">
  * &#064;Configuration
- * &#064;EnableWebMvc
- * &#064;ComponentScan(basePackageClasses = { MyConfiguration.class })
+ * &#064;EnableWebReactive
+ * &#064;ComponentScan(basePackageClasses = MyConfiguration.class)
  * public class MyConfiguration implements WebReactiveConfigurer {
  *
  * 	   &#064;Override
@@ -56,17 +56,23 @@
  *         messageWriters.add(new MyHttpMessageWriter());
  * 	   }
  *
- *     // More overridden methods ...
  * }
  * </pre>
  *
- * <p>If {@link WebReactiveConfigurer} does not expose some advanced setting that
- * needs to be configured, consider removing the {@code @EnableWebReactive}
+ * <p><strong>Note:</strong> only one {@code @Configuration} class may have the
+ * {@code @EnableWebReactive} annotation to import the Spring Web Reactive
+ * configuration. There can however be multiple {@code @Configuration} classes
+ * implementing {@code WebReactiveConfigurer} in order to customize the provided
+ * configuration.
+ *
+ * <p>If {@link WebReactiveConfigurer} does not expose some more advanced setting
+ * that needs to be configured consider removing the {@code @EnableWebReactive}
  * annotation and extending directly from {@link WebReactiveConfigurationSupport}
  * or {@link DelegatingWebReactiveConfiguration} if you still want to allow
  * {@link WebReactiveConfigurer} instances to customize the configuration.
  *
  * @author Brian Clozel
+ * @author Rossen Stoyanchev
  * @since 5.0
  * @see WebReactiveConfigurer
  * @see WebReactiveConfigurationSupport

spring-web-reactive/src/main/java/org/springframework/web/reactive/config/WebReactiveConfigurationSupport.java

@@ -167,7 +167,7 @@ protected RequestMappingHandlerMapping createRequestMappingHandlerMapping() {
 	public CompositeContentTypeResolver webReactiveContentTypeResolver() {
 		RequestedContentTypeResolverBuilder builder = new RequestedContentTypeResolverBuilder();
 		builder.mediaTypes(getDefaultMediaTypeMappings());
-		configureRequestedContentTypeResolver(builder);
+		configureContentTypeResolver(builder);
 		return builder.build();
 	}
 
@@ -186,7 +186,7 @@ protected Map<String, MediaType> getDefaultMediaTypeMappings() {
 	/**
 	 * Override to configure how the requested content type is resolved.
 	 */
-	protected void configureRequestedContentTypeResolver(RequestedContentTypeResolverBuilder builder) {
+	protected void configureContentTypeResolver(RequestedContentTypeResolverBuilder builder) {
 	}
 
 	/**
@@ -319,7 +319,9 @@ protected void configureMessageReaders(List<HttpMessageReader<?>> messageReaders
 
 	/**
 	 * Adds default converters that sub-classes can call from
-	 * {@link #configureMessageReaders(List)}.
+	 * {@link #configureMessageReaders(List)} for {@code byte[]},
+	 * {@code ByteBuffer}, {@code String}, {@code Resource}, JAXB2, and Jackson
+	 * (if present on the classpath).
 	 */
 	protected final void addDefaultHttpMessageReaders(List<HttpMessageReader<?>> readers) {
 		readers.add(new DecoderHttpMessageReader<>(new ByteArrayDecoder()));

spring-web-reactive/src/main/java/org/springframework/web/reactive/config/WebReactiveConfigurer.java

@@ -41,18 +41,20 @@
  * overriding the relevant methods for your needs.
  *
  * @author Brian Clozel
+ * @author Rossen Stoyanchev
  * @since 5.0
  */
 public interface WebReactiveConfigurer {
 
 	/**
-	 * Configure how the requested content type is resolved.
+	 * Configure how the content type requested for the response is resolved.
 	 * <p>The given builder will create a composite of multiple
-	 * {@link RequestedContentTypeResolver}s, each defining a way to resolve the
-	 * the requested content type (accept HTTP header, path extension, parameter, etc).
-	 * @param builder factory that creates a {@link CompositeContentTypeResolver} instance
+	 * {@link RequestedContentTypeResolver}s, each defining a way to resolve
+	 * the the requested content type (accept HTTP header, path extension,
+	 * parameter, etc).
+	 * @param builder factory that creates a {@link CompositeContentTypeResolver}
 	 */
-	default void configureRequestedContentTypeResolver(RequestedContentTypeResolverBuilder builder) {
+	default void configureContentTypeResolver(RequestedContentTypeResolverBuilder builder) {
 	}
 
 	/**
@@ -79,71 +81,84 @@ default void addResourceHandlers(ResourceHandlerRegistry registry) {
 	}
 
 	/**
-	 * Provide custom argument resolvers without overriding the built-in ones.
-	 * @param resolvers a list of resolvers to add to the built-in ones
+	 * Provide custom controller method argument resolvers. Such resolvers do
+	 * not override and will be invoked after the built-in ones.
+	 * @param resolvers a list of resolvers to add
 	 */
 	default void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
 	}
 
 	/**
-	 * Configure the message readers to use for decoding controller method arguments.
-	 * <p>If no message readers are specified, default readers will be added via
+	 * Configure the message readers to use for decoding the request body where
+	 * {@code @RequestBody} and {@code HttpEntity} controller method arguments
+	 * are used. If none are specified, default ones are added based on
 	 * {@link WebReactiveConfigurationSupport#addDefaultHttpMessageReaders}.
-	 * @param readers a list to add message readers to, initially an empty list
+	 * <p>See {@link #extendMessageReaders(List)} for adding readers
+	 * in addition to the default ones.
+	 * @param readers an empty list to add message readers to
 	 */
 	default void configureMessageReaders(List<HttpMessageReader<?>> readers) {
 	}
 
 	/**
-	 * Modify the list of message readers to use for decoding controller method arguments,
-	 * for example to add some in addition to the ones already configured.
+	 * An alternative to {@link #configureMessageReaders(List)} that allows
+	 * modifying the message readers to use after default ones have been added.
 	 */
 	default void extendMessageReaders(List<HttpMessageReader<?>> readers) {
 	}
 
 	/**
-	 * Add custom {@link Converter}s and {@link Formatter}s.
+	 * Add custom {@link Converter}s and {@link Formatter}s for performing type
+	 * conversion and formatting of controller method arguments.
 	 */
 	default void addFormatters(FormatterRegistry registry) {
 	}
 
 	/**
-	 * Provide a custom {@link Validator}, instead of the instance configured by default.
-	 * <p>Only a single instance is allowed, an error will be thrown if multiple
-	 * {@code Validator}s are returned by {@code WebReactiveConfigurer}s.
-	 * The default implementation returns {@code Optional.empty()}.
+	 * Provide a custom {@link Validator}.
+	 * <p>By default a validator for standard bean validation is created if
+	 * bean validation api is present on the classpath.
 	 */
 	default Optional<Validator> getValidator() {
 		return Optional.empty();
 	}
 
 	/**
-	 * Provide a custom {@link MessageCodesResolver}, instead of using the one
-	 * provided by {@link org.springframework.validation.DataBinder} instances.
-	 * The default implementation returns {@code Optional.empty()}.
+	 * Provide a custom {@link MessageCodesResolver} to use for data binding
+	 * instead of the one created by default in
+	 * {@link org.springframework.validation.DataBinder}.
 	 */
 	default Optional<MessageCodesResolver> getMessageCodesResolver() {
 		return Optional.empty();
 	}
 
 	/**
-	 * Configure the message writers to use for encoding return values.
-	 * <p>If no message writers are specified, default writers will be added via
+	 * Configure the message writers to use to encode the response body based on
+	 * the return values of {@code @ResponseBody}, and {@code ResponseEntity}
+	 * controller methods. If none are specified, default ones are added based on
 	 * {@link WebReactiveConfigurationSupport#addDefaultHttpMessageWriters(List)}.
-	 * @param writers a list to add message writers to, initially an empty list
+	 * <p>See {@link #extendMessageWriters(List)} for adding writers
+	 * in addition to the default ones.
+	 * @param writers a empty list to add message writers to
 	 */
 	default void configureMessageWriters(List<HttpMessageWriter<?>> writers) {
 	}
 
 	/**
-	 * Modify the list of message writers to use for encoding return values,
-	 * for example to add some in addition to the ones already configured.
+	 * An alternative to {@link #configureMessageWriters(List)} that allows
+	 * modifying the message writers to use after default ones have been added.
 	 */
 	default void extendMessageWriters(List<HttpMessageWriter<?>> writers) {
 	}
 
 	/**
-	 * Configure view resolution for supporting template engines.
+	 * Configure view resolution for processing the return values of controller
+	 * methods that rely on resolving a
+	 * {@link org.springframework.web.reactive.result.view.View} to render
+	 * the response with. By default all controller methods rely on view
+	 * resolution unless annotated with {@code @ResponseBody} or explicitly
+	 * return {@code ResponseEntity}. A view may be specified explicitly with
+	 * a String return value or implicitly, e.g. {@code void} return value.
 	 * @see ViewResolverRegistry
 	 */
 	default void configureViewResolvers(ViewResolverRegistry registry) {

spring-web-reactive/src/main/java/org/springframework/web/reactive/config/WebReactiveConfigurerComposite.java

@@ -51,8 +51,8 @@ public void addWebReactiveConfigurers(List<WebReactiveConfigurer> configurers) {
 
 
 	@Override
-	public void configureRequestedContentTypeResolver(RequestedContentTypeResolverBuilder builder) {
-		this.delegates.stream().forEach(delegate -> delegate.configureRequestedContentTypeResolver(builder));
+	public void configureContentTypeResolver(RequestedContentTypeResolverBuilder builder) {
+		this.delegates.stream().forEach(delegate -> delegate.configureContentTypeResolver(builder));
 	}
 
 	@Override

spring-web-reactive/src/main/java/org/springframework/web/reactive/resource/AppCacheManifestTransformer.java

@@ -61,7 +61,7 @@
  * <p>In order to serve manifest files with the proper {@code "text/manifest"} content type,
  * it is required to configure it with
  * {@code requestedContentTypeResolverBuilder.mediaType("appcache", MediaType.valueOf("text/manifest")}
- * in {@code WebReactiveConfiguration.configureRequestedContentTypeResolver()}.
+ * in {@code WebReactiveConfiguration.configureContentTypeResolver()}.
  *
  * @author Rossen Stoyanchev
  * @author Brian Clozel

spring-web-reactive/src/test/java/org/springframework/web/reactive/config/DelegatingWebReactiveConfigurationTests.java

@@ -80,7 +80,7 @@ public void requestMappingHandlerMapping() throws Exception {
 		delegatingConfig.setConfigurers(Collections.singletonList(webReactiveConfigurer));
 		delegatingConfig.requestMappingHandlerMapping();
 
-		verify(webReactiveConfigurer).configureRequestedContentTypeResolver(any(RequestedContentTypeResolverBuilder.class));
+		verify(webReactiveConfigurer).configureContentTypeResolver(any(RequestedContentTypeResolverBuilder.class));
 		verify(webReactiveConfigurer).addCorsMappings(any(CorsRegistry.class));
 		verify(webReactiveConfigurer).configurePathMatching(any(PathMatchConfigurer.class));
 	}
@@ -126,7 +126,7 @@ public void responseBodyResultHandler() throws Exception {
 
 		verify(webReactiveConfigurer).configureMessageWriters(writers.capture());
 		verify(webReactiveConfigurer).extendMessageWriters(writers.capture());
-		verify(webReactiveConfigurer).configureRequestedContentTypeResolver(any(RequestedContentTypeResolverBuilder.class));
+		verify(webReactiveConfigurer).configureContentTypeResolver(any(RequestedContentTypeResolverBuilder.class));
 	}
 
 	@Test

spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/EnableWebMvc.java

@@ -31,8 +31,8 @@
  * <pre class="code">
  * &#064;Configuration
  * &#064;EnableWebMvc
- * &#064;ComponentScan(basePackageClasses = { MyConfiguration.class })
- * public class MyWebConfiguration {
+ * &#064;ComponentScan(basePackageClasses = MyConfiguration.class)
+ * public class MyConfiguration {
  *
  * }
  * </pre>
@@ -44,7 +44,7 @@
  * <pre class="code">
  * &#064;Configuration
  * &#064;EnableWebMvc
- * &#064;ComponentScan(basePackageClasses = { MyConfiguration.class })
+ * &#064;ComponentScan(basePackageClasses = MyConfiguration.class)
  * public class MyConfiguration extends WebMvcConfigurerAdapter {
  *
  * 	   &#064;Override
@@ -57,12 +57,17 @@
  *         converters.add(new MyHttpMessageConverter());
  * 	   }
  *
- *     // More overridden methods ...
  * }
  * </pre>
  *
- * <p>If {@link WebMvcConfigurer} does not expose some advanced setting that
- * needs to be configured, consider removing the {@code @EnableWebMvc}
+ * <p><strong>Note:</strong> only one {@code @Configuration} class may have the
+ * {@code @EnableWebMvc} annotation to import the Spring Web MVC
+ * configuration. There can however be multiple {@code @Configuration} classes
+ * implementing {@code WebMvcConfigurer} in order to customize the provided
+ * configuration.
+ *
+ * <p>If {@link WebMvcConfigurer} does not expose some more advanced setting that
+ * needs to be configured consider removing the {@code @EnableWebMvc}
  * annotation and extending directly from {@link WebMvcConfigurationSupport}
  * or {@link DelegatingWebMvcConfiguration}, e.g.:
  *