Common Elements of web.xml

The <description>, <display-name>, and <icon> elements can occur in several places as subelements of other elements within web.xml.

<description>

The <description> element appears in a number of places within the web.xml file to provide a description of its parent element.

<display-name>

The <display-name> element contains a short name for its parent element and is displayed by graphical user interface (GUI) tools.

<icon>

The <icon> element references icons that will be used by a GUI tool to represent its parent element. It contains the following:

An optional <small-icon> element containing the location within the application of a 1616 pixel icon
An optional <large-icon> element containing the location within the application of a 3232 pixel icon

<web-app>: Root Element

The <web-app> element is the root element of the web.xml file. This means that every web.xml file must contain one and only one such element, and all other elements must be contained within it. It contains the following:

An optional <icon> element
An optional <display-name> element
An optional <description> element
An optional <distributable> element
Zero or more <context-param> elements
Zero or more <filter> elements
Zero or more <filter-mapping> elements
Zero or more <listener> elements
Zero or more <servlet> elements
Zero or more <servlet-mapping> elements
An optional <session-config> element
Zero or more <mime-mapping> elements
An optional <welcome-file-list> element
Zero or more <error-page> elements
Zero or more <jsp-config> elements
Zero or more <resource-env-ref> elements
Zero or more <resource-ref> elements
Zero or more <security-constraint> elements
An optional <login-config> element
Zero or more <security-role> elements
Zero or more <env-entry> elements
Zero or more <ejb-ref> elements
Zero or more <ejb-local-ref> elements
Zero or more <service-ref> elements
Zero or more <message-destination-ref> elements
Zero or more <message-destination> elements
Zero or more <local-encoding-mapping-list> elements

Child Elements of <web-app>

The following sections cover the permissible child elements that <web-app> may have (other than those already described).

<distributable>

The <distributable> element, if present, declares that this Web application can be deployed in a distributed servlet container or servlet container executing across multiple Java virtual machines (JVMs) running either on the same host or on different hosts.

<context-param>

The <context-param> element declares a context initialization parameter. It contains the following:

A <param-name> element containing the parameter's name
A <param-value> element containing the parameter's value
An optional <description> element (see earlier description)

<filter>

The <filter> element declares a filter. A filter is a Java class that preprocesses the request data received from clients. This preprocessing may include decryption, formatting, or other processes. This element contains the following:

An optional <icon> element
A <filter-name> element containing the filter's name
An optional <display-name> element
An optional <description> element
A <filter-class> element containing the filter's class name
Zero or more <init-param> elements containing initialization parameters for the filter

Each <init-param> element contains the following:

A <param-name> element containing the parameter name
A <param-value> element containing the parameter value
An optional <description> element

<filter-mapping>

You use the <filter-mapping> element to map a filter to a servlet or a set of uniform resource locators (URLs). It contains the following:

A <filter-name> element containing the name of a filter declared by a <filter> element
Either a <url-pattern> element containing a URL pattern to match or a <servlet-name> element containing the name of a servlet declared by a <servlet> element
Zero to four <dispatcher> elements

The <dispatcher> elements can have one of the following values: FORWARD, REQUEST, INCLUDE, and ERROR. FORWARD applies the filter to RequestDispatcher.forward() calls. REQUEST applies the filter to ordinary client calls to the path or servlet. INCLUDE applies the filter to RequestDispatcher.include() calls. ERROR applies the filter to the error page mechanism. If the <dispatcher> element is omitted, the default value is REQUEST.

<listener>

You can use the <listener> element to declare an application listener. It contains the following:

A <listener-class> element containing the listener's class name
<description>, <display-name>, and <icon> elements

<servlet>

The <servlet> element declares a servlet. It contains the following:

An optional <icon> element.
A <servlet-name> element containing the servlet's name.
An optional <display-name> element.
An optional <description> element.
Either a <servlet-class> element containing the listener's class name or a <jsp-file> element containing the location within the Web application of a JSP file.
<init-param> elements.
An optional <load-on-startup> element indicating that the servlet should be loaded when the Web application starts up and containing an optional positive integer value indicating the order in which servlets should be started. If a <jsp-file> was specified, then the JSP should be precompiled and loaded.
<security-role-ref> elements.
An optional <run-as> element that specifies the identity under which the servlet should run.

