Using Servlet 3.0 Async Features in Grails 2.0

I was talking to someone last week about the new support for Servlet 3.0 async features in Grails 2 and realized I didn’t know that much about what was available. So I thought I’d try it out and share some examples. The documentation is a little light on the subject, so first some background information.

The primary hook to do asynchronous work in the 3.0 spec is the new startAsync method in the javax.servlet.ServletRequest class. This returns an instance of the javax.servlet.AsyncContext interface which has lifecycle methods such as dispatch and complete, gives you a hook back to the request and response, and lets you register an javax.servlet.AsyncListener. You call the start method passing in a Runnable to do the asynchronous work. Using this approach frees up server resources instead of blocking, which increases scalability since you can handle more concurrent requests.

In order to use this however the servlet that handles the request must support async, and all applied filters in the filter chain must too. The main Grails servlet (GrailsDispatcherServlet) is registered in the 3.0 version of the web.xml template with the async-supported attribute set to true. And Servlet3AsyncWebXmlProcessor adds <async-supported>true</async-supported> to all filter declarations in web.xml after it’s generated. So that’s covered for you; there is no required web.xml configuration on your part.

You also have to be configured to use servlet API 3.0. This is simple to do; just change the value of grails.servlet.version to “3.0” from the default value of “2.5”. Note that there is a legacy setting in with the name app.servlet.version; you should delete this line from your file since its value is ignored and overridden at runtime by the value from BuildConfig.groovy.

You don’t call startAsync on the request from a controller though; call startAsync directly on the controller. This method is added as a controller method (wired in as part of the controllers’ AST transforms from ControllersAsyncApi (by ControllerAsyncTransformer if you’re curious)). It’s important to call the controller’s startAsync method because it does all of the standard work but also adds Grails integration. This includes adding the logic to integrate all registered PersistenceContextInterceptor instances, e.g. to bind a Hibernate Session to the thread, flush when finished, etc., and also integrates with Sitemesh. This is implemented by returning an instance of
GrailsAsyncContext which adds the extra behavior and delegates to the real instance provided by the container (e.g. org.apache.catalina.core.AsyncContextImpl in Tomcat) for the rest.

Therer are a few other new async-related methods available in the request; they include boolean isAsyncStarted() and AsyncContext getAsyncContext().

I’ve attached a sample application (see below for the link) to demonstrate these features. There are two parts; a simple controller that looks up stock prices asynchronously, and a chat application.

StockController is very simple. It just has a single action and suspends to look up the current stock price for the requested stock ticker. It does this asynchronously but it’s typically very fast, so you probably won’t see a real difference from the serial approach. But this pattern can be generalized to doing more time-consuming tasks.

Call http://localhost:8080/asynctest/stock/GOOG, http://localhost:8080/asynctest/stock/AAPL, http://localhost:8080/asynctest/stock/VMW, etc. to test it.

The second example is more involved and is based on the “async-request-war” example from the Java EE 6 SDK. This implements a chat application (it was previously implemented with Comet). The SDK example is one large servlet; I split it up into a controller to do the standard request work and the ChatManager class (registered as a Spring bean in resources.groovy) to handle client registration, message queueing and dispatching, and associated error handling.

The implementation uses a hidden iframe which initiates a long-running request. This never completes and is used to send messages back to each registered client. When you “login” or send a message, the controller handles the request and queues a response message. ChatManager then cycles through each registered AsyncContext and sends JSONP to the iframe which updates a text area in the main page with incoming messages.

One thing that hung me up for quite a while was that things worked fine with the SDK example but not mine. Everything looked good but messages weren’t being received by the iframe. It turns out this is due to the optimizations that are in place to make response rendering as fast as possible. Unfortunately this resulted in flush() calls on the response writer being ignored. Since we need responsive updates and aren’t rendering a large page of html, I added code to find the real response that’s wrapped by the Grails code and send directly to that.

Try it out by opening http://localhost:8080/asynctest/ in two browsers. Once you’re “logged in” to both, messages sent will be displayed in both browsers.

Some notes about the test application:

  • All of the client logic is in web-app/js/chat.js
  • grails-app/views/chat/index.gsp is the main page; it creates the text area to display messages and the hidden iframe to stay connected and listen for messages
  • This requires a servlet container that implements the 3.0 spec. The version of Tomcat provided by the tomcat plugin and used by run-app does, and all 7.x versions of Tomcat do.
  • I ran install-templates and edited web.xml to add metadata-complete="true" to keep Tomcat from scanning all jar files for annotated classes – this can cause an OOME due to a bug that’s fixed in version 7.0.26 (currently unreleased)
  • Since the chat part is based on older code it uses Prototype but it could easily use jQuery

You can download the sample application code here.

4 Responses to “Using Servlet 3.0 Async Features in Grails 2.0”

  1. Antoine says:

    Great article! Wanted to note that if you have an existing grails app on 2.0/2.0.1 you will want to update the servlet version in the build config before installing your templates. Or reinstall your templates to get the correct web.xml with servlet version 3.0. As of grails 2.0.1 it looks like metadata-complete=”true” is included by default.

  2. I did a presentation last week for work about the new Grails 2 features and wasn’t clear on exactly how one would use the async features. This post and sample app were exactly what I needed to get a better sense of how these features worked. Thanks for writing this up Burt!!

  3. Ime says:

    I just ran the example. A major problem is that the web age keeps refreshing,or so it seems. If the user presses Esc,the app collapses.Do u see this as well? (both in chrome and ff)

  4. John says:

    I upgraded the sample to grails 2.2 and tried it. I had to add the line “app.servlet.version=3.0” to the file to get the sample to work on this newer version. The interaction between and BuildConfig.groovy continues to confuse me.

Creative Commons License
This work is licensed under a Creative Commons Attribution 3.0 License.