Recipe 3.1 Mapping a Servlet to a Name in web.xml

Problem

You want to create an alias, or servlet path , to your servlet.

Solution

Create servlet and servlet-mapping elements in web.xml .

Discussion

Creating an alias to the servlet takes place in the deployment descriptor's servlet-mapping element. All se rvlet elements must come before any of the servlet-mapping elements in the servlet 2.3 web.xml deployment descriptor. The servlet-mapping element refers to the name of the servlet that appears in the servlet-name element, such as:

 <servlet><servlet-name>myservlet</servlet-name></servlet>

This is referred to as the servlet's registered name . The servlet-mapping then provides the name, or URL pattern , which web application users can type into their browsers to access the servlet. Example 3-1 shows a web.xml file with a servlet and servlet-mapping element. The registered name in this case is "CookieServlet".

Example 3-1. servlet and servlet-mapping elements

 <?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>   <servlet>     <servlet-name>CookieServlet</servlet-name>     <servlet-class>com.jspservletcookbook.CookieServlet</servlet-class>    </servlet>    <servlet-mapping>      <servlet-name>CookieServlet</servlet-name>      <url-pattern>/cookieservlet</url-pattern>    </servlet-mapping> </web-app>

In this example, the servlet element registers the name "CookieServlet" by using the servlet-name element. The class name is specified by the servlet-class element. The actual location of this servlet class may be WEB-INF/classes/com/jspservletcookbook/ , or inside a JAR file that resides in WEB-INF/lib . "CookieServlet" becomes the registered name by which the servlet com.jspservletcookbook.CookieServlet is referred to in the rest of the web.xml file.

Now create the servlet path by which the web application users will access this servlet in their web browsers. This aliasing is accomplished with the servlet-mapping element. servlet-name identifies the registered name by which the servlet is referred to in web.xml , and the url-pattern element creates the URL that is used to access this servlet. The / character inside the /cookieservlet pattern means "begin at the web-application root." For example, if the context path for the site http://www.mysite.org is "cookbook," then the complete address for accessing the CookieServlet servlet is http://www.mysite.org/cookbook/cookieservlet . The /cookbook part of the URL is the context path for your web application. The servlet is then identified with the /cookieservlet pattern within that context.

Looking at this more generally , you have the following URL for any given servlet:

 http://<host>:<port>/<context path>/<servlet-path>

Most servlet containers allow for a default context , where the context path is / . In this case, the URL is in this form:

 http://<host>:<port>/<servlet-path>

For example, if you are using Tomcat 4.1.x on your local machine and have created an application called "myapp" and a servlet URL pattern of /myservlet , the entire web address for that servlet looks like http://localhost:8080/myapp/myservlet .

You can also access a servlet with a URL like this:

 http://host:port/context path/servlet/registered-servlet-name

So if the registered servlet name was "MyServlet," then the request appears as http://localhost:8080/myapp/servlet/MyServlet .

Some servlet engines use a different servlet path than /servlet , and others allow this path to be changed by an administrator. You should consult the documentation for your servlet container to ensure the correct path for your setup. What if the example servlet-mapping element appeared in the web.xml file for the server's default web application, in which the context path is / ? In this case, users would access the CookieServlet servlet by using the address http://www.mysite.org/cookieservlet .

The url-pattern that you create for a servlet inside of a servlet-mapping element is case-sensitive in Tomcat and WebLogic. According to Chapter SRV.11.1 of the servlet v2.3 specification and v2.4 proposed final draft, "The container must use case-sensitive string comparisons for matching." If the user requests http://www.mysite.org/cookbook/cookieSERVLET instead of http://www.mysite.org/cookbook/cookieservlet , then the request is not directed to the mapped servlet ( CookieServlet ). In Tomcat 4.1.x and WebLogic 7.0, the request returns an HTTP 404 error code, which is the "File not found" type error returned by a web server.

The url-pattern inside the servlet-mapping element can take on different forms, which are discussed in the upcoming recipes.

Recipe 3.1 Mapping a Servlet to a Name in web.xml