5.2. The Order of Elements within the Deployment Descriptor

Not only are XML elements case sensitive, they are also sensitive to the order in which they appear within other elements. For example, the XML header must be the first entry in the file, the DOCTYPE declaration must be second, and the web-app element must be third. Within the web- app element, the order of the elements also matters. Servers are not required to enforce this ordering, but they are permitted to, and some do so in practice, completely refusing to run Web applications that contain elements that are out of order. This means that web.xml files that use nonstandard element ordering are not portable.

Core Approach Be sure to correctly order the elements that appear within web-app .

The following list gives the required ordering of all legal elements that can appear directly within the web- app element. For example, the list shows that any servlet elements must appear before any servlet-mapping elements. If there are any mime-mapping elements, they must go after all servlet and servlet-mapping elements but before welcome-file- list. Remember that all these elements are optional. So, you can omit any element but you cannot place it in a nonstandard location.

• icon. The icon element designates the location of either one or two image files that an IDE or GUI tool can use to represent the Web application. For details, see Section 5.11 (Documenting Web Applications).

• display-name. The display-name element provides a name that GUI tools might use to label this particular Web application. See Section 5.11.

• description. The description element gives explanatory text about the Web application. See Section 5.11.

• distributable. The distributable element tells the system that it is safe to distribute the Web application across multiple servers. See Section 5.15 .

• context- param. The context-param element declares application-wide initialization parameters. For details, see Section 5.5 (Initializing and Preloading Servlets and JSP Pages).

• filter. The filter element associates a name with a class that implements the javax.servlet.Filter interface. For details, see Section 5.6 (Declaring Filters).

• filter-mapping. Once you have named a filter, you associate it with one or more servlets or JSP pages by means of the filter-mapping element. See Section 5.6.

• listener. Version 2.3 of the servlet API added support for event listeners that are notified when the session or servlet context is created, modified, or destroyed. The listener element designates the event listener class. See Section 5.14 for details.

• servlet. Before you assign initialization parameters or custom URLs to servlets or JSP pages, you must first name the servlet or JSP page. You use the servlet element for that purpose. For details, see Section 5.3.

• servlet-mapping. Servers typically provide a default URL for servlets: http://host/webAppPrefix/servlet/ServletName. However, you often change this URL so that the servlet can access initialization parameters (Section 5.5 ) or more easily handle relative URLs (Section 4.5). When you do change the default URL, you use the servlet- mapping element to do so. See Section 5.3.

• session- config. If a session has not been accessed for a certain period of time, the server can throw it away to save memory. You can explicitly set the timeout for individual session objects by using the setMaxInactiveInterval method of HttpSession, or you can use the session-config element to designate a default timeout. For details, see Section 5.10.

• mime-mapping. If your Web application has unusual files that you want to guarantee are assigned certain MIME types, the mime-mapping element can provide this guarantee. For more information, see Section 5.12.

• welcome-file-list. The welcome-file-list element instructs the server what file to use when the server receives URLs that refer to a directory name but not a filename. See Section 5.7 for details.

• error-page. The error-page element lets you designate the pages that will be displayed when certain HTTP status codes are returned or when certain types of exceptions are thrown. For details, see Section 5.8.

• taglib. The taglib element assigns aliases to Tag Library Descriptor files. This capability lets you change the location of the TLD files without editing the JSP pages that use those files. See Section 5.13 for more information.

• resource-env-ref. The resource-env-ref element declares an administered object associated with a resource. See Section 5.15.

• resource-ref. The resource-ref element declares an external resource used with a resource factory. See Section 5.15.

• security-constraint. The security- constraint element lets you designate URLs that should be protected. It goes hand-in-hand with the login-config element. See Section 5.9 for details.

• login-config. You use the login-config element to specify how the server should authorize users who attempt to access protected pages. It goes hand-in-hand with the security-constraint element. See Section 5.9 for details.

• security-role. The security- role element gives a list of security roles that will appear in the role- name subelements of the security-role-ref element inside the servlet element. Declaring the roles separately could make it easier for advanced IDEs to manipulate security information. See Section 5.9 for details.

• env- entry. The env-entry element declares the Web application’s environment entry. See Section 5.15.

• ejb- ref. The ejb-ref element declares a reference to the home of an enterprise bean. See Section 5.15 .

• ejb-local- ref. The ejb-local-ref element declares a reference to the local home of an enterprise bean. See Section 5.15.