5.3. Assigning Names and Custom URLs
One of the most common tasks that you perform in web.xml is giving names and 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 name just assigned.
Assigning Names
In order to provide initialization parameters, define a custom URL, or assign a 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 format includes servlet-name and servlet- class subelements (inside the web-app element), as follows.
<servlet> <servlet-name>Test</servlet- name> <servlet-class>moreservlets.TestServlet</servlet-class> </servlet>
This means that the servlet at WEB-INF/classes/moreservlets/TestServlet is now known by the registered name Test. Giving a servlet a name has two major implications. First, initialization parameters, custom URL patterns, and other customizations refer to the servlet by the registered name, not by the class name. Second, the name can be used in the URL instead of the class name. Thus, with the definition just given, the URL http://host/webAppPrefix/servlet/Test can be used in lieu of http://host/webAppPrefix/servlet/moreservlets.TestServlet.
Remember: not only are XML elements case sensitive, but the order in which you define them also matters. For example, all servlet elements within the web-app element must come before any of the servlet-mapping elements that are introduced in the next subsection, but before the filter or documentation-related elements (if any) that are discussed in Sections 5.6 and 5.11. Similarly, the servlet-name subelement of servlet must come before servlet-class. Section 5.2 (The Order of Elements within the Deployment Descriptor) describes the required ordering in detail.
|
For example, Listing 5.1 shows a simple servlet called TestServlet that resides in the moreservlets package. Since the servlet is part of a Web application rooted in a directory named deployDemo, Test Servlet.class is placed in deployDemo/WEBINF/classes/moreservlets. Listing 5.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 and servlet-class elements to associate the name Test with TestServlet.class.
Figures 5-1 and 5-2 show the results when TestServlet is invoked by means of the default URL and the registered name, respectively.
Figure 5-1. TestServlet when invoked with the default URL.
Figure 5-2. TestServlet when invoked with the registered name.
Listing 5.1. TestServlet.java
package moreservlets;
import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
/** Simple servlet used to illustrate servlet naming
* and custom URLs.
*/
public class TestServlet 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(ServletUtilities.headWithTitle("Test Servlet") +
"<BODY BGCOLOR="#FDF5E6">
" +
"<H2>URI: " + uri + "</H2>
" +
"</BODY></HTML>");
}
} |
Listing 5.2. web.xml (Excerpt showing servlet name)
<?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-app_2_3.dtd">
<web-app>
<!-- ... -->
<servlet>
<servlet-name>Test</servlet-name>
<servlet-class>moreservlets.TestServlet</servlet-class>
</servlet>
<!-- ... -->
</web-app> |
Defining Custom URLs
Most servers have a default URL for servlets: http://host/webAppPrefix/servlet/packageName.ServletName. Although it is convenient to use this URL during development, you often want a different URL for deployment. For instance, you might want a URL that appears in the top level of the Web application (e.g., http://host/webAppPrefix/AnyName), without the servlet entry in the URL. A URL at the top level simplifies the use of relative URLs, as described in Section 4.5 (Handling Relative URLs in Web Applications). Besides, top-level URLs are shorter and simply look better to many developers than the long and cumbersome default URLs.
In fact, sometimes you are required to use a custom URL. For example, you might turn off the default URL mapping so as to better enforce security restrictions or to prevent users from accidentally accessing servlets that have no init parameters. This idea is discussed further in Section 5.4 (Disabling the Invoker Servlet). If you disable the default URL, how do you access the servlet? Only by using a custom URL.
To assign a custom URL, you use the servlet-mapping element along with its servlet-name and url-pattern subelements. The servlet-name element provides an arbitrary name with which to refer to the servlet; url-pattern describes a URL relative to the Web application root. The value of the url-pattern element must begin with a slash (/).
Here is a simple web.xml excerpt that lets you use the URL http://host/webAppPrefix/UrlTest instead of either http://host/webAppPrefix/servlet/Test or http://host/webAppPrefix/servlet/moreservlets.TestServlet. Figure 5-3 shows a typical result. Remember that you still need the XML header, the DOCTYPE declaration, and the enclosing web-app element as described in Section 5.1 (Defining the Header and Root Elements). Furthermore, recall that the order in which XML elements appears is not arbitrary. In particular, you are required to put all the servlet elements before any of the servlet-mapping elements. For a complete breakdown of the required ordering of elements within web-app, see Section 5.2 (The Order of Elements within the Deployment Descriptor).
Figure 5-3. TestServlet invoked with a URL pattern.
<servlet> <servlet-name>Test</servlet-name> <servlet-class>moreservlets.TestServlet</servlet-class> </servlet> <!-- ... --> <servlet-mapping> <servlet-name>Test</servlet-name> <url-pattern>/UrlTest</url-pattern> </servlet-mapping>
The URL pattern can also include wildcards. For example, the following snippet instructs the server to send to all requests beginning with the Web app’s URL prefix (see Section 4.1, “ Registering Web Applications ”) and ending with.asp to the servlet named BashMS.
<servlet> <servlet-name>BashMS</servlet-name> <servlet-class>msUtils.ASPTranslator</servlet-class> </servlet> <!-- ... --> <servlet-mapping> <servlet-name>BashMS</servlet-name> <url-pattern>/*.asp</url-pattern> </servlet-mapping>
Naming JSP Pages
Since 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 (since the system picks the name). So, to name JSP pages, you substitute the jsp-file element for the servlet-class element, as follows.
<servlet>
<servlet-name>PageName</servlet-name>
<jsp-file>/TestPage.jsp</jsp-file>
</servlet> You name JSP pages for exactly the same reason that you name servlets: 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 5.5 (Initializing and Preloading Servlets and JSP Pages) for details.
For example, Listing 5.3 is a simple JSP page named TestPage.jsp that just prints out the local part of the URL used to invoke it. TestPage.jsp is placed in the top level of the deployDemo directory. Listing 5.4 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/UrlTest2/anything. Figures 5-4 through 5-6 show the results for the URLs http://localhost/deployDemo/TestPage.jsp (the real name), http://localhost/deployDemo/servlet/PageName (the registered servlet name), and http://localhost/deployDemo/UrlTest2/foo/bar/baz.html (a URL matching url-pattern), respectively.
Figure 5-4. TestPage.jsp invoked with the normal URL.
Figure 5-5. TestPage.jsp invoked with the registered servlet name.
Listing 5.3. TestPage.jsp
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <HTML> <HEAD><TITLE>JSP Test Page</TITLE></HEAD> <BODY BGCOLOR="#FDF5E6"> <H2>URI: <%= request.getRequestURI() %></H2> </BODY></HTML> |
Listing 5.4. web.xml (Excerpt illustrating the naming of JSP pages)
<?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-app_2_3.dtd">
<web-app>
<!-- ... -->
<servlet>
<servlet-name>PageName</servlet-name>
<jsp-file>/TestPage.jsp</jsp-file>
</servlet>
<!-- ... -->
<servlet-mapping>
<servlet-name>PageName</servlet-name>
<url-pattern>/UrlTest2/*</url-pattern>
</servlet-mapping>
<!-- ... -->
</web-app> |