Chapter 29. Asynchronous HTTP Request Processing

Asynchronous HTTP Request Processing lets you process a single HTTP request using NIO (Non-blocking Input/Output), in separate threads (if desired). This is also known as COMET capability. The primary use case for Asynchronous HTTP is where the client polls the server for a delayed response.
A common example is an AJAX chat client that pushes/pulls from both the client and the server. In this scenario, the client blocks a long period of time on the server's socket while waiting for a new message. In synchronous HTTP (where the server blocks on incoming and outgoing I/O), one thread is consumed per client connection, which consumes both memory and thread resources. When multiple concurrent clients block in this way, resources are not used effectively, and the server does not scale well.
Tomcat, Jetty, and JBoss Web all have similar (proprietary) support for asynchronous HTTP request processing. This functionality is currently being standardized in the Servlet 3.0 specification. RESTEasy provides a simple callback API to provide asynchronous capabilities, and supports integration with Servlet 3.0 (through Jetty 7), Tomcat 6, and JBoss Web 2.1.1.
The RESTEasy asynchronous HTTP support is implemented via two classes: the @Suspend annotation and the AsynchronousResponse interface. 
public @interface Suspend
{
   long value() default -1;
}

import javax.ws.rs.core.Response;

public interface AsynchronousResponse
{
   void setResponse(Response response);
}
@Suspend tells RESTEasy that the HTTP request/response should be detached from the currently executing thread, and that the current thread should not automatically process the response. The argument to @Suspend is the time in milliseconds until the request should be canceled.
AsynchronousResponse is the callback object. It is injected into the method by RESTEasy. Application code moves the AsynchronousResponse to a different thread for processing. Calling setResponse() returns a response to the client and terminates the HTTP request. The following is an example of asynchronous processing: 
import org.jboss.resteasy.annotations.Suspend;
import org.jboss.resteasy.spi.AsynchronousResponse;

@Path("/")
public class SimpleResource
{

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

29.1. Tomcat 6 and JBoss 4.2.3 Support

To use RESTEasy's Asynchronous HTTP APIs with Tomcat 6 or JBoss 4.2.3, you must use a special RESTEasy Servlet and configure Tomcat (or JBoss Web in JBoss 4.2.3) to use the NIO transport. First, edit Tomcat's (or JBoss Web's) server.xml file. Comment out the vanilla HTTP adapter and add the following: 
<Connector port="8080" address="${jboss.bind.address}"
   emptySessionPath="true" protocol="org.apache.coyote.http11.Http11NioProtocol"
   enableLookups="false" redirectPort="6443" acceptorThreadCount="2" pollerThreadCount="10"
/>
Your deployed RESTEasy applications must also use a different RESTEasy Servlet: org.jboss.resteasy.plugins.server.servlet.Tomcat6CometDispatcherServlet. This class is available within the async-http-tomcat-xxx.jar (or within the Maven repository, under the async-http-tomcat6 artifact ID) in web.xml. 
<servlet>
   <servlet-name>Resteasy</servlet-name>
   <servlet-class>org.jboss.resteasy.plugins.server.servlet.Tomcat6CometDispatcherServlet</servlet-class>
</servlet>