Asynchronous Support in Servlet 3.0
By edort on Nov 30, 2009
One of the significant enhancements made in JSR 315: Java Servlet 3.0, is support for asynchronous processing. With this support, a servlet no longer has to wait for a response from a resource such as a database before its thread can continue processing, that is, the thread is not blocked. Previous to Servlet 3.0, asynchronous support in the Java EE web container was provided in a proprietary way — either through APIs built on top of the Servlet 2.5 API or through non-Servlet APIs or implementations.
In modern web applications there are times when you need to asynchronously handle some part of the request, so that the web container can continue serving other requests in a seamless fashion. One example is a chat room application. In this type of application you want to enable long-lived client connections with a servlet. You don't want a server thread to be blocked for a long period of time serving a request from a single client. You want the servlet to process a request from the client and then free up the server thread as quickly as possible for other work. In other words, you want the request to be processed and a response generated asynchronously.
With the upcoming release of the Servlet 3.0 specification, standard asynchronous support has been added to the Servlet API. This Tech Tip introduces the asynchronous support that has been added to the Servlet API in Java Servlet 3.0 technology. It also includes a sample application that demonstrates those features.
Asynchronous Support Features
The primary features of the asynchronous support in Servlet 3.0 are as follows.
Servlet 3.0 introduces the use of annotations as an alternative to deployment descriptors
for servlet-related configuration in a web application. Two of these annotations are
@WebServlet, which defines a servlet,
@WebFilter, which defines a servlet filter. Both of these annotations include an attribute,
asyncSupported attribute to
true, declares that the servlet or servlet filter supports asynchronous
processing. For example, the following annotation defines a servlet in a web application and declares that the servlet supports
asyncSupported attribute is needed to differentiate code written for synchronous processing from that written for use in
an asynchronous context. In fact, for an application to use the asynchronous feature, the entire request processing chain must have
the have this attribute set either through the annotation or in its deployment descriptor. An IllegalStateException will be thrown
if an application tries to start an asynchronous operation and there is a servlet or servlet filter in the request processing chain
that does not support asynchronous processing.
Servlet Request Methods
The support for asynchronous processing also includes new
ServletRequest methods, such as
getAsyncContext(). After you set the
asyncSupported attribute in the request processing chain to support asynchronous processing, you call either the
startAsync(servletRequest, servletResponse) or
startAsync() method to make an asynchronous request.
Here, for example, is a call that makes an asynchronous request:
The difference between the two
startAsync method signatures is that the
startAsync() method implicitly uses
the original request and response, while the
startAsync(servletRequest, servletResponse) method uses the request and response
objects passed in the method call. The request and response passed in the call can be wrapped by filters or other servlets earlier in the
request processing chain. Notice that the
startAsync method returns an
AsyncContext object —
see AsyncContext Class for more details. The
AsyncContext object is initialized appropriately
with the request and response objects depending on the method used. You must exercise caution when wrapping the response and calling the
no arguments signature of the
startAsync() method. You could lose the data if any of data is written to the wrapped
response and not flushed to the underlying response stream.
There are a few more methods in the
ServletRequest class that are part of the support for asynchronous processing.
isAsyncStarted() You can use these convenience methods in an application
to determine if asynchronous operations are supported or started on a request.
AsyncContext class is a new class in Servlet 3.0 that provides the execution context for an asynchronous operation.
The class provides a variety of methods that you can use to get access to the underlying request and response objects.
For example, you can use the
AsyncContext.dispatch(servletContext, path) method to dispatch the request to the container. Using any of the
dispatch methods, enables the processing to return to the container after the asynchronous operation that was started on the
completed — for instance, after waiting for a call to a web service to return. These methods dispatch the request back to the container
so you can use frameworks such as JavaServer Pages (JSP) to generate the response.
dispatch() method, that is, the method with no arguments, forwards the request back to the original URL.
Also, if a call to
RequestDispatcher.forward occurs after an asynchronous context
has been initialized, the
dispatch() method forwards the request to the path for the
dispatch(path) method forwards the request to the path relative to the context of the request.
dispatch(ServletContext, path) method forwards the request to the path relative to the specified context.
For example, here is a call that forwards the request back to the container so that the JSP framework can generate the response.
complete(), completes the asynchronous operation that was started on the request that
was used to initialize this
AsyncContext object. It closes the response that was used to initialize this
object. You can call this method, for example, when the response generated by the asynchronous operation is complete.
The container can also implicitly call this method if the application dispatches the request back to the container using the
method with no subsequent
startAsync call on the request.
Asynchronous Listener Class
Servlet 3.0 also adds a new listener class for asynchronous processing,
AsyncListener. You can use this class in an
application to get notified when asynchronous processing is completed, if a timeout has occurred, an error has occurred, or a subsequent call
startAsync has occurred. The following code snippet creates a new
AsyncListener object and uses it to
get notified when an asynchronous processing operation is completed .
Notice that the parameter passed to the
onComplete method is an
AsyncEvent object. The
AsyncEvent class is another new class provided as part of the Servlet 3.0 support for asynchronous processing.
It represents an event that gets fired when the asynchronous operation initiated on a
has completed, timed out, or produced an error.
A Simple Application That Uses the Asynchronous Support in Servlet 3.0
Now that you've seen the key features in the Servlet 3.0 support for asynchronous processing, let's look at a more complete example. The following shows the code for a simple web application. In the application, a servlet makes an asynchronous request to a web service, waits for the call to return, and then dispatches the request back to the container to render the result using JSP. Note that the complete code for servlet is not shown.
One of the sample applications provided with the Java EE 6 SDK is a chat application that uses the asynchronous support in Servlet 3.0.
To run the application, do the following:
- If you haven't already done so, download the Java EE 6 SDK. Also be sure to have an installed version of the Java Platform Standard Edition (Java SE) 6 SDK.
- Download the sample application, async-request-war.war
- Start the GlassFish v3 application server that is packaged with the Java EE 6 SDK by entering the
<javaee_home>is where you installed the Java EE 6 SDK.
- Deploy the sample application by copying it to the
- Execute the application by opening two browser windows. For simplicity, let's call them say Browser A and Browser B.
- Point both Browser A and Browser B to the URL http://localhost:8080/async_request_war. In response, you should see a chat user interface (UI) in each browser window. The UI presents a text area to view chat entries, a text field to enter a user ID, and a Login button.
- In Browser A, enter a user name, say "userA", in the text field and click the Login button. You should see
the following message appear in the text area:
System Message: userA has joined.
Login as "userB" in Browser B. You should see the following message appear in both browser windows:
System Message: userB has joined.
Now, you're ready to chat.
- In Browser A, enter "Hello" in the text box and click the Post Message button.
You should see the following message in both Browser A and Browser B:
- In Browser B, enter "Hello" in the text box and click the Post Message button.
You should see the following message in both Browser A and Browser B:
You can view the source code for the application in the
For more information, see the following resources:
About the Author
Rajiv Mordani is a senior staff engineer at Sun Microsystems. He was part of the original J2EE platform team and has worked on a wide variety of server-side XML and web technologies, including Jakarta Tomcat and most recently Java Servlet 3.0. Rajiv is currently the specification lead for Servlet 3.0. Read his blog.