How to use a servlet as your main web page

Author: Neale Rudd, Metawerx

Date: 7-Aug-2007

On containers that implement Servlets 2.4, such as Tomcat 5.5 and above, it is possible to list servlets as welcome pages.

This makes it easy to use a servlet as the main web page for your site, instead of redirecting to a servlet from your index.jsp page or using similar work-arounds.

As with most Tomcat application configuration, the changes are made in <appName>/WEB-INF/web.xml.

Step by step

For this example, we will assume your servlet is in a package called com.examplecompany, and that the fully qualified class name is com.examplecompany.MyCMS.

• First, add a <servlet> element in your web.xml file if you haven't already added one.

<!-- Define the com.examplecompany.MyCMS servlet class, giving it the name MyCMS -->
<servlet>
	<servlet-name>MyCMS</servlet-name>
	<servlet-class>com.examplecompany.MyCMS</servlet-class>
</servlet>

• Next, we will add a <servlet-mapping> for this servlet, for the URL pattern /CMS. This allows us to access the servlet with the URI http://yoursite.com/CMS

<!-- Map the MyCMS name to the URI /CMS (main page for site) -->
<servlet-mapping>
	<servlet-name>MyCMS</servlet-name>
	<url-pattern>/CMS</url-pattern>
</servlet-mapping>

• Finally, we override the default <welcome-file-list> by providing our own list of welcome files.

<!-- The main page for the site will be the MyCMS servlet (http://website/CMS) -->
<welcome-file-list>
    <welcome-file>CMS</welcome-file>
    <welcome-file>index.html</welcome-file>
    <welcome-file>index.htm</welcome-file>
    <welcome-file>index.jsp</welcome-file>
</welcome-file-list>

How does this work?

When someone accesses your website, the following happens

• http://yoursite.com becomes http://yoursite.com/
• http://yoursite.com/ is a directory, so the welcome-file-list is scanned
• http://yoursite.com/CMS is the first welcome-file ("CMS" in the welcome-file-list), and there is a mapping of /CMS to the MyCMS servlet, so that servlet is accessed.

No URI mapping is defined for any folder except the root folder:

http://yoursite.com/CMS - this will work
http://yoursite.com/someFolder/CMS - this won't work

Therefore, if one of the other folders is accessed, one of the other files listed with <welcome-file> elements will be loaded, if it exists. Those files are index.html, index.htm, index.jsp. This is the standard behaviour of a fresh Tomcat installation, which is why we have included these above.

Important Notes

• In the above example, the welcome-file is specified as "CMS" not "/CMS". The first slash is added automatically, and should not be provided in the <welcome-file> element.
• In the same way, if your <url-pattern> was "/servlet/MyServlet", you would use "servlet/MyServlet", without the leading slash.

    <welcome-file>servlet/MyServlet</welcome-file>

• As the path for <welcome-file> is relative (and cannot be absolute), a servlet can only be used as the main page of the application, and not a welcome file for every folder. This is the same for other index files such as index.htm, in that they cannot refer to a single index.htm file, but instead cause Tomcat to search the specified folder for a file called "index.htm". Even if you map the servlet as *.foo, a <welcome-file> of index.foo will not work (at least in Tomcat versions up to and including 5.5.23 and 6.0.13). One workaround is to also specify a <url-pattern> mapping for /someFolder/MyServlet (where /someFolder is the folder you want to use the servlet in, and /MyServlet is your <url-pattern>). Another way to make the servlet work as a default for any folder is to change the Default Servlet instead.

Full Example

Here is a full example web.xml file

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
     version="2.4">

	<!-- ========================================================== -->
	<!-- General Info -->
	<!-- ========================================================== -->

	<display-name>My App</display-name>
	<description>
		My Application
	</description>


	<!-- ========================================================== -->
	<!-- CMS Servlet -->
	<!-- ========================================================== -->
	
	<!-- Define the com.examplecompany.MyCMS servlet class, giving it the name MyCMS -->
	<servlet>
		<servlet-name>MyCMS</servlet-name>
		<servlet-class>com.examplecompany.MyCMS</servlet-class>
	</servlet>
	<!-- Map the MyCMS name to the URI /CMS (main page for site) -->
	<servlet-mapping>
		<servlet-name>MyCMS</servlet-name>
		<url-pattern>/CMS</url-pattern>
	</servlet-mapping>
	
	
	<!-- ========================================================== -->
	<!-- Welcome Files -->
	<!-- ========================================================== -->

	<!-- The main page for the site will be the MyCMS servlet (http://website/CMS) -->
	<!-- No mapping is defined for other folders (http://website/someFolder/CMS), -->
	<!-- so one of the other files will be displayed (index.html, index.htm, index.jsp) -->
	<welcome-file-list>
	    <welcome-file>CMS</welcome-file>
	    <welcome-file>index.html</welcome-file>
	    <welcome-file>index.htm</welcome-file>
	    <welcome-file>index.jsp</welcome-file>
	</welcome-file-list>
    
</web-app>

How to use a Servlet as your main page in Servlets 2.3 and lower

If you are using servlets 2.3 or lower, you can point to a JSP file instead, and make that file redirect to your servlet. eg:

File redirect.jsp (where /CMS is mapped to your servlet, as in the above examples)

<%
    response.sendRedirect("http://yoursite.com/CMS");
%>

Welcome-file list in web.xml:

<!-- The main page for the site will be redirect.jsp servlet, which redirects -->
<!-- to the MyCMS servlet (http://yoursite.com/CMS) -->
<!-- No mapping is defined for other folders (http://website/someFolder/CMS), -->
<!-- so one of the other files will be displayed (index.html, index.htm, index.jsp) -->
<welcome-file-list>
    <welcome-file>redirect.jsp</welcome-file>
    <welcome-file>index.html</welcome-file>
    <welcome-file>index.htm</welcome-file>
    <welcome-file>index.jsp</welcome-file>
</welcome-file-list>

Troubleshooting

• Make sure you don't use leading slashes on your <welcome-file-list> files (eg: use CMS, not /CMS)
• If using the servlet in a <welcome-file-list>, make sure your web.xml version is 2.4 or above (see web.xml - DTD and XSD), and that you are using a 2.4 compliant container or above (eg: Tomcat 5.5 or above)

More Information

• Java Servlet 2.4 Specification
• web.xml Reference Guide