Each <init-param> element contains the following:

A <param-name> element containing the parameter name
A <param-value> element containing the parameter value
An optional <description> element

A <security-role-ref> element maps a role name called from within the servlet and the name of a security role defined for the Web application. It contains the following:

An optional <description> element
A <role-name> element containing the role name used within the servlet
An optional <role-link> element containing the name of a role defined in a <security-role> element

<servlet-mapping>

The <servlet-mapping> element maps a servlet to a URL pattern. It contains the following:

A <servlet-name> element containing the name of a servlet declared by a <servlet> element
A <url-pattern> element containing a URL pattern to match

<session-config>

The <session-config> element configures the session tracking for the Web application. It contains the following:

An optional <session-timeout> element containing the default session timeout for this Web application, which must be a whole number of minutes. The default behavior of the container without this attribute is to never time out.

<mime-mapping>

The <mime-mapping> element maps a filename extension to a Multipurpose Internet Mail Extensions (MIME) type. It contains the following:

An <extension> element containing a filename extension
A <mime-type> element containing a defined MIME type

<welcome-file-list>

The <welcome-file-list> element defines an ordered list of welcome files. It contains the following:

One or more <welcome-file> elements containing a filename to use as a welcome file

<error-page>

The <error-page> element maps an error code or exception type to a resource (error page) to use if that error condition arises. It contains the following:

Either an <error-code> element containing an HTTP error code or an <exception-type> element containing the class name of a Java exception type
A <location> element containing the location of the error page resource within the Web application

<jsp-config>

The <jsp-config> element declares JSP configuration options. It contains the following:

A <taglib> element containing tag library information
A <jsp-property-group> element for specifying properties common to a group of JSPs

The <taglib> element contains the following subelements:

A <taglib-uri> element containing a uniform resource indicator (URI) to identify the tag library
A <taglib-location> element containing the location within the Web application of the tag library descriptor file (.tld file)

The <jsp-property-group> element has the following subelements:

A <url-pattern> element specifying which resources should be covered by this set of properties.
An optional <el-ignored> element that should be set to true or false. If true, then Expression Language (EL) terms are ignored.
An optional <page-encoding> element that specifies the page encoding. A translation-time error will occur if a page directive's pageEncoding attribute is different from the value specified in web.xml.
An optional <scripting-invalid> element that disables scripting on a page.
An optional <is-xml> element that specifies that the pages are XML.
Zero or more <include-prelude> elements that include the specified resource at the beginning of each file in this JSP group.
Zero or more <include-coda> elements that include the specified resource at the end of each file in this JSP group.

<resource-env-ref>

The <resource-env-ref> element declares that the Web application references an administered object such as a Java Message Service (JMS) resource destination. It contains the following:

An optional <description> element.
A <resource-env-ref-name> element containing the name of the resource environment.
A <resource-env-ref-type> element containing the type of the resource environment reference. J2EE Web containers are required to support javax.jms.Topic and javax.jms.Queue

<resource-ref>

The <resource-ref> element declares that the Web application references an external resource such as a data source reference. It contains the following:

An optional <description> element.
A <res-ref-name> element containing the name of the resource factory reference.
A <res-type> element specifying the type of the data source.
A <res-auth> element indicating whether the application code signs on to the resource programmatically or whether the container should sign on based on information supplied by the application deployer. Contents must be either Application or Container.
An optional <res-sharing-scope> element specifying whether connections can be shared. Contents must be either Shareable (the default) or Unshareable.

<security-constraint>

The <security-constraint> element applies security constraints to one or more collections of Web resources. It contains the following:

An optional <display-name> element
One or more <web-resource-collection> elements
An optional <auth-constraint> element
An optional <user-data-constraint> element

A <web-resource-collection> element identifies a set of resources within the application; it can be qualified by specifying particular Hypertext Transfer Protocol (HTTP) method(s) such as GET or POST. (By default, the security constraint applies to all HTTP methods.) It contains the following:

A <web-resource-name> element containing the name of the Web resource collection
An optional <description> element
One or more <url-pattern> elements, each containing a URL pattern to match
Zero or more <http-method> elements, each containing the name of an HTTP method

