Polish CodecConfigurer related classes

Functionally equivalent updates to package private classes to improve
the code and make it easier to understand.

Author: rstoyanchev

spring-web/src/main/java/org/springframework/http/codec/ClientCodecConfigurer.java

@@ -20,35 +20,33 @@
 import org.springframework.core.codec.Encoder;
 
 /**
- * Helps to configure a list of client-side HTTP message readers and writers
- * with support for built-in defaults and options to register additional custom
- * readers and writers via {@link #customCodecs()}.
- *
- * <p>The built-in defaults include basic data types such as various byte
- * representations, resources, strings, forms, but also others like JAXB2 and
- * Jackson 2 based on classpath detection. There are options to
- * {@link #defaultCodecs() override} some of the defaults or to have them
- * {@link #registerDefaults(boolean) turned off} completely.
+ * Extension of {@link CodecConfigurer} for HTTP message reader and writer
+ * options relevant on the client side.
  *
  * @author Rossen Stoyanchev
  * @since 5.0
  */
 public interface ClientCodecConfigurer extends CodecConfigurer {
 
+	/**
+	 * {@inheritDoc}
+	 * <p>On the client side, built-in default also include customizations related
+	 * to multipart readers and writers, as well as the decoder for SSE.
+	 */
 	@Override
 	ClientDefaultCodecs defaultCodecs();
 
 
 	/**
-	 * Create a new instance of the {@code ClientCodecConfigurer}.
+	 * Static factory method for a {@code ClientCodecConfigurer}.
 	 */
 	static ClientCodecConfigurer create() {
 		return CodecConfigurerFactory.create(ClientCodecConfigurer.class);
 	}
 
 
 	/**
-	 * Extension of {@link CodecConfigurer.DefaultCodecs} with extra client options.
+	 * {@link CodecConfigurer.DefaultCodecs} extension with extra client-side options.
 	 */
 	interface ClientDefaultCodecs extends DefaultCodecs {
 

spring-web/src/main/java/org/springframework/http/codec/CodecConfigurer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,32 +23,59 @@
 
 /**
  * Defines a common interface for configuring either client or server HTTP
- * message readers and writers. To obtain an instance use either
- * {@link ClientCodecConfigurer#create()} or
- * {@link ServerCodecConfigurer#create()}.
+ * message readers and writers. This is used as follows:
+ * <ul>
+ * <li>Use {@link ClientCodecConfigurer#create()} or
+ * {@link ServerCodecConfigurer#create()} to create an instance.
+ * <li>Use {@link #defaultCodecs()} to customize HTTP message readers or writers
+ * registered by default.
+ * <li>Use {@link #customCodecs()} to add custom HTTP message readers or writers.
+ * <li>Use {@link #getReaders()} and {@link #getWriters()} to obtain the list of
+ * configured HTTP message readers and writers.
+ * </ul>
+ *
+ * <p>HTTP message readers and writers are divided into 3 categories that are
+ * ordered as follows:
+ * <ol>
+ * <li>Typed readers and writers that support specific types, e.g. byte[], String.
+ * <li>Object readers and writers, e.g. JSON, XML.
+ * <li>Catch-all readers or writers, e.g. String with any media type.
+ * </ol>
+ *
+ * <p>Typed and object readers are further sub-divided and ordered as follows:
+ * <ol>
+ * <li>Default HTTP reader and writer registrations.
+ * <li>Custom readers and writers.
+ * </ol>
  *
  * @author Rossen Stoyanchev
  * @since 5.0
  */
 public interface CodecConfigurer {
 
 	/**
-	 * Configure or customize the default HTTP message readers and writers.
+	 * Provides a way to customize or replace HTTP message readers and writers
+	 * registered by default.
+	 * @see #registerDefaults(boolean)
 	 */
 	DefaultCodecs defaultCodecs();
 
 	/**
-	 * Whether to register default HTTP message readers and writers.
-	 * <p>By default this is set to {@code "true"}; setting this to {@code false}
-	 * disables default HTTP message reader and writer registrations.
+	 * Register custom HTTP message readers or writers in addition to the ones
+	 * registered by default.
 	 */
-	void registerDefaults(boolean registerDefaults);
+	CustomCodecs customCodecs();
 
 	/**
-	 * Register custom HTTP message readers or writers to use in addition to
-	 * the ones registered by default.
+	 * Provides a way to completely turn off registration of default HTTP message
+	 * readers and writers, and instead rely only on the ones provided via
+	 * {@link #customCodecs()}.
+	 * <p>By default this is set to {@code "true"} in which case default
+	 * registrations are made; setting this to {@code false} disables default
+	 * registrations.
 	 */
-	CustomCodecs customCodecs();
+	void registerDefaults(boolean registerDefaults);
+
 
 	/**
 	 * Obtain the configured HTTP message readers.
@@ -62,9 +89,10 @@ public interface CodecConfigurer {
 
 
 	/**
-	 * Assists with customizing the default HTTP message readers and writers.
-	 * @see ClientCodecConfigurer.ClientDefaultCodecs
-	 * @see ServerCodecConfigurer.ServerDefaultCodecs
+	 * Customize or replace the HTTP message readers and writers registered by
+	 * default. The options are further extended by
+	 * {@link ClientCodecConfigurer.ClientDefaultCodecs ClientDefaultCodecs} and
+	 * {@link ServerCodecConfigurer.ServerDefaultCodecs ServerDefaultCodecs}.
 	 */
 	interface DefaultCodecs {
 
@@ -85,7 +113,7 @@ interface DefaultCodecs {
 
 
 	/**
-	 * Registry and container for custom HTTP message readers and writers.
+	 * Registry for custom HTTP message readers and writers.
 	 */
 	interface CustomCodecs {
 

spring-web/src/main/java/org/springframework/http/codec/ServerCodecConfigurer.java

@@ -19,35 +19,33 @@
 import org.springframework.core.codec.Encoder;
 
 /**
- * Helps to configure a list of server-side HTTP message readers and writers
- * with support for built-in defaults and options to register additional custom
- * readers and writers via {@link #customCodecs()}.
- *
- * <p>The built-in defaults include basic data types such as various byte
- * representations, resources, strings, forms, but also others like JAXB2 and
- * Jackson 2 based on classpath detection. There are options to
- * {@link #defaultCodecs() override} some of the defaults or to have them
- * {@link #registerDefaults(boolean) turned off} completely.
+ * Extension of {@link CodecConfigurer} for HTTP message reader and writer
+ * options relevant on the server side.
  *
  * @author Rossen Stoyanchev
  * @since 5.0
  */
 public interface ServerCodecConfigurer extends CodecConfigurer {
 
+	/**
+	 * {@inheritDoc}
+	 * <p>On the server side, built-in default also include customizations
+	 * related to the encoder for SSE.
+	 */
 	@Override
 	ServerDefaultCodecs defaultCodecs();
 
 
 	/**
-	 * Create a new instance of the {@code ServerCodecConfigurer}.
+	 * Static factory method for a {@code ServerCodecConfigurer}.
 	 */
 	static ServerCodecConfigurer create() {
 		return CodecConfigurerFactory.create(ServerCodecConfigurer.class);
 	}
 
 
 	/**
-	 * Extension of {@link CodecConfigurer.DefaultCodecs} with extra server options.
+	 * {@link CodecConfigurer.DefaultCodecs} extension with extra client-side options.
 	 */
 	interface ServerDefaultCodecs extends DefaultCodecs {