The following example shows a simple asynchronous resource method using the new JAX-RS async features:

@GET
@Path("/simple")
public void asyncGet(@Suspended final AsyncResponse asyncResponse) {
   new Thread(new Runnable() {
      @Override
      public void run() {
       String result = veryExpensiveOperation();
         asyncResponse.resume(result);
      }
   private String veryExpensiveOperation() {
    return new MagicNumber(3) + "";
   }
  }).start();
}

We have a JAX-RS AsyncResponse class passed as an attribute to a GET method implementation, asyncGet. This method injects an instance of AsyncResponse using the javax.ws.rs.container.Suspended annotation.

This annotation is very similar to the javax.ws.rs.core.Context annotation. The @Context annotation allows us to inject a REST response. The @Suspend annotation does the same with the difference, it declares the resource as part of an asynchronous operation too.

Asynchronous is when a thread is different when starting the thread end operation. In this case, it is not certain that the AsyncResponse will return to the same thread. Through the @Suspend, we say that the AsyncResponse is suspended until a thread can take the response and resume it. The choice and creation of the threads is the work of RESTEasy. The suspend operation of the AsyncResponse is transparent to the application. The application must only declare the operation as asynchronous through the @Suspend annotation and remember that the response must be resumed before to using it.

Note that the asyncGet method returns void in this example. In case of an asynchronous JAX-RS resource methods is lawful, even for a method declared as @GET, because the response is never directly returned from the method with a value. Being asynchronous, the response will return when the internal decision of the framework will be confirmed or never done in other cases.

With the asyncGet resource method, a new thread is started. Nothing of output streams will be closed at the end of the method until the resume method of the AsyncResponse is executed.

The one thread candidate to host the resource will go back in the thread pool of the application server once the method executes. In this state, the request processing remains suspended and the started thread can process other new requests.

New threads started in the resource methods may execute expensive operations, which might take a long time to end. When the result is ready, it will be resumed through the resume() method of the AsyncResponse instance. The resumed response will then be processed in a new thread by RESTEasy in the same way as any other synchronous response. Execution of filters, interceptors, and exception mappers can be included as necessary and then the response is sent back to the client.

We must note that this asynchronous response does not need to be resumed from the starting thread of the resource method. The asynchronous response can be resumed even from other request processing threads. In other examples, the suspended asynchronous response from the GET method can be resumed later on, for example, from a POST method. The suspended asynchronous response can be passed between requests through a static field and then resumed from another method that runs on a different request processing thread.

The asynchronous call response time may be prolonged over time; the factors can be many--complexity in code, different waiting points for resource managers, unconnected connections, or unexpected errors. Timeouts can solve the long wait; REST provides a good system for configuring timeouts on resources and methods. In the next paragraph, we will see the timeout in detail.