Deprecations related to reactive type support in 5.0

Issue: SPR-15365

Author: rstoyanchev

spring-web/src/main/java/org/springframework/web/method/support/AsyncHandlerMethodReturnValueHandler.java

@@ -19,20 +19,15 @@
 import org.springframework.core.MethodParameter;
 
 /**
- * A {@link HandlerMethodReturnValueHandler} that handles return values that
- * represent asynchronous computation. Such handlers need to be invoked with
- * precedence over other handlers that might otherwise match the return value
- * type: e.g. a method that returns a Promise type that is also annotated with
- * {@code @ResponseBody}.
+ * A return value handler that supports async types. Such return value types
+ * need to be handled with priority so the async value can be "unwrapped".
  *
- * <p>In {@link #handleReturnValue}, implementations of this class should create
- * a {@link org.springframework.web.context.request.async.DeferredResult} or
- * adapt to it and then invoke {@code WebAsyncManager} to start async processing.
- * For example:
- * <pre>
- * DeferredResult<?> deferredResult = (DeferredResult<?>) returnValue;
- * WebAsyncUtils.getAsyncManager(webRequest).startDeferredResultProcessing(deferredResult, mavContainer);
- * </pre>
+ * <p><strong>Note: </strong> implementing this contract is not required but it
+ * should be implemented when the handler needs to be prioritized ahead of others.
+ * For example custom (async) handlers, by default ordered after built-in
+ * handlers, should take precedence over {@code @ResponseBody} or
+ * {@code @ModelAttribute} handling, which should occur once the async value is
+ * ready.
  *
  * @author Rossen Stoyanchev
  * @since 4.2

spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/DeferredResultAdapter.java

@@ -23,7 +23,14 @@
  *
  * @author Rossen Stoyanchev
  * @since 4.3
+ *
+ * @deprecated in 4.3.8 since 5.0 adds first-class support for reactive type
+ * return values from Spring MVC controller methods based on the pluggable
+ * {@code ReactiveAdapterRegistry} mechanism. Yet another alternative would
+ * be to implement a custom
+ * {@link org.springframework.web.method.support.AsyncHandlerMethodReturnValueHandler}.
  */
+@Deprecated
 public interface DeferredResultAdapter {
 
 	/**

spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/DeferredResultMethodReturnValueHandler.java

@@ -41,6 +41,7 @@
  * @author Rossen Stoyanchev
  * @since 3.2
  */
+@SuppressWarnings("deprecation")
 public class DeferredResultMethodReturnValueHandler implements AsyncHandlerMethodReturnValueHandler {
 
 	private final Map<Class<?>, DeferredResultAdapter> adapterMap;
@@ -61,7 +62,9 @@ public DeferredResultMethodReturnValueHandler() {
 	 * <p>By default the map contains adapters for {@code DeferredResult}, which
 	 * simply downcasts, {@link ListenableFuture}, and {@link CompletionStage}.
 	 * @return the map of adapters
+	 * @deprecated in 4.3.8, see comments on {@link DeferredResultAdapter}
 	 */
+	@Deprecated
 	public Map<Class<?>, DeferredResultAdapter> getAdapterMap() {
 		return this.adapterMap;
 	}

spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/ResponseBodyEmitterAdapter.java

@@ -23,7 +23,12 @@
  *
  * @author Rossen Stoyanchev
  * @since 4.3
+ *
+ * @deprecated in 4.3.8 since 5.0 adds first-class support for reactive type
+ * return values from Spring MVC controller methods based on the pluggable
+ * {@code ReactiveAdapterRegistry} mechanism.
  */
+@Deprecated
 public interface ResponseBodyEmitterAdapter {
 
 	/**

spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/ResponseBodyEmitterReturnValueHandler.java

@@ -52,6 +52,7 @@
  * @author Rossen Stoyanchev
  * @since 4.2
  */
+@SuppressWarnings("deprecation")
 public class ResponseBodyEmitterReturnValueHandler implements AsyncHandlerMethodReturnValueHandler {
 
 	private static final Log logger = LogFactory.getLog(ResponseBodyEmitterReturnValueHandler.class);
@@ -75,7 +76,9 @@ public ResponseBodyEmitterReturnValueHandler(List<HttpMessageConverter<?>> messa
 	 * By default the map contains a single adapter {@code ResponseBodyEmitter}
 	 * that simply downcasts the return value.
 	 * @return the map of adapters
+	 * @deprecated in 4.3.8, see comments on {@link ResponseBodyEmitterAdapter}
 	 */
+	@Deprecated
 	public Map<Class<?>, ResponseBodyEmitterAdapter> getAdapterMap() {
 		return this.adapterMap;
 	}