Deployment Descriptor is an XML document saved in a file called web.xml and placed in the folder WEB-INF in a web application archive. The DD is used to tell the component about the deployed components and is designed to decouple the resources and components in the application from their installation and configuration.  Deployment Descriptor is mainly used to declare servlets, their initialization parameters, specify mappings between URLs and their target components, provide declarative security, specifying MIME types and configuring JSP pages and documents, etc.

From the Servlet 2.5 specification, annotations can be defined on certain web components, such as servlets, filters, listeners, and tag handlers, instead of the xml tags in DD and hence, the standard web.xml deployment descriptor is optional now. 

This can be taken as a reference; you can come back and look into elements for which topics are not covered until now, once those topics are being discussed.

Basic syntax and the root element

DD is an XML file and hence follows the syntax rules of an XML document. DD XML is also described using a DTD or XML schema, like other XML documents.

The <web-app> element is the root element of a DD and all other elements come inside it.

Basic DD structure with an empty web-app element will look as below:

<?xml version="1.0" encoding="UTF-8"?>

<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

                xmlns="http://xmlns.jcp.org/xml/ns/javaee"

                xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"

                id="WebApp_ID" version="3.1">

 

</web-app>

Summary of child elements of web-app and their children

All the child elements of the web-app element are optional and can have any number of occurrences.

1.description

• provide a textual explanation of the parent element

• may also appear under other elements

2.display-name

• user-friendly name often displayed in tools and error reports

• may also appear under other elements

3.icon

• Used to reference and image that can be loaded by GUI tools and displayed to user.

• Generally icon images should be either in GIF or JPEG format as Java’s Image IO API contains processing of these formats by default.

• Two optional sub-elements

  • small-icon

  • large-icon

4.distributable

• if your application is distributable

• empty xml element and no sub-elements

5.context-param

• application-scoped initialization parameters

• Sub-elements

  • Optional(0 or more) description

  • Mandatory param-name

  • Mandatory param-value

6.filter

• Declare a filter

• Sub-elements

  • Optional(0 or more) description

  • Optional(0 or more) display-name

  • Optional(0 or more) icon

  • Mandatory filter-name

  • Mandatory filter-class is fully qualified class name of filter implementation.

  • Optional(0 or more) init-param

    • Optional(0 or more) description

    • Mandatory param-name

    • Mandatory param-value

7.filter-mapping

• Map filter to an url or servlet name to get invoked.

• Sub-elements

  • Mandatory filter-name matching a filter’s filter-name.

  • Either of mandatory url-pattern or servlet-name

  • Optional(0-4)  dispatcher can have four values to decide when to invoke the filter.

    • FORWARD

    • INCLUDE

    • REQUEST

    • ERROR

    • Default if no <dispatcher> elements are declared is REQUEST

8.listener

• Declare a listener

• Sub-elements

  • Optional(0 or more) description

  • Optional(0 or more) display-name

  • Optional(0 or more) icon

  • Mandatory listener-class is fully qualified class name of listener implementation.

9.servlet

• Declare a servlet

• Sub-elements

  • Optional(0 or more) description

  • Optional(0 or more) display-name

  • Optional(0 or more) icon

  • Mandatory servlet-name

  • Either of mandatory servlet-class or jsp-file is either is fully qualified class name of servlet class or with a context-relative path for the jsp file.

  • Optional(0 or more) init-param

    • ​Optional(0 or more) description

    • Mandatory param-name

    • Mandatory param-value

  • Optional(0 or 1) load-on-startup

    • Value can be 0 or positive to load the servlet as application is deployed.

    • Servlets with lover values are loaded before servlets with larger values

    • If negative value or element not present, container may load whenever it want.

  • Optional(0 or 1) run-as is a security related element.

  • Optional(0 or 1) async-supported if the servlet support asynchronous communication.

  • Optional(0 or more) security-role-ref is a security related element.

  • Optional(0 or 1) multipart-config tell the container that instances of the Servlet expect requests that conform to the multipart/form-data MIME type.

    • Optional location is the directory location where files will be stored. Default is “”.

    • Optional max-file-size i the maximum size allowed for uploaded files. The default is -1L, which means unlimited.

    • Optional max-request-size is the maximum size allowed for multipart/form-data requests. The default is -1L, which means unlimited.

    • Optional file-size-threshold is the size threshold after which the file will be written to disk. Default is 0 which means files will be immediately written without caching.

       

10.servlet-mapping

• Sub-elements

  • Mandatory servlet-name

  • Mandatory url-pattern is the url-pattern that will cause the servlet to be invoked.

11.session-config

• Sub-elements

  • Optional(0 or 1) session-timeout is timeout in minutes.

    • If 0 or negative, sessions will never timeout,

    • If element is omitted, java ee server can use its own values and average is usually around 30 minutes.

12.mime-mapping

• Java EE server usually provides default mapping for all common file formats

• Sub-elements

  • Mandatory extension (E.g. txt)

  • Mandatory mime-type (E.g. text/plain)

13.welcome-file-list

• A set of default file names to be loaded when request is made to a directory path

• Sub-elements

  • Mandatory (One or more) welcome-file

14.error-page

• Provide mapping between an error code or Java exception type and a path to a resource in the web application that needs to be displayed in case of that error/exception.

• Sub-elements

  • Either of mandatory error-code or exception-type is either an HTTP error code or a fully qualified java exception type.

  • Mandatory location is context-relative url to the error page or servlet.

15.jsp-config

• Normally only one instance in the DD

• Sub-elements

  • Optional(0 or more) description

  • Optional(0 or more) display-name

  • Optional(0 or more) icon

  • Optional(0 or more) taglib is used to specify the location of tag library to be used globally and is one of the many ways to reference a tag library.

    • Mandatory taglib-uri is a unique URI for the tag library

    • Mandatory taglib-location is context relative location of the TLD file

  • Optional(0 or more) jsp-property-group per JSP group (JSPs are configured per group). Individual JSPs may override through page directive.

    • Optional(0 or more) description

    • Optional(0 or more) display-name

    • Optional(0 or more) icon

    • Mandatory (One or More) url-pattern is url pattern to which all JSPs in a group conform and there may be multiple url patterns.

    • Optional(0 or 1) el-ignored is used to disable (true) or enable (false) EL parsing and default is true (disabled).

    • Optional(0 or 1) page-encoding is character encoding used in JSP.

    • Optional(0 or 1) scripting-invalid is used to disable java based coding in JSPs and default is false (enabled).

    • Optional(0 or 1) is-xml if it is a JSP document and not traditional JSP page.

    • Optional(0 or 1) include-prelude is context-relative path to be included as a header.

    • Optional(0 or 1)  include-coda is context-relative path to be included as a footer.

16.security-constraint

17.login-config

18.security-role

19.env-entry

20.ejb-ref

21.ejb-local-ref

22.service-ref

23.resource-ref

24.resource-env-ref

25.message-destination-ref

26.message-destination

27.locale-encoding-mapping-list

Important Notes

• Web.xml might be removed in a future javaee version in favor of annotations. However at least till Java EE 7 it is not removed and having a look at these elements will help you learn corresponding annotations easily.

• Security related elements will be explained later.

• Elements related to ejb and other areas which do not fit into the Web Component Developer exam are not explained here.