Async return values refactoring in Spring MVC

Revise Javadoc on AsyncHandlerMethodReturnValueHandler to clarify its
main purpose is to prioritze custom async return value handlers ahead
of built-in ones. Also replace the interface from built-in handlers
which are prioritized already.

Remove DeferredResultAdapter and ResponseBodyEmitterAdapter --
introduced in 4.3 for custom async return value handling, since for
5.0 we will add built-in support for reactive types and the value of
these contracts becomes very marginal.

Issue: SPR-15365

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -19,20 +19,16 @@ package org.springframework.web.method.support;
 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. By contrast, built-in (async) handlers are already ordered ahead of
+ * sync handlers.
  *
  * @author Rossen Stoyanchev
  * @since 4.2

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

@@ -33,7 +33,7 @@ import org.springframework.web.context.request.NativeWebRequest;
  * @author Rossen Stoyanchev
  * @since 3.1
  */
-public class HandlerMethodReturnValueHandlerComposite implements AsyncHandlerMethodReturnValueHandler {
+public class HandlerMethodReturnValueHandlerComposite implements HandlerMethodReturnValueHandler {
 
 	protected final Log logger = LogFactory.getLog(getClass());
 
@@ -94,8 +94,7 @@ public class HandlerMethodReturnValueHandlerComposite implements AsyncHandlerMet
 		return null;
 	}
 
-	@Override
-	public boolean isAsyncReturnValue(Object value, MethodParameter returnType) {
+	private boolean isAsyncReturnValue(Object value, MethodParameter returnType) {
 		for (HandlerMethodReturnValueHandler handler : this.returnValueHandlers) {
 			if (handler instanceof AsyncHandlerMethodReturnValueHandler) {
 				if (((AsyncHandlerMethodReturnValueHandler) handler).isAsyncReturnValue(value, returnType)) {