|[ Team LiB ]|
Recipe 1.5 Creating the Deployment Descriptor
Name the XML file web.xml and place it in the WEB-INF directory of your web application. If you do not have an existing example of web.xml, then cut and paste the examples given in the servlet v2.3 or 2.4 specifications and start from there.
The deployment descriptor is a very important part of your web application. It conveys the requirements for your web application in a concise format that is readable by most XML editors. The web.xml file is where you:
This is just a subset of the configurations that you can use with web.xml. While a number of chapters in this book contain detailed examples of web.xml (refer to the "See Also" section), this recipe shows simplified versions of the servlet v2.3 and v2.4 deployment descriptors.
Example 1-3 shows a simple web application with a servlet, a filter, a listener, and a session-config element, as well as an error-page configuration. The web.xml in Example 1-3 uses the servlet v2.3 Document Type Definition (DTD). The main difference between the deployment descriptors of 2.3 and 2.4 is that 2.3 uses a DTD and 2.4 is based on an XML schema. You'll notice that the old version of web.xml has the DOCTYPE declaration at the top of the file, while the 2.4 version uses the namespace attributes of the web-app element to refer to the XML schema. The XML elements of Example 1-3 have to be in the same order as specified by the DTD.
<?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> <display-name>Servlet 2.3 deployment descriptor</display-name> <filter> <filter-name>RequestFilter</filter-name> <filter-class>com.jspservletcookbook.RequestFilter</filter-class> </filter> <filter-mapping> <filter-name>RequestFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping> <listener> <listener-class>com.jspservletcookbook.ReqListener</listener-class> </listener> <servlet> <servlet-name>MyServlet</servlet-name> <servlet-class>com.jspservletcookbook.MyServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name> MyServlet </servlet-name> <url-pattern>/myservlet</url-pattern> </servlet-mapping> <session-config> <session-timeout>15</session-timeout> </session-config> <error-page> <error-code>404</error-code> <location>/err404.jsp</location> </error-page> </web-app>
Example 1-3 shows the web.xml file for an application that has just one servlet, accessed at the path <context path>/myservlet. Sessions time out in 15 minutes with this application. If a client requests a URL that cannot be found, the web container forwards the request to the /err404.jsp page, based on the error-page configuration. The filter named RequestFilter applies to all requests for static and dynamic content in this context. At startup, the web container creates an instance of the listener class com.jspservletcookbook.ReqListener.
Everything about Example 1-4 is the same as Example 1-3, except that the web-app element at the top of the file refers to an XML schema with its namespace attributes. In addition, elements can appear in arbitrary order with the servlet v2.4 deployment descriptor. For instance, if you were so inclined you could list your servlets and mappings before your listeners and filters.
<?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"> <!-- the rest of the file is the same as Example 1-3 after the web-app opening tag --> </web-app>
Chapter 2 on deploying servlets and JSPs; Chapter 3 on naming servlets; Chapter 9 on configuring the deployment descriptor for error handling; the J2EE tutorial from Sun Microsystems: http://java.sun.com/j2ee/tutorial/1_3-fcs/doc/J2eeTutorialTOC.html.
|[ Team LiB ]|