In order to have a simple test, you could create a small application which creates a big PDF report. Then access the URL mapped to the PDF report creation more often simultaneous than you have CPU cores. So you would have to request this resource three times at once on a duo core machine. You will see that a maximum two HTTP connections are executed simultaneously; in development mode it will be only one, regardless of your CPU count.

Play 1.2 introduces a new feature called continuations, which allows transparent suspension of threads including recovery without writing any additional code to do this:

public static void generateInvoice(Long orderId) {
    Order order = Order.findById(orderId);
    InputStream is = await(new OrderAsPdfJob(order).now());
    renderBinary(is);
}

Of course, the OrderAsPdfJob needs a signature like this:

public void OrderAsPdfJob extends Job<InputStream> {

    public InputStreamdoJobWithResult() {
        // logic goes here
    }
}

You can suspend your logic for a certain amount of time like this:

public static void stockChanges() {
   List<Stock> stocks = Stock.find("date > ?", request.date).fetch();
   if (stocks.isEmpty()) {
       suspend("1s");
   }
renderJSON(stocks);
}

Alternatively, you can wait until a certain job has finished its business logic:

public static void generateInvoice(Long orderId) {
    if(request.isNew) {
        Order order = Order.findById(orderId);
        Future<InputStream> task = new OrderAsPdfJob(order).now();
        request.args.put("task", task);
        waitFor(task);
    }
    renderBinary((Future<InputStream>)request.args.get("task").get());
}

Following the three lines of code in the first example, you see that there is actually no invocation telling the framework to suspend the thread. The await() method takes a so-called Promise as argument, which is returned by the now() method of the job. A Promise is basically a standard Java Future with added functionality for invocation inside of the framework, when the task is finished.

The stockChanges() example is pretty self explanatory as it waits the defined amount of time before it is called again. This means that the operation is only called again if there was no updated stock available and it is very important it is called again from the beginning. Otherwise it will happily render the JSON output and has to be triggered by the client again. As you can see, this would be a pretty interesting starting point for implementing SLAs for your customers in a stock rate application, as you could allow your premium customers quicker updates.

The second example takes another approach. The controller logic is actually run twice. In the first run, the isNew parameter is true and starts a Play job to create the PDF of an invoice. This parameter is automatically set by the framework depending on the status of the request and gives the developer the possibility to decide what should happen next. The waitFor() tells the framework to suspend here. Again, after the task is finished, the whole controller method will be called again, but this time only the renderBinary() method is called as isNew is false, which returns the result by calling get() on the Future type.

Always think whether introducing such a suspended response is really what you want or whether this just shows certain problems in your application design. Most of the time such a mechanism is not needed.

The recipe Integration with Munin in Chapter 7 shows how to monitor your controller execution times in order to make sure you are suspending the right requests.