Java Servlet & JSP Cookbook

Problem

You want to configure one or more welcome files for a web application.

Solution

Use a welcome-file-list element in your deployment descriptor.

Discussion

A welcome file is a tradition as old as the hypertextual Internet. Many sites have homepages or other welcome files that are designed to be the entry page or front door for their web sites. These pages usually have names like index.html , welcome.html , or default.html . You can configure your web application to direct requests toward these pages by adding a welcome-file-list element to your web application's deployment descriptor. Set up a welcome file list in web.xml in the manner demonstrated by Example 3-12. The welcome-file-list element must come after any servlet and servlet-mapping elements, and precede any error-page or taglib elements in the servlet 2.3 deployment descriptor.

Example 3-12. Setting up welcome files in web.xml

<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-application_2_3.dtd" > <web-app> <!-- Define servlets and servlet-mappings here --> <welcome-file-list> <welcome-file>index.html</welcome-file> <welcome-file>default.jsp</welcome-file> </welcome-file-list> </web-app>

Whenever the servlet container encounters a URL for a web application that specifies only a directory, not a particular filename or servlet, then it looks for a welcome-file-list element in the application's deployment descriptor. The servlet v2.3 specification calls these kinds of URLs valid partial requests . The servlet container attaches any welcome filenames that it finds in web.xml to the request (in the order that they appear in web.xml ) and returns those files to the client.

For example, let's say Tomcat receives a request for http://www.mysite.org/cookbook/ . Also imagine that the web.xml file for the cookbook web application contains the welcome-file-list shown in Example 3-12. Tomcat then returns http://www.mysite.org/cookbook/index.html if that file exists; if it does not, Tomcat looks for the default.jsp file in the cookbook directory and returns that file instead.

The servlet container initiates this search in response to any directory-style URL that it receives (such as http://www.mysite.org/cookbook/ bookinfo / ). In other words, as long as an index.html or default.jsp (or whichever filenames you choose) exists in a web application's root directory, and the web developer has properly configured the welcome-file-list element, then those files are invoked by default in response to directory-style requests.

See Also

Chapter 1 on web.xml ; Recipe 3.1-Recipe 3.6; Recipe 3.9; Chapter 11 of the Servlet v2.3 and 2.4 specifications on mapping requests to servlets.