An <auth-constraint> element indicates that certain user roles should be permitted to access these Web resources. It contains the following:

An optional <description> element
Zero or more <role-name> elements each containing a role referenced in a <security-role-ref> element or the special name * that indicates all roles in this application

A <user-data-constraint> element indicates how data transmitted between the client and the application should be protected. It contains the following:

An optional <description> element

A <transport-guarantee> element, which can have one of the three values in Table C-1

Table C-1: <transport-guarantee> Values

Value

Description

NONE	No transport guarantee is required.
INTEGRAL	The data must not be changed in transit.
CONFIDENTIAL	Others may not view the data en route.

<login-config>

The <login-config> element configures the authentication mechanism for this application. It contains the following:

An optional <auth-method> element specifying the authentication mechanism. It must contain the text BASIC, DIGEST, FORM, or CLIENT-CERT.
An optional <realm-name> element specifying the realm name for HTTP basic authorization.
An optional <form-login-config> element to configure form-based authentication. It contains a <form-login-page> element specifying the login page and a <form-error-page> element specifying the error page used if login is unsuccessful.

<security-role>

The <security-role> element declares a security role used in the Web application's security-constraints. It contains the following:

An optional <description> element
A <role-name> element containing the name of the role

<env-entry>

The <env-entry> element declares an application's environment entry. It contains the following:

An optional <description> element.
An <env-entry-name> element containing the environment entry's name.
An optional <env-entry-value> element containing the environment entry's value.
An <env-entry-type> element containing the environment entry value's Java type. Legal values are java.lang.Boolean, java.lang.String, java.lang.Integer, java.lang.Double, and java.lang.Float.

<ejb-ref>

The <ejb-ref> element declares a reference to an Enterprise JavaBean (EJB). It contains the following:

An optional <description> element
An <ejb-ref-name> element containing the Java Naming and Directory Interface (JNDI) name of the EJB
An <ejb-ref-type> element containing the expected type of the EJB, either Entity or Session
A <home> element containing the type (the name of the class) of the EJB's home interface
A <remote> element containing the type of the EJB's remote interface
An optional <ejb-link> element specifying that this EJB reference is linked to the named EJB in the encompassing J2EE application.

<ejb-local-ref>

You use <ejb-local-ref> to declare a reference to an EJB's local home. The declaration consists of the following:

An optional <description> element
An <ejb-ref-name> element containing the JNDI name of the EJB
An <ejb-ref-type> element containing the expected type of the EJB, either Entity or Session
A <local-home> element used to specify the local home interface of the EJB
A <local> element used to specify the local interface of the EJB
An optional <ejb-link> element used to specify the referenced EJB

<service-ref>

<service-ref> declares reference to a Web service. It contains the following:

A <service-ref-name> element used to specify the name of the Web service. This should begin with /service/.
A <service-interface> element used to define the fully qualified class name of the interface on which the client depends.
An optional <wsdl-file> element used to specify the path to a Web Service Description Language (WSDL) file.
An optional <jaxrpc-mapping-file> element containing the name of a file that describes the Java API for XML-Based RPC (JAX-RPC) mapping between the Java interfaces used by the application and the WSDL description in the <wsdl-file> element.
An optional <service-qname> used to specify the WSDL service element.
Zero or more <port-component-ref> elements declaring a client dependency on the container.
Zero or more <handler> elements declaring the handler for a port component.

<message-destination>

<message-destination> declares a message destination. It contains the following:

A <message-destination-name> element used to specify the name of a message destination

<message-destination-ref>

<message-destination-ref> contains a declaration of a message destination. It contains the following:

A <message-destination-ref-name> element that specifies the JDNI name of a message destination
A <message-destination-type> element specifying the type of the destination.
A <message-destination-usage> element specifying the use of the message destination
An optional <message-destination-link> element that links a destination to a message reference or message EJB

<locale-encoding-mapping-list>

<locale-encoding-mapping-list> contains mappings between the locale and the encoding. It contains the following:

One or more <locale-encoding-mapping> elements used to specify a single mapping

<locale-encoding-mapping> contains the following subelements:

A <locale> element used to specify the locale
An <encoding> element used to specify the encoding