One of the most common tasks that you perform in web.xml is declaring names and mapping custom URLs to your servlets or JSP pages. You use the servlet element to assign names; you use the servlet-mapping element to associate custom URLs with the names just assigned.
Assigning Names
To provide initialization parameters, define a custom URL, or assign a logical (porta- ble) security role to a servlet or JSP page, you must first give the servlet or page a name. You assign a name by means of the servlet element. The most common for- mat includes servlet-name and servlet-class subelements (inside the web-app element), as follows:
<servlet>
<servlet-name>Test</servlet-name>
<servlet-class>coreservlets.TestServlet</servlet-class>
</servlet>
This means that the servlet at WEB-INF/classes/coreservlets/TestServlet is now
known by the registered name Test. Giving a servlet a name has the following major implications: Initialization parameters, custom URL patterns, and other customiza- tions refer to the servlet by the registered name, not by the class name. We see how to take advantage of these features later on in this chapter.
For example, Listing 2.1 shows a simple servlet called TestServlet1 that resides in the coreservlets package. Because the servlet is part of a Web application rooted in a directory named deployDemo,TestServlet1.class is placed in deployDemo/
WEB-INF/classes/coreservlets. Listing 2.2 shows a portion of the web.xml file that
would be placed in deployDemo/WEB-INF. This web.xml file uses the servlet-name andservlet-class elements to associate the name Test1 with TestServlet1.class.
Listing 2.1 TestServlet1.java
package coreservlets;
import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
/** Simple servlet used to illustrate servlet naming * and custom URLs.
*/
public class TestServlet1 extends HttpServlet { public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType("text/html");
PrintWriter out = response.getWriter();
String uri = request.getRequestURI();
out.println("<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.0 " + "Transitional//EN\">" + "\n" +
"<HTML>\n" + "<HEAD><TITLE>" +
"Test Servlet 1" + "</TITLE></HEAD>\n" + "<BODY BGCOLOR=\"#FDF5E6\">\n" +
"<H2>" + "Servlet Name: Test1" + "</H2>\n" + "<H2>URI: " + uri + "</H2>\n" +
"</BODY></HTML>");
} }
Defining Custom URLs
To assign a custom URL, you use the servlet-mapping element along with its servlet-name and url-pattern subelements. The servlet-name element specifies the name that was assigned to the servlet using the servlet-name subele- ment of the servlet element; url-pattern describes a URL relative to the Web application root. The value of the url-pattern element must begin with either a slash (/) or an asterisk and period combination (*.).
Core Approach
The value of url-pattern must begin with either / or *..
The specification allows you to map a servlet to a particular custom URL. For exam- ple, here is a simple web.xml excerpt that lets you use the URL http://host/webApp-
Prefix/UrlTest1 to invoke TestServlet1 declared with the name Test1. Figure 2–1 shows the result of invoking TestServlet1 with the exact-matching URL.
<servlet>
<servlet-name>Test1</servlet-name>
<servlet-class>coreservlets.TestServlet1</servlet-class>
</servlet>
Listing 2.2 web.xml (Excerpt showing servlet name)
<?xml version="1.0" encoding="ISO-8859-1"?>
<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">
<!-- Register the name "Test1" for TestServlet1. -->
<servlet>
<servlet-name>Test1</servlet-name>
<servlet-class>coreservlets.TestServlet1</servlet-class>
</servlet>
<!-- ... -->
</web-app>
<servlet-mapping>
<servlet-name>Test1</servlet-name>
<url-pattern>/UrlTest1</url-pattern>
</servlet-mapping>
Figure 2–1 TestServlet1 invoked with http://localhost/deployDemo/UrlTest1.
Exact-Match Patterns
The previous example showed an exact-match pattern: the url-pattern element specified an address beginning with a slash that did not contain *. The associated servlet will be invoked when the part of the incoming URL that is after the Web application prefix (but before the attached GET data, if any) exactly matches the URL pattern.
Here are a couple more examples using exact matching. Listing 2.3 shows an excerpt from web.xml declaring and mapping TestServlet2 and TestServlet3 using exact-matching URL patterns. Figures 2–2 and 2–3 show the results of invok- ing these servlets with their respective URLs.
Listing 2.3 web.xml (Excerpt showing exact matching)
<?xml version="1.0" encoding="ISO-8859-1"?>
<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">
Figure 2–2 TestServlet2 invoked with http://localhost/deployDemo/UrlTest2/.
<!-- Register the name "Test2" for TestServlet2. -->
<servlet>
<servlet-name>Test2</servlet-name>
<servlet-class>coreservlets.TestServlet2</servlet-class>
</servlet>
<!-- Use the URL http://host/webAppPrefix/UrlTest2/ -->
<servlet-mapping>
<servlet-name>Test2</servlet-name>
<url-pattern>/UrlTest2/</url-pattern>
</servlet-mapping>
<!-- Register the name "Test3" for TestServlet3. -->
<servlet>
<servlet-name>Test3</servlet-name>
<servlet-class>coreservlets.TestServlet3</servlet-class>
</servlet>
<!-- Use the URL http://host/webAppPrefix/UrlTest3.asp -->
<servlet-mapping>
<servlet-name>Test3</servlet-name>
<url-pattern>/UrlTest3.asp</url-pattern>
</servlet-mapping>
<!-- ... -->
</web-app>
Listing 2.3 web.xml (Excerpt showing exact matching) (continued)
Figure 2–3 TestServlet3 invoked with http://localhost/deployDemo/
UrlTest3.asp.
Multimapping Patterns
In the majority of cases, you want to assign one URL to each servlet. Once in a while, however, you want multiple URLs to invoke the same servlet. There are two ways you can accomplish this multimapping:
• By giving a url-pattern of /directoryName/*, you can specify that all URLs of the form http://host/webAppPrefix/directoryName/
blah are handled by the designated servlet.
• By giving a url-pattern of *.foo, you can specify that all URLs of the form http://host/webAppPrefix/.../blah.foo are handled by the designated servlet.
Details follow.
Here is an excerpt from web.xml showing a mapping that lets you use URLs like
http://host/webAppPrefix/UrlTest4, http://host/webAppPrefix/UrlTest4/ (note the
slash at the end), http://host/w ebAppPrefix/UrlTest4/foo/bar to invo ke
TestServlet4 declared with the name Test4. Figures 2–4, 2–5, and 2–6 show the results of invoking TestServlet4 with these URLs, respectively.
<servlet>
<servlet-name>Test4</servlet-name>
<servlet-class>coreservlets.TestServlet4</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Test4</servlet-name>
<url-pattern>/UrlTest4/*</url-pattern>
</servlet-mapping>
Figure 2–4 TestServlet4 invoked with http://localhost/deployDemo/UrlTest4.
Figure 2–5 TestServlet4 invoked with http://localhost/deployDemo/UrlTest4/.
Figure 2–6 TestServlet4 invoked with http://localhost/deployDemo/UrlTest4/
foo/bar.
Likewise, you can use * if you want all URLs ending with a certain extension to invoke a particular servlet. For example, here is an excerpt from web.xml that lets
you use URLs like http://host/webAppPrefix/foo/bar/baz.urlTest5, http://host/
webAppPrefix/foo.urlTest5 to invoke TestServlet5 declared with the name Test5. Figures 2–7 and 2–8 show the results of invoking TestServlet5 with these URLs, respectively.
<servlet>
<servlet-name>Test5</servlet-name>
<servlet-class>coreservlets.TestServlet5</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Test5</servlet-name>
<url-pattern>*.urlTest5</url-pattern>
</servlet-mapping>
Figure 2–7 TestServlet5 invoked with http://localhost/deployDemo/foo/bar/
baz.urlTest5.
Figure 2–8 TestServlet5 invoked with http://localhost/deployDemo/
foo.urlTest5.
Matching Overlapping Patterns
When mapping a servlet to a URL, the specification does not allow the same value of url-pattern to appear twice within the same web.xml file. Thus, there can never be an overlap between two patterns that map exact matches. However, if one or more servlet mappings use “*”, an overlap could occur.
Compliant servers are required to use the following rules to resolve these overlaps.
• Exact matches are handled first. Thus, if /foo/bar and /foo/*
were both url-pattern entries, the first would take precedence for a request URL of http://host/webAppPrefix/foo/bar. Similarly, /foo/bar.html would win over *.html for an incoming URL of
http://host/webAppPrefix/foo/bar.html.
• Directory mappings are preferred over extension mappings.
Thus, if /foo/* and *.html were both url-pattern entries, the first would take precedence for a request URL of http://host/
webAppPrefix/foo/bar.html.
• For overlapping directory mappings, the longest path is preferred. Thus, if /foo/bar/* and /foo/* were both
url-pattern entries, the first would take precedence for a request URL of http://host/webAppPrefix/foo/bar/baz.html.
Naming JSP Pages
Because JSP pages get translated into servlets, it is natural to expect that you can name JSP pages just as you can name servlets. After all, JSP pages might benefit from initialization parameters, security settings, or custom URLs, just as regular servlets do. Although it is true that JSP pages are really servlets behind the scenes, there is one key difference: You don’t know the actual class name of JSP pages (because the system picks the name). So, to name JSP pages, you substitute the jsp-file ele- ment for the servlet-class element, as follows:
<servlet>
<servlet-name>PageName</servlet-name>
<jsp-file>/WEB-INF/jspPages/TestPage.jsp</jsp-file>
</servlet>
Thejsp-file element specifies the location of the JSP page relative to the Web application root directory. Although anything placed inside of WEB-INF is protected from direct access, it is the server, not the client, that will be resolving this path, so you are allowed to specify a location inside WEB-INF.
Generally, JSP pages do not need to be declared inside web.xml. They can be invoked like any other static resource (e.g., somePage.html), provided you place them outside of WEB-INF. However, there are times when you might still want to declare a name for a JSP page. Declaring a name for a JSP page allows you to provide
a name to use with customization settings (e.g., initialization parameters and security settings) and so that you can change the URL that invokes the JSP page (e.g., so that multiple URLs get handled by the same page or to remove the .jsp extension from the URL). However, when setting initialization parameters, remember that JSP pages read initialization parameters by using the jspInit method, not the init method. See Section 2.6 (Initializing and Preloading Servlets and JSP Pages) for details.
For example, Listing 2.4 is a simple JSP page named TestPage.jsp that just prints out the local part of the URL used to invoke it. Listing 2.5 shows a portion of the
web.xml file (i.e., deployDemo/WEB-INF/web.xml) used to assign a registered name of PageName and then to associate that registered name with URLs of the form
http://host/webAppPrefix/UrlTest7/anything. Figure 2–9 shows the result for the URL http://localhost/deployDemo/UrlTest7/foo.
Listing 2.4 TestPage.jsp
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD><TITLE>JSP Test Page</TITLE></HEAD>
<BODY BGCOLOR="#FDF5E6">
<H2>TestPage.jsp<br/>
URI: <%= request.getRequestURI() %></H2>
</BODY></HTML>
Listing 2.5 web.xml (Excerpt illustrating the naming of JSP pages)
<?xml version="1.0" encoding="ISO-8859-1"?>
<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">
<!-- Register the name "PageName" for TestPage.jsp -->
<servlet>
<servlet-name>PageName</servlet-name>
<jsp-file>/WEB-INF/jspPages/TestPage.jsp</jsp-file>
</servlet>
<!-- Use the URL http://host/webAppPrefix/UrlTest7/foo -->
<servlet-mapping>
<servlet-name>PageName</servlet-name>
<url-pattern>/UrlTest7/*</url-pattern>
</servlet-mapping>
<!-- ... ->
</web-app>
Figure 2–9 TestPage.jsp invoked with http://localhost/deployDemo/UrlTest7/foo.