Handing asynchronous results

Make controllers asynchronous

在内部，Play自下而上都是异步的。Play以asynchronous,non-blocking的方式处理每个请求。

默认的配置就开启了asynchronous controllers。换句话说，应用的代码应该避免阻塞在controllers中，即controller中的代码会因为一个操作而等待。常见的一些阻塞操作像：JDBC calls，streaming API,HTTP requests and long computations.

尽管可以通过增加默认执行环境的线程数来允许更多的并发请求让阻塞controller去处理，跟随下面的推荐，尽可能的保持controllers异步是它更容易伸缩并保持系统负载下及时的响应。

Creating non-blocking actions

由于Play的工作方式，action的代码必须尽可能的快，即 non-blocking.那么我们应该从action中返回什么如果我们还没能计算出这个结果呢？我们应该返回promise。

Java 8 提供了一个通用promise API叫做CompletionStage.一个CompletionStage<Result>将最终被一个Result类型的值赎回。通过使用CompletionStage<Result>替代一个正常的Result,我们可以从action中很快的返回而不阻塞任何东西.一旦Result被赎回Play就会返回。

web client将会阻塞等待直到响应，但server不会有任何的阻塞，并且server的资源可以用来服务其他的client。

How to create a CompletionStage<Result>

去创建一个CompletionStage<Result>,我们需要其他的promise：这个promise会给我们一个真实的值-我们需要的计算结果：

CompletionStage<Double> promiseOfPIValue = computePIAsynchronously();
CompletionStage<Result> promiseOfResult = promiseOfPIValue.thenApply(pi ->
                ok("PI value computed: " + pi)
);

Play的异步API方法给你一个CompletionStage.可能是当你调用一个外部的web service使用play.libs.WSAPI,或是使用Akka to schedule asynchronous tasks又或是使用Actor通过play.libs.Akka与其通信。

一个简单的方式去异步的执行一个代码块并获取CompletionStage是去使用CompletableFuture.supplyAsync()helper:

CompletionStage<Integer> promiseOfInt = CompletableFuture.supplyAsync(() -> intensiveComputation());

注意：
知道promises的代码运行在哪一个线程上很重要。这里的密集运算将被运行在其他的线程上。
通过将其包裹在CompletionStage中是无法将synchronous IO转变为 asynchronous的。如果你不能改变这个应用的架构去避免阻塞操作，那么在一些地方操作被执行的时候，线程将会阻塞。所以使用CompletionStage去包裹操作时，需要去使其运行在分离的execution context中，这里需要配置足够的线程去处理预期的并发。可以参考Understanding Play thread pools了解更多。
这里使用Actors处理阻塞操作也是有帮助的。Actors提供了一个干净的模型处理timeouts和failures，设置阻塞执行的contexts，并且管理可能与该服务相关联的任意状态。Actors提供了类似ScatterGatherFirstCompletedRouter的模式to address simultaneous cache and database requests and allow remote execution on a cluster of backend servers.But an Actor may be overkill depending on what you need.

Using CompletionStage inside an Action

在Action中使用JavaCompletionStage时，您必须作为执行器显式提供HTTP执行上下文，以确保HTTP.Context保留在范围内。如果你没有应用HTTP execution context，你会得到“There is no HTTP Context available from here”的错误当你调用request()或是其他依赖Http.Context的方法。

你可以用play.libs.concurrent.HttpExecutionContext实例通过依赖注入：

public class Application extends Controller {
    @Inject HttpExecutionContext ec;

    public CompletionStage<Result> index() {
        someCompletableFuture.supplyAsync(() -> { 
          // do something with request()
        }, ec.current());
    }
}

Async results

We have been returning Resultup until now.要发送一个异步的结果我们的action需要返回一个CompletionStage<Result>:

public CompletionStage<Result> index() {
    return CompletableFuture.supplyAsync(() -> intensiveComputation())
            .thenApply(i -> ok("Got result: " + i));
}

Actions are asynchronous by default

Play的actions是默认异步的。例如，下面的controller代码，返回的Result的内部包裹了一个promise：

public Result index() {
    return ok("Got request " + request() + "!");
}

注意：无论action的代码返回的是一个Result或是一个CompletionStage<Result>,这两种返回对象都以同样的方式在内部处理。这里又一个单独的Action，是异步的，不是两种。返回一个CompletionStage是一个编写非阻塞代码的技术。

Handling time-outs

正确的去处理超时通常是很有用的，避免一个web浏览器的阻塞和等待如果出现了一些错误。你可以使用play.libs.concurrent.Timeout.timeout方法去包裹一个CompletionStage在一个非阻塞的超时中。

class MyClass implements play.libs.concurrent.Timeout {
    CompletionStage<Double> callWithOneSecondTimeout() {
        return timeout(computePIAsynchronously(), Duration.ofSeconds(1));
    }
}

注意：Timeout与cancellation不同，即使在超时的情况下，即使未返回完成的值，给定的future仍将完成。