Deployment Descriptors (web.xml)

What is a Deployment Descriptor — and Why Does it Still Exist?

A deployment descriptor is an XML file, living at WEB-INF/web.xml inside a WAR, that tells the servlet container how to wire up an application — which classes are servlets, which URLs map to them, what filters run and in what order, how sessions and security are configured. Before Servlet 3.0 (2009), this file was mandatory — there was no other way to register a servlet at all. Annotations removed that requirement for the common case, but XML configuration didn't disappear: it remains the only mechanism for a handful of things annotations genuinely can't express, and it's essential for reading and maintaining the large body of Java EE applications written before annotations existed.

// BEFORE Servlet 3.0 — mandatory, and this is the ENTIRE registration
<servlet>
    <servlet-name>productServlet</servlet-name>
    <servlet-class>com.shop.ProductServlet</servlet-class>
</servlet>
<servlet-mapping>
    <servlet-name>productServlet</servlet-name>
    <url-pattern>/products</url-pattern>
</servlet-mapping>

// AFTER Servlet 3.0 — the same registration, one line, no XML at all
@WebServlet("/products")
public class ProductServlet extends HttpServlet { /* ... */ }

Structure and Namespace

mywebapp.war
└── WEB-INF/
    └── web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
                             https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
         version="6.0">

    <display-name>Shop Catalog Service</display-name>
    <!-- Configuration goes here -->

</web-app>

Configuring Servlets and Filters

Servlet registration with init parameters

<servlet>
    <servlet-name>reportServlet</servlet-name>
    <servlet-class>com.shop.ReportServlet</servlet-class>
    <init-param>
        <param-name>maxResults</param-name>
        <param-value>100</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>   <!-- lower number = higher startup priority -->
</servlet>
<servlet-mapping>
    <servlet-name>reportServlet</servlet-name>
    <url-pattern>/reports/*</url-pattern>
</servlet-mapping>

Filter chain — execution order is declaration order, and that's the whole rule

<!-- Filters execute in EXACTLY the order they appear in this file -->
<filter>
    <filter-name>encodingFilter</filter-name>
    <filter-class>com.shop.EncodingFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>encodingFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

<filter>
    <filter-name>authFilter</filter-name>
    <filter-class>com.shop.AuthFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>authFilter</filter-name>
    <url-pattern>/secure/*</url-pattern>
</filter-mapping>

File uploads — multipart configuration

<multipart-config>
    <max-file-size>5242880</max-file-size>        <!-- 5 MB per file -->
    <max-request-size>20971520</max-request-size> <!-- 20 MB total request -->
    <file-size-threshold>0</file-size-threshold>  <!-- 0 = write to disk immediately, don't buffer in memory -->
</multipart-config>
// Relevant for something like uploading a product image in an admin panel —
// without an explicit limit, a single oversized upload can exhaust memory
// or disk before your own validation code ever runs.

Session Configuration

<session-config>
    <session-timeout>30</session-timeout>   <!-- minutes; 0 = never expires — almost never what you want -->
    <cookie-config>
        <name>SHOPSESSIONID</name>
        <http-only>true</http-only>
        <secure>true</secure>
    </cookie-config>
    <tracking-mode>COOKIE</tracking-mode>   <!-- never URL rewriting — it exposes the session ID in logs, referrers, history -->
</session-config>

Container-Managed Security — Legacy, Superseded by Spring Security

The Servlet specification defines its own declarative authentication and authorization mechanism, configured entirely in web.xml. It's presented here for completeness and for maintaining applications that still use it — modern Spring applications use Spring Security's SecurityFilterChain (see Authentication vs Authorization) instead, which is more flexible and is where new development should live.

<security-constraint>
    <web-resource-collection>
        <web-resource-name>Admin Area</web-resource-name>
        <url-pattern>/admin/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>admin</role-name>
    </auth-constraint>
    <user-data-constraint>
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>   <!-- requires HTTPS -->
    </user-data-constraint>
</security-constraint>

<login-config>
    <auth-method>FORM</auth-method>
    <form-login-config>
        <form-login-page>/login.html</form-login-page>
        <form-error-page>/login-error.html</form-error-page>
    </form-login-config>
</login-config>

<security-role><role-name>admin</role-name></security-role>

<!-- login.html — these exact names are REQUIRED by the servlet spec,
     not a convention you can rename -->
<form action="j_security_check" method="POST">
    <input type="text" name="j_username" required>
    <input type="password" name="j_password" required>
</form>

Error Pages

<error-page>
    <error-code>404</error-code>
    <location>/WEB-INF/errors/not-found.html</location>
</error-page>

<error-page>
    <exception-type>java.lang.Throwable</exception-type>
    <location>/WEB-INF/errors/generic-error.jsp</location>   <!-- catch-all -->
</error-page>

Context Parameters and Listeners

<context-param>
    <param-name>maxUploadSize</param-name>
    <param-value>10485760</param-value>
</context-param>

// Accessing it:
ServletContext context = getServletContext();
String maxUpload = context.getInitParameter("maxUploadSize");

<listener>
    <listener-class>com.shop.InventorySyncListener</listener-class>
</listener>

web.xml → Modern Equivalent, Element by Element

Every capability above still exists in modern Spring applications — it just moved from XML into annotations and configuration properties. This table is the direct translation, useful both for reading legacy code with a modern mental model and for knowing exactly what to search for when a piece of inherited XML needs to be ported forward.

Best Practices and Common Pitfalls

Interview Questions