

§Handling asynchronous results

§Make controllers asynchronous




§Creating non-blocking actions

Because of the way Play works, action code must be as fast as possible, i.e., non-blocking. So what should we return from our action if we are not yet able to compute the result? We should return the promise of a result!

Java 8 provides a generic promise API called CompletionStage. A CompletionStage<Result> will eventually be redeemed with a value of type Result. By using a CompletionStage<Result> instead of a normal Result, we are able to return from our action quickly without blocking anything. Play will then serve the result as soon as the promise is redeemed.


§How to create a CompletionStage<Result>

To create a CompletionStage<Result> we need another promise first: the promise that will give us the actual value we need to compute the result:

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

Play asynchronous API methods give you a CompletionStage. This is the case when you are calling an external web service using the play.libs.WS API, or if you are using Akka to schedule asynchronous tasks or to communicate with Actors using play.libs.Akka.

A simple way to execute a block of code asynchronously and to get a CompletionStage is to use the CompletableFuture.supplyAsync() helper:

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

Note: It’s important to understand which thread code runs on which promises. Here, the intensive computation will just be run on another thread.

You can’t magically turn synchronous IO into asynchronous by wrapping it in a CompletionStage. If you can’t change the application’s architecture to avoid blocking operations, at some point that operation will have to be executed, and that thread is going to block. So in addition to enclosing the operation in a CompletionStage, it’s necessary to configure it to run in a separate execution context that has been configured with enough threads to deal with the expected concurrency. See Understanding Play thread pools for more information.


§Using CompletionStage inside an Action


You can supply the play.libs.concurrent.HttpExecutionContext instance through dependency injection:

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 Result up until now. To send an asynchronous result our action needs to return a CompletionStage<Result>:

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

§Actions are asynchronous by default

Play actions are asynchronous by default. For instance, in the controller code below, the returned Result is internally enclosed in a promise:

public Result index() {

Note: Whether the action code returns a Result or a CompletionStage<Result>, both kinds of returned object are handled internally in the same way. There is a single kind of Action, which is asynchronous, and not two kinds (a synchronous one and an asynchronous one). Returning a CompletionStage is a technique for writing non-blocking code.

§Handling time-outs

It is often useful to handle time-outs properly, to avoid having the web browser block and wait if something goes wrong. You can use play.libs.concurrent.Timeout.timeout method to wrap a CompletionStage in a non-blocking timeout.

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


Next: Streaming HTTP responses
