Generic Top

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:


1. Overview

In this tutorial, we’re creating a Java web application using Servlet 3.0+.

We’ll take a look at three annotations – @WebServlet, @WebFilter, and @WebListener – that can help us nix our web.xml files.

2. The Maven Dependency

In order to use these new annotations, we need to include the javax.servlet-api dependency:


3. XML Based Configuration

Before Servlet 3.0, we’d configure a Java web application in a web.xml file:

<web-app xmlns=""

Let’s start replacing each configuration section with the respective annotations introduced in Servlet 3.0.

4. Servlets

JEE 6 shipped with Servlet 3.0 which enables us to use annotations for servlet definitions, minimizing the use of a web.xml file for a web application.

For example, we can define a servlet and expose it with the @WebServlet annotation

Let’s define one servlet for the URL pattern /uppercase. It will transform the value of the input request parameter to uppercase:

@WebServlet(urlPatterns = "/uppercase", name = "uppercaseServlet")
public class UppercaseServlet extends HttpServlet {
    public void doGet(HttpServletRequest request, HttpServletResponse response) 
      throws IOException {
        String inputString = request.getParameter("input").toUpperCase();

        PrintWriter out = response.getWriter();

Note that we defined a name for the servlet (uppercaseServlet) that we can now reference. We’ll make use of this in the next section.

With the @WebServlet annotation, we’re replacing the servlet and servlet-mapping sections from the web.xml file.

5. Filters

A Filter is an object used to intercept requests or responses, performing pre- or post-processing tasks.

We can define a filter with the @WebFilter annotation.

Let’s create a filter to check if the input request parameter is present:

@WebFilter(urlPatterns = "/uppercase")
public class EmptyParamFilter implements Filter {
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse,
      FilterChain filterChain) throws IOException, ServletException {
        String inputString = servletRequest.getParameter("input");

        if (inputString != null && inputString.matches("[A-Za-z0-9]+")) {
            filterChain.doFilter(servletRequest, servletResponse);
        } else {
            servletResponse.getWriter().println("Missing input parameter");

    // implementations for other methods

With the @WebFilter annotation, we’re replacing the filter and filter-mapping sections from the web.xml file.

6. Listeners

We’ll often need to trigger actions based on certain events. This is where listeners come to the rescue. These objects will listen for an event and execute the behavior we specify.

Like previously, we can define a listener with the @WebListener annotation.

Let’s create a listener that counts each time we perform a request to the server. We’ll implement ServletRequestListener, listening for ServletRequestEvents:

public class RequestListener implements ServletRequestListener {
    public void requestDestroyed(ServletRequestEvent event) {
        HttpServletRequest request = (HttpServletRequest)event.getServletRequest();
        if (!request.getServletPath().equals("/counter")) {
            ServletContext context = event.getServletContext();
            context.setAttribute("counter", (int) context.getAttribute("counter") + 1);

    // implementations for other methods

Note that we are excluding the requests to the URL pattern /counter.

With the @WebListener annotation, we’re replacing the listener section from the web.xml file.

7. Build and Run

For those following along, note that for testing, there’s a second servlet we’ve added for the /counter endpoint that simply returns the counter servlet context attribute.

So, let’s use Tomcat as the application server.

If we are using a version of maven-war-plugin prior to 3.1.0, we’ll need to set the property failOnMissingWebXml to false.

Now, we can deploy our .war file to Tomcat, and access to our servlets.

Let’s try out our /uppercase endpoint:

curl http://localhost:8080/spring-mvc-java/uppercase?input=texttouppercase


And we should also see how our error handling looks:

curl http://localhost:8080/spring-mvc-java/uppercase

Missing input parameter

And finally, a quick test of our listener:

curl http://localhost:8080/spring-mvc-java/counter

Request counter: 2

8. XML Still Needed

Even, with all the features introduced in Servlet 3.0, there are some use cases where we’ll still need a web.xml file, among them:

  • We can’t define the filter order with annotations – we still need the <filter-mapping> section if we have multiple filters that we need to be applied in a particular order
  • To define a session timeout, we still need to use the <session-config> section
  • We still need the <security-role> element for container-based authorization
  • And to specify welcome files, we’ll still need a <welcome-file-list> section

Or, Servlet 3.0 also introduced some programmatic support via ServletContainerInitializer, too, which can also fill in some of these gaps.

9. Conclusion

In this tutorial, we configured a Java web Application without using the web.xml file by exercising the equivalent annotations.

As always, the source code for this tutorial can be found on GitHub. Additionally, an application using the traditional web.xml file can also be found on GitHub.

For a Spring-based approach, head over to our tutorial web.xml vs. Initializer with Spring.

Generic bottom

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2: