<welcome-file-list>

This tag is the container for one or more <welcome-file> tags, listed in order of preference.

Welcome files show when no filename is provided in the URL.

For example:

http://yoursite.com/
http://yoursite.com/somefolder

Tomcat checks the welcome file list, and tries to find each file listed.

Important Warning

Caution: Using this tag overrides the server's default welcome-file-list from <jakarta>/conf/web.xml. If you use it, make sure you also include all page names you want to use. It is normal practise to copy the default list from the server's web.xml file, and add your own pages to the list, according to your preference.

Your web.xml entry will completely override the default settings. It will not add to the list. Therefore, only the pages you specify will be used.

Default Settings (add your own pages/servlets to this list)

Tomcat's default welcome-file-list looks like this:

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

How to add a new <welcome-file> element

Copy the above into your own web.xml, so that the Tomcat defaults still apply, then add your new entry at the top or bottom.

The following example will display a Flash page called default.swf if it exists. If it doesn't exist, index.html will be displayed (and so on).

<welcome-file-list>
    <welcome-file>default.swf</welcome-file>
    <welcome-file>index.html</welcome-file>
    <welcome-file>index.htm</welcome-file>
    <welcome-file>index.jsp</welcome-file>
</welcome-file-list>

How to use a servlet in the welcome file list

Since Servlets 2.4, servlets can also be used in the welcome-file-list. See How to use a servlet as your main web page for more information and a full example.

How does Tomcat decide which page to display?

The rules Tomcat uses are as follows:

• The list of files in your welcome-file-list are checked in order
• If no welcome-file-list was specified, the list of files from the server's default web.xml are checked in order
• If no suitable files are found, and the directory listings feature is enabled, a directory listing is displayed
• If directory listings are disabled, a 404 error occurs (which may in turn display the page you have specified using the <error-page> tag).

See Also

• Tomcat's Directory Listings Feature
• Enabling or Disabling Directory Listings using web.xml
• How to use a servlet as your main web page