The JAX-RS 2.0 specification has added asynchronous HTTP support via two classes. The @Suspended annotation, and AsyncResponse interface.

Injecting an AsynchronousResponse as a parameter to your jax-rs methods tells RESTEasy that the HTTP request/response should be detached from the currently executing thread and that the current thread should not try to automatically process the response.

The AsyncResponse is the callback object. The act of calling one of the resume() methods will cause a response to be sent back to the client and will also terminate the HTTP request. Here is an example of asynchronous processing:

import javax.ws.rs.Suspend;
import javax.ws.rs.core.AsynchronousResponse;

@Path("/")
public class SimpleResource
{

   @GET
   @Path("basic")
   @Produces("text/plain")
   public void getBasic(@Suspended final AsyncResponse response) throws Exception
   {
      Thread t = new Thread()
      {
         @Override
         public void run()
         {
            try
            {
               Response jaxrs = Response.ok("basic").type(MediaType.TEXT_PLAIN).build();
               response.resume(jaxrs);
            }
            catch (Exception e)
            {
               response.resume(e);
            }
         }
      };
      t.start();
   }
}
      

AsyncResponse also has other methods to cancel the execution. See javadoc for more details.

NOTE: The old RESTEasy proprietary API for async http has been deprecated and may be removed as soon as RESTEasy 3.1. In particular, the RESTEasy @Suspend annotation is replaced by javax.ws.rs.container.Suspended, and org.jboss.resteasy.spi.AsynchronousResponse is replaced by javax.ws.rs.container.AsyncResponse. Note that @Suspended does not have a value field, which represented a timeout limit. Instead, AsyncResponse.setTimeout() may be called.

Whenever a resource method returns a CompletionStage, it will be subscribed to, the request will be suspended, and only resumed when the CompletionStage is resolved either to a value (which is then treated as the return value for the method), or as an error case, in which case the exception will be processed as if it were thrown by the resource method.

Here is an example of asynchronous processing using CompletionStage:

import javax.ws.rs.Suspend;
import javax.ws.rs.core.AsynchronousResponse;

@Path("/")
public class SimpleResource
{

   @GET
   @Path("basic")
   @Produces("text/plain")
   public CompletionStage<Response> getBasic() throws Exception
   {
      final CompletableFuture<Response> response = new CompletableFuture<>();
      Thread t = new Thread()
      {
         @Override
         public void run()
         {
            try
            {
               Response jaxrs = Response.ok("basic").type(MediaType.TEXT_PLAIN).build();
               response.complete(jaxrs);
            }
            catch (Exception e)
            {
               response.completeExceptionally(e);
            }
         }
      };
      t.start();
      return response;
   }
}
     

Some backends support asynchronous IO operations (Servlet, Undertow, Vert.x, Quarkus, Netty), which are exposed using the AsyncOutputStream subtype of OutputStream. It includes async variants for writing and flushing the stream.

Some backends have what is called an "Event Loop Thread", which is a thread responsible for doing all IO operations. Those backends require the Event Loop Thread to never be blocked, because it does IO for every other thread. Those backends typically require JAX-RS endpoints to be invoked on worker threads, to make sure they never block the Event Loop Thread.

Sometimes, with Async programming, it is possible for asynchronous JAX-RS requests to be resumed from the Event Loop Thread. As a result, JAX-RS will attempt to serialise the response and send it to the client. But JAX-RS is written using "Blocking IO" mechanics, such as OutputStream (used by MessageBodyWriter and WriterInterceptor), which means that sending the response will block the current thread until the response is received. This would work on a worker thread, but if it happens on the Event Loop Thread it will block it and prevent it from sending the response, resulting in a deadlock.

As a result, we've decided to support and expose Async IO interfaces in the form of AsyncOutputStream, AsyncMessageBodyWriter and AsyncWriterInterceptor, to allow users to write Async IO applications in RESTEasy.

Most built-in MessageBodyWriter and WriterInterceptor support Async IO, with the notable exceptions of:

Async IO will be preferred if the following conditions are met:

If those conditions are not met, and you attempt to use Blocking IO on an Event Loop Thread (as determined by the backend), then an exception will be thrown.