Skip to main content

Servlet 3.0 - from the source

Posted by mode on December 2, 2008 at 6:13 PM PST

Since the Early draft of the specification for Servlet 3.0 (JSR 315) the expert group has been working on refining and improving the specificaiton in a couple of areas - Ease of Development (EoD), pluggability and asynchronous support. Below is a description of things that are in the soon to be available public review to enable each of these features.

  • Ease of Development (Eod)

    In the early draft we added the annotations that allowed you to essentially write a Servlet as a POJO. However after some discussions in the expert group and feedback from some folks in the community, we decided to actually remove the method level annotations like @GET, @POST etc and keep the doGet, doPost method contracts and require extending an HttpServlet. However the top level annotations which are renamed for better usage in applications still exist. The @WebServlet annotation is used to declare a servlet, @ServletFilter to declare a filter and @WebServletContextListener to define ServletContextListeners. In addition to these annotations, other annotations like @Resource, which have been supported in web applications since Servlet 2.5 will continue to work as before. As an example a servlet declaration using Servlet 3.0 will now look like -

    public class MyServlet extends HttpServlet {
        public void doGet(...) {
  • Pluggability

    Web frameworks built on top of servlets are very popular for developers and there are a lot of them that address various different problems. In order to better support frameworks for developers writing webapps we are adding ways in the servlet 3.0 specification to make it easier to use and configure frameworks of their choice. There are a couple of ways that enable pluggability -

    • Methods to add Servlets and Filters - If a ServletContextListener is registered and wants to add a Servlet or Filter, then at the time of context initialization the event that is fired to the Listener can add Servlets and Filters to the context. The methods are addServlet and addFilter. For more details look for the javadocs when the specification is published.
    • Web.xml fragments - Instead of having just one monolithic web.xml that is used by the developer to declare servlets, filters and other configuration for using the framework, the framework can now include a web-fragment.xml with all it's configuration. A web-fragment is almost identical to the web.xml and can contain all the configuration needed by the framework in the META-INF directory of the framework's jar file. The container will use the information to assembe the descriptor for the application and the application needn't have to use any of the boilerplate configuration in their app for the framework. There are rules that are defined int the specification for conflict resolution, overriding and disabling fragment scanning. Along with the annotations which also can be in libraries the feature is very compelling not only for the developers that use frameworks but also for framework authors to be self sufficient in defining the configuration needed.
  • Asynchronous processing

    • This is the biggest change that we have made in the servlet 3.0 specification. In the early draft we had suspend and resume and certain semantics that were defined. However after the early draft the expert group had a lot of discussions on solving various use cases for asynchronous processing and the changes that are made to the specification in this area now also address the various use cases.
    • Instead of suspend and resume we now have a startAsync method on request and there are two variations of these. One that takes a request and response in which case the AsyncContext that is created when you call startAsync will be initialized with the request and response passed in. The other is a startAsync() that takes no parameters, in which case the AsyncContext is initialized with the original request and response. Also the Servlets and Filters that support asynchronous processing must be annotated appropriately with asyncSupport attribute set. It is illegal to call startAsync if anywhere in the request processing chain you have have a servlet or a filter that does not support async.
    • In addition to the AsyncContext there is also an AsyncListener that can be registered to get notifications on timeout and completion of async processing of a request. The event listener can be used to clean up resources if wrapped request and responses were used to initialize the AsyncContext.

Please take a look at the specification when it is published on the website and send us your feedback at

An early access implementation of some of the features are available in the GlassFish nightly build. For further discussion please post your questions about the implementation to

Jetty 7 pre-release also has some of the features implemented for those interested.

Look for more blogs about these features from my colleagues Shing Wai and Jan Luehe on specifics of some of the implementation.

Related Topics >>


whartung: Can you be more specific about the HTTP method and URL mapping? Do you mean the uri templating support?

kito75: Security enhancements are planned for the next release. However can you send me email to be more specific about "a usable security feature"?

So, it looks like we're still left without a usable security feature?

Actually, the real question is what incremental features could be added to the base Servlet API so that a developer could choose "raw" servlets instead of any framework whatsoever? For example, the HTTP Method and URL mapping feature of JAX-RS, but, say, without the content-type matching and conversion features.

mwessendorf: It is still in the plan. We hope to have it in the proposed final draft of the spec.

netsql: I will soon be writing an entry describing the async API. A lot of people have asked me the same question as you.

musketyr85: I recently was at a JUG and queriied the attendees to see how many people are still writing servlets and was quite surprised to see the number. However to answer your question - for JAX-RS to be able to support async for example one way it could do it is via using the underlying functionality in the container. If JAX-RS does not have any support for async (as is the case today) then what does a developer do?

Regarding the start async proposal, I think this is a much better concept than start resume. I have written HTTP server which uses a similar concept, however asynchronous processing is transparent from the outset. This form of processing also opens up the servlet container to parallelize requests on the same pipeline. As it allows HTTP request completion to drive dispatch of the next request, rather than service completion, and without any greater buffering demands. Performance is also much better than the conventional Servlet service model.

Are you guys planing to (finally) add a unified api/framework for uploads? Today... every damn web framework does it on its own... Please fix that

is startAsync to be used for comet a/ the asyncContext? Not resume ? Is there a draft document to look over? Sample code?

Sure. That are frameworks creators who will use servlets, but my queston was more on ordinal developers who don't write any frameworks. I was just curious whether you or your colleagues know some use cases where end user programmer would say "Hey, this cannot be done so easy with JAX-RS let's do it with old good servlet!"

musketyr85 - A LOT of frameworks build on the web container. JAX-RS also builds on the servlet container as one of the containers in the Java EE platform. So adding functionality to the underlying container will enable frameworks which will make developers lives easier. - Rajiv

Just one simple question :) What will be servlets good for since JAX-RS makes easier lot of servlet use cases? It looks like it will become lowend technology for framework creators only just like JDBC.