Recipe 3.1 Mapping a Servlet to a Name in web.xml
You want to create an alias, or servlet path , to your servlet.
Create servlet and servlet-mapping elements in web.xml .
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:
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:
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:
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 inside the servlet-mapping element can take on different forms, which are discussed in the upcoming recipes.
Chapter 1 on web.xml ; Recipe 3.2-Recipe 3.8; Chapter 11 of the Servlet v2.3 and 2.4 specifications on mapping requests to servlets.