5.1. Defining the Header and Root Elements

The deployment descriptor, like all XML files, must begin with an XML header. This header declares the version of XML that is in effect and gives the character encoding for the file.

A DOCTYPE declaration must appear immediately after the header. This declaration tells the server the version of the servlet specification (e.g., 2.2 or 2.3) that applies and specifies the Document Type Definition (DTD) that governs the syntax of the rest of the file.

The top- level (root) element for all deployment descriptors is web-app. Remember that XML elements, unlike HTML elements, are case sensitive. Consequently, Web-App and WEB-APP are not legal; you must use web-app in lower case.

Core Warning XML elements are case sensitive.

Thus, the web.xml file should be structured as follows for Web apps that will run in servlet 2.2 containers (servers) or that will run in 2.3 containers but not make use of the new web.xml capabilities (e.g., filter or listener declarations) introduced in version 2.3.

 <?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE web-app PUBLIC "-//Sun
Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds
/web-app_2_2.dtd"> <web-app>
<!-- Other elements go here. All are optional. --> </web-app> 

Rather than typing in this template by hand, you can (and should) download an example from http://www.moreservlets.com or copy and edit the version that comes in the default Web application of whatever server you use. However, note that the web.xml file that is distributed with Allaire JRun 3 (e.g., in install_dir/servers/default/default-app/WEB-INF for JRun 3.0 or the samples directory for JRun 3.1) incorrectly omits the XML header and DOCTYPE line. As a result, although JRun accepts properly formatted web.xml files from other servers, other servers might not accept the web.xml file from JRun 3. So, if you use JRun 3, be sure to insert the header and DOCTYPE lines.

Core Warning The web.xml file that is distributed with JRun 3 is illegal; it is missing the XML header and DOCTYPE declaration.

If you want to use servlet/JSP filters, application life-cycle listeners, or other features specific to servlets 2.3, you must use the servlet 2.3 DTD, as shown in the web.xml file below. Of course, you must also use a server that supports this version of the specification—version 4 of Tomcat, JRun, or ServletExec, for example. Just be aware that your Web application will not run in servers that support only version 2.2 of the servlet API (e.g., version 3 of Tomcat, JRun, or ServletExec).

 <?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> <!-- Other elements go here. All are optional. --> </web-app>