@async docs explicitly mention ListenableFuture and CompletableFuture

Issue: SPR-14881

Author: jhoeller

spring-context/src/main/java/org/springframework/scheduling/annotation/Async.java

@@ -29,12 +29,18 @@
  *
  * <p>In terms of target method signatures, any parameter types are supported.
  * However, the return type is constrained to either {@code void} or
- * {@link java.util.concurrent.Future}. In the latter case, the {@code Future} handle
- * returned from the proxy will be an actual asynchronous {@code Future} that can be used
- * to track the result of the asynchronous method execution. However, since the
- * target method needs to implement the same signature, it will have to return
- * a temporary {@code Future} handle that just passes the return value through: e.g.
- * Spring's {@link AsyncResult} or EJB 3.1's {@link javax.ejb.AsyncResult}.
+ * {@link java.util.concurrent.Future}. In the latter case, you may declare the
+ * more specific {@link org.springframework.util.concurrent.ListenableFuture} or
+ * {@link java.util.concurrent.CompletableFuture} types which allow for richer
+ * interaction with the asynchronous task and for immediate composition with
+ * further processing steps.
+ *
+ * <p>A {@code Future} handle returned from the proxy will be an actual asynchronous
+ * {@code Future} that can be used to track the result of the asynchronous method
+ * execution. However, since the target method needs to implement the same signature,
+ * it will have to return a temporary {@code Future} handle that just passes a value
+ * through: e.g. Spring's {@link AsyncResult}, EJB 3.1's {@link javax.ejb.AsyncResult},
+ * or {@link java.util.concurrent.CompletableFuture#completedFuture(Object)}.
  *
  * @author Juergen Hoeller
  * @author Chris Beams

src/asciidoc/integration.adoc

@@ -866,6 +866,8 @@ proxy will take care of forwarding the call to the server-side object via JMS.
 ----
 
 
+
+
 [[remoting-amqp]]
 === AMQP
 Refer to the {doc-spring-amqp}/html/_reference.html#remoting[Spring AMQP Reference Document
@@ -1087,6 +1089,7 @@ Note that the `java.net` implementation for HTTP requests may raise an exception
 accessing the status of a response that represents an error (e.g. 401). If this is an
 issue, switch to `HttpComponentsClientHttpRequestFactory` instead.
 ====
+
 The previous example using Apache HttpComponents `HttpClient` directly rewritten to use
 the `RestTemplate` is shown below
 
@@ -1124,6 +1127,7 @@ construct a `HttpComponentsClientHttpRequestFactory` like so:
     RestTemplate restTemplate = new RestTemplate(requestFactory);
 ----
 ====
+
 The general callback interface is `RequestCallback` and is called when the execute
 method is invoked.
 
@@ -2591,13 +2595,16 @@ what the <<jms-receiving-async-message-listener-adapter, `MessageListenerAdapter
 provides).
 
 The annotated endpoint infrastructure creates a message listener container
-behind the scenes for each annotated method, using a `JmsListenerContainerFactory`. Such
-container is not registered against the application context but can be easily
+behind the scenes for each annotated method, using a `JmsListenerContainerFactory`.
+Such a container is not registered against the application context but can be easily
 located for management purposes using the `JmsListenerEndpointRegistry` bean.
 
-TIP: `@JmsListener` is a _repeatable_ annotation so it is possible to associate several
-JMS destinations to the same method by adding additional `@JmsListener` declaration on
-it. For pre Java8 use cases, you can use `@JmsListeners`.
+[TIP]
+====
+`@JmsListener` is a _repeatable_ annotation on Java 8, so it is possible to associate
+several JMS destinations to the same method by adding additional `@JmsListener`
+declarations to it. On Java 6 and 7, you can use the `@JmsListeners` annotation.
+====
 
 [[jms-annotated-support]]
 ==== Enable listener endpoint annotations
@@ -2785,8 +2792,11 @@ as follow to automatically send a response:
 	}
 ----
 
-TIP: If you have several `@JmsListener`-annotated methods, you can also place the `@SendTo`
-annotation at class-level to share a default reply destination.
+[TIP]
+====
+If you have several `@JmsListener`-annotated methods, you can also place the `@SendTo`
+annotation at the class level to share a default reply destination.
+====
 
 If you need to set additional headers in a transport-independent manner, you could return a
 `Message` instead, something like:
@@ -2826,7 +2836,7 @@ example can be rewritten as follows:
 
 
 [[jms-namespace]]
-=== JMS Namespace Support
+=== JMS namespace support
 Spring provides an XML namespace for simplifying JMS configuration. To use the JMS
 namespace elements you will need to reference the JMS schema:
 
@@ -6372,7 +6382,7 @@ reference is provided for managing those methods annotated with `@Scheduled`.
 
 
 [[scheduling-annotation-support-scheduled]]
-==== The @Scheduled Annotation
+==== The @Scheduled annotation
 The `@Scheduled` annotation can be added to a method along with trigger metadata. For
 example, the following method would be invoked every 5 seconds with a fixed delay,
 meaning that the period will be measured from the completion time of each preceding
@@ -6430,7 +6440,6 @@ You can additionally use the `zone` attribute to specify the time zone in which
 expression will be resolved.
 ====
 
-
 Notice that the methods to be scheduled must have void returns and must not expect any
 arguments. If the method needs to interact with other objects from the Application
 Context, then those would typically have been provided through dependency injection.
@@ -6451,7 +6460,7 @@ container and once through the `@Configurable` aspect, with the consequence of e
 
 
 [[scheduling-annotation-support-async]]
-==== The @Async Annotation
+==== The @Async annotation
 The `@Async` annotation can be provided on a method so that invocation of that method
 will occur asynchronously. In other words, the caller will return immediately upon
 invocation and the actual execution of the method will occur in a task that has been
@@ -6495,6 +6504,14 @@ asynchronous execution so that the caller can perform other tasks prior to calli
 	}
 ----
 
+[TIP]
+====
+`@Async` methods may not only declare a regular `java.util.concurrent.Future` return type
+but also Spring's `org.springframework.util.concurrent.ListenableFuture` or, as of Spring
+4.2, JDK 8's `java.util.concurrent.CompletableFuture`: for richer interaction with the
+asynchronous task and for immediate composition with further processing steps.
+====
+
 `@Async` can not be used in conjunction with lifecycle callbacks such as
 `@PostConstruct`. To asynchronously initialize Spring beans you currently have to use
 a separate initializing Spring bean that invokes the `@Async` annotated method on the
@@ -6583,8 +6600,11 @@ however, the exception is uncaught and cannot be transmitted. For those cases, a
 By default, the exception is simply logged. A custom `AsyncUncaughtExceptionHandler` can
 be defined _via_ `AsyncConfigurer` or the `task:annotation-driven` XML element.
 
+
+
+
 [[scheduling-task-namespace]]
-=== The Task Namespace
+=== The task namespace
 Beginning with Spring 3.0, there is an XML namespace for configuring `TaskExecutor` and
 `TaskScheduler` instances. It also provides a convenient way to configure tasks to be
 scheduled with a trigger.