web.xml Deployment Descriptor in Java Servlets – Beginner’s Guide

Introduction

When working with Java Servlets, you will often hear about a file called web.xml.
This file plays a crucial role in configuring how your web application behaves.

Even though modern Servlets support annotations, web.xml is still important, especially for:

Understanding legacy projects
Advanced configuration
Interviews and real-world enterprise apps

This guide explains web.xml from scratch, with simple language, examples, and explanations.

What Is web.xml?

Definition:

web.xml is a deployment descriptor file used in Java web applications to define configuration and mapping information.

In simple words:

web.xml tells the web server how your application should run.

Where Is web.xml Located?

In a standard Java web application:

YourProject
 └── WEB-INF
      └── web.xml

The WEB-INF folder is not directly accessible from the browser, making it secure.

Why Is web.xml Used?

web.xml is used to configure:

Servlet names and URL mappings
Welcome pages
Initialization parameters
Session timeout
Filters and listeners
Error pages
Security constraints

Before annotations existed, all servlet configuration was done using web.xml.

Role of web.xml in Java Web Architecture

Browser
   ↓
Tomcat Server
   ↓
web.xml (Configuration Rules)
   ↓
Servlet / JSP
   ↓
Response

Tomcat reads web.xml first, then decides:

Which servlet to call
What URL pattern to match
How to manage sessions

Basic Structure of web.xml

A minimal web.xml file looks like this:

<?xml version="1.0" encoding="UTF-8"?>

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         version="4.0">

</web-app>

All configurations go inside <web-app>.

Defining a Servlet in web.xml

Step 1: Declare the Servlet

<servlet>
    <servlet-name>HelloServlet</servlet-name>
    <servlet-class>com.example.servlet.HelloServlet</servlet-class>
</servlet>

Explanation:

servlet-name → Logical name
servlet-class → Full Java class path

Mapping a Servlet to a URL

Step 2: Map the Servlet

<servlet-mapping>
    <servlet-name>HelloServlet</servlet-name>
    <url-pattern>/hello</url-pattern>
</servlet-mapping>

This means the servlet runs at:

http://localhost:8080/YourApp/hello

Complete Servlet Configuration Example

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         version="4.0">

    <servlet>
        <servlet-name>HelloServlet</servlet-name>
        <servlet-class>com.example.servlet.HelloServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>HelloServlet</servlet-name>
        <url-pattern>/hello</url-pattern>
    </servlet-mapping>

</web-app>

Welcome File Configuration

You can define the default page when the app loads:

<welcome-file-list>
    <welcome-file>index.html</welcome-file>
    <welcome-file>index.jsp</welcome-file>
</welcome-file-list>

This runs when user visits:

http://localhost:8080/YourApp/

Servlet Initialization Parameters

Define Parameters in `web.xml`

<servlet>
    <servlet-name>ConfigServlet</servlet-name>
    <servlet-class>com.example.ConfigServlet</servlet-class>

    <init-param>
        <param-name>username</param-name>
        <param-value>admin</param-value>
    </init-param>
</servlet>

These parameters are read in the servlet using Java code.

Session Timeout Configuration

<session-config>
    <session-timeout>30</session-timeout>
</session-config>

Session expires after 30 minutes of inactivity.

web.xml vs Annotations

Feature	`web.xml`	Annotations
Configuration Style	XML-based	Code-based
Readability	Centralized	Distributed
Modern Usage	Less common	More common
Legacy Support	Required	Limited
Interview Importance	High	Medium

Both are important to understand.

Real-Life Analogy

Think of a Rule Book

Servlets → Employees
web.xml → Company rules
Tomcat → Manager

Employees work according to rules written in web.xml.

Best Practices

Use annotations for simple projects
Use web.xml for centralized configuration
Keep XML clean and readable
Comment complex configurations
Restart server after modifying web.xml