Welcome File List in web.xml

The web page that comes, when we give a request to the web application (host:port/webapp/directory) is called the home page or welcome page, or landing page. We can configure HTML/Servlet/JSP components as a welcome file list in the deployment descriptor (web.xml) file.

The welcome file list mechanism allows us to specify a list of files that the web container will use for appending to a request for a URL (called a valid partial request) that is not mapped to a web component.

The tag used to configure welcome file in web.xml is:- <welcome-file-list> and <welcome-file>

Example:- We have multiple HTML files, Servlet components in our web application. After giving a request to the web application host:port/webapp/directory, we want to display the index.html file. Then it can be configured as,


We can also configure the servlet component as a welcome file, but we should take its URL pattern without “/” as a welcome file.

If we don’t configure any welcome file in the deployment descriptor (web.xml) file then the web application will run without a home page.

Multiple Welcome File in web.xml

We can also configure more than one welcome file for our web application. Generally, we configure more than one welcome file for backup purposes. So that if one welcome is not available then another welcome file will take place. 

The home page of the web application is the one of most important pages in our web application, end-users will enter the web application through the homepage. Therefore we must use more than one welcome file for backup purposes.


When multiple welcome files are configured then web container will pick up the welcome file based on,

  1. Order of availability.
  2. Order of configuration done in <welcome-file-list> 

In the above example, the index.html file is available then it will become the welcome file. If the index.html file is not available then the next configured home.jsp will become the welcome file. Similarly, if the first and second configured welcome files are not available then the third input.html will become the welcome file, and so on. In all cases, the remaining files will act as backup files.

Default Welcome File

If no welcome file is specified, the Application Server will use a file named index.extension, where the extension can be HTML or JSP, as the default welcome file. Example:- index.httml, or index.jsp

For example:- In the tomcat server, If no welcome file is configured then index.html or index.jsp will be taken as a welcome file. If both index.html and index.jsp are available then the tomcat web server will give first priority to index.html and second priority to index.jsp. 

If explicitly configured welcome files are available and default welcome files are also available then explicit configure welcome files will be picked up by the tomcat server.

Note:- Other servers may or may not support the default welcome file feature.

Example Application

You can verify the above points by developing a simple Java based web application. The directory structure will be,

   |=> home.html
   |=> index.html
   |=> index.jsp
   |=> input.jsp
   |=> WEB-INF
      |=> classes
         |=> TestServlet.java

See the above Java web application code developed using Eclipse IDE at GitHub.

home.html File,

// home.html
   <h1 style='text-align: center'>home.html File</h1>

index.html File,

// index.html
   <h1 style='text-align: center'>index.html File</h1>

index.jsp File,

// index.jsp
   <h1 style='text-align: center'>index.jsp File</h1>

input.jsp File,

// input.jsp
   <h1 style='text-align: center'>input.jsp File</h1>

Servlet Component (TestServlet.java),

// TestServlet.java
package com.kp.servlet;

import java.io.IOException;
import java.io.PrintWriter;

import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServlet;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

public class TestServlet extends HttpServlet {
   public void doGet(HttpServletRequest req, HttpServletResponse resp) 
         throws ServletException, IOException {
      PrintWriter pw = resp.getWriter();
      pw.println("<h1 style='text-align: center'>TestServlet</h1>");

Now, the deployment descriptor (web.xml) file for the above file can be written as given below,

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  "http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
  id="WebApp_ID" version="4.0">




Give request to web application through http://localhost:8080/WelcomeFile/


  • When multiple welcome files are configured, then the welcome file will be picked on the order of configuration and the availability in the web application.
  • If no welcome file is configured then Servlet Container looks to takes either index.jsp or index.html as the default welcome file, if both files are available then index.html gets high priority.
  • If explicitly configured welcome files are available along with default welcome files in the web application then the explicit configured welcome file will be taken as a welcome file.
  • If explicitly configured welcome files are not physically available in the web application, but default welcome files are available in web application then the web application runs without welcome file.
  • We can configure the servlet component as the welcome file by specifying its URL pattern as the welcome file.

If you enjoyed this post, share it with your friends. Do you want to share more information about the topic discussed above or do you find anything incorrect? Let us know in the comments. Thank you!

Leave a Comment

Your email address will not be published. Required fields are marked *