After the last couple of entries I have gotten requests for more details on how the async works. So I decided to write this up in a blog to share what the async support looks like in the Servlet 3.0 public review draft. 

There are a couple of use cases that we are trying to handle with the async support in Servlet 3.0 -

  • Wait for a resource to become available (JDBC, call to webservice)
  • Generate response asynchronously
  • Use the existing frameworks to generate responses after waiting for the async operation to complete
Keeping this in mind the API that the expert group has agreed upon for async is as follows. 
  • Annotation attributes in the @WebServlet and@ServletFilter annotations that indicates if a Servlet or a Filter supports async. The attribute isasyncSupported.
  • To initiate an async operation there are methods onServletRequest - startAsync(req, res) andstartAsync() (difference described below).
  • Call to startAsync returns anAsyncContext initialized with the request and response objects passed to the startAsync call.
  • AsyncContext.forward(path) andAsyncContext.forward() that forwards the request back to the container so you can use frameworks like JSP to generate the response.
  • AsyncContext.complete() indicates that the developer is done processing the request and generating the appropriate response.
  • There are a few more methods in ServletRequestlike isAsyncSupported and isAsyncStartedthat can be used by applications to determine if async operations are supported or started.
  • There is also a new listener - AsyncListener that applications can use to get notified of when async processing is completed or if a timeout occurs.
To initiate async processing there are two methods available - one that takes a request and response (startAsync(req, res) ) and one that does not take any parameters (startAsync()). The difference between the two method signatures is that the startAsync() with no parameters implicitly uses the original request and response while the startAsync(req, res) uses the request and response objects passed in. The request and response passed in can be wrapped by filters or other servlets earlier in the request processing chain. The AsyncContext is initialized appropriately with the request and response depending on the method used. Caution must be taken when wrapping the response and calling the no arguments startAsync(). If any data has been written to the wrapped response and not flushed to the underlying response stream you could lose the data. 

Similarly after the async processing is over if you choose to forward the request back to run in the context of the web container there are three methods that are available in the AsyncContext that enable this. forward(path), forward(ServletContext, path) and forward().

  • forward() no args forwards back to the "original url" or if a forward (AsyncContext or RequestDispatcher forward) has occured after an async context has been initialized then the no args forward will forward to the path that was used by the AsyncContext / RequestDispatcher to forward to.
  • forward(path) forwards to the path relative to the context of the request
  • forward(ServletContext, path) forwards to the path relative to the context specified. Below is an example that shows a simple web application that is waiting for a webservice call to return and then rendering the response. Note the actual code for calling the web service itself is not included. 
    @WebServlet("/foo" asyncSupported=true)
    public class MyServlet extends HttpServlet {
        public void doGet(HttpServletRequest req, HttpServletResponse res) {
            AsyncContext aCtx = request.startAsync(req, res);
            ScheduledThreadPoolExecutor executor = new ThreadPoolExecutor(10);
            executor.execute(new AsyncWebService(aCtx));
    public class AsyncWebService implements Runnable {
        AsyncContext ctx;
        public AsyncWebService(AsyncContext ctx) {
             this.ctx = ctx;
        public void run() {
            // Invoke web service and save result in request attribute
            // Forward the request to render the result to a JSP. 
    If you would like to try it out use the nightly build of the GlassFish trunk and post any issues that you run into at the GlassFish webtier team monitors closely.