DD Elements At A GlanceS2C Home « DD Elements At A Glance

• <<    Java Keywords
• HTML Tags     >>

Quick reference section for all the Servlet 2.5 specification Deployment Descriptor (DD) elements.

The web.xml file is our Deployment Descriptor (DD) and is where we put declarative statements for several areas of our web application. The first part of the DD is always the same and points to version numbers, schemas and namespaces for XML and DTD, so don't worry too much about this when creating your own DD, just copy it.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
                             http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xmlns="http://java.sun.com/xml/ns/javaee" version="2.5">

</web-app>

All other top level elements are optional and are placed within the <web-app> root element. The following sections cover every top-level element within the Servlet 2.5 specification DD along with each sub-level element contained within it. Click a link on the right sidebar to go directly to the top-level DD element you're interested in.

Prior to the Servlet 2.5 specification the order of top-level DD element entries within the DD was important and certain elements had to come before others. Since 2.5 the top-level DD element entries can be placed in any order. The list in this quick reference reflects the pre 2.5 specification ordering, as oopposed to alphabetical ordering, because people are used to it. Just remember that from 2.5 the ordering of top-level DD element entries is up to the person who writes the DD.

The <context-param> ElementTop

The top-level <context-param> element is optional, contains the declaration of a web application's servlet context initialization parameters and can appear in the DD mutiple times. The <context-param> element has three sub-level elements as shown in the following diagram.

Within <context-param>, the <description> sub-level element is optional and can appear many times and the <param-name> and <param-value> sub-level elements are both mandatory, must appear only once and represent a key/value pair. The values within these elements can be retrieved using methods of the ServletContext interface which are implemented within the GenericServlet class. Examples of using these methods to get values via keys can be found in the ServletConfig & ServletContext lesson.

The <filter> ElementTop

The top-level <filter> element is used to describe and point to a filter class and is used in conjunction with the top-level <filter-mapping> element to allow controlled access to resources. The <filter> element contains several sub-level elements which can themselves contain sub-level elements as shown in the following diagram.

The <description>, <display-name> and <icon> sub-level elements are an optional group of descriptive elements. If present the <icon> sub-level element must come before the <filter-name> sub-level element.

The <filter-name> sub-level element is mandatory and can only appear once within the top-level <filter> element. The <filter-name> sub-level element must come before the <filter-class> sub-level element. The value of the filter name you give this element must be unique within the web application and be at least one character long.

The <filter-class> sub-level element is mandatory and can only appear once within the top-level <filter> element. The <filter-class> sub-level element defines the fully qualifed name of a Java Filter class, delimited by dots for the packages our filter is within. The value you give this class doesn't have to be unique within a web application.

The <init-param> sub-level element is optional and can appear many times within the top-level <filter> element. Within <init-param> the <description> sub-level element is optional and the <param-name> and <param-value> sub-level elements are both mandatory, must appear only once and represent a key/value pair. The values within these elements can be retrieved using methods of the FilterConfig interface. Examples of using these methods to get values via keys can be found in the Using Filters lesson.

The <filter-mapping> ElementTop

The <filter-mapping> element is used to map an incoming resource to a filter and is used in conjunction with the <filter> top-level element to allow controlled access to resources. The <filter-mapping> element has three sub-level elements as shown in the following diagram.

The <url-pattern> and <servlet-name> sub-level elements can be placed in any order and their must be at least one of either present. The value of the servlet names must be unique within the web application and be at least one character long.

When a request comes in for a servlet or a static resource that is declared as requiring filtration in the DD the part of the address supplied by the client after the web application name, is used to match against the <url-pattern> and <servlet-name> and sub-level elements within the DD. When one is found the <filter-name> sub-level element of the <filter-mapping> top-level element is used to find the <filter-name> sub-level element within the top-level <filter> element. From here we can get the location of the filter via the <filter-class> sub-level element. This is how the mapping from the request to the filter, which is hidden from public view in the WEB-INF directory is achieved.

A filter chain is based on the order of the <url-pattern> and <servlet-name> sub-level elements declared in the DD. When more than one resource is mapped to a given resource all filters with matching URL patterns are located and are applied to the chain in the order they were declared in the DD. Once this is completed the same process is repeated for filters that have a matching <servlet-name>.

The <dispatcher> sub-level element is optional and can appear up to four times; the values are listed below:

• REQUEST - This is the default and is a direct client request for a resource.
• FORWARD - Internal request on the web server for a resource via the forward() method of a Request Dispatcher.
• INCLUDE - Internal request on the web server for a resource via the include() method of a Request Dispatcher.
• ERROR - Internal request on the web server for a resource that has been created as an error-page.

The <listener> ElementTop

The top-level <listener> element is optional and can appear in the DD mutiple times. The <listener> element has one sub-level element as shown in the following diagram.

Within <listener>, the <listener-class> sub-level element is optional, can only appear once and represents the fully qualifed name of the listener class. There is no need to state which kind of listener is being used as the web container works this out using the Java Reflection API, which is beyond the scope of these tutorials.

The listeners are called in top-down order which may be of importance if you have more than one listener class implementing the same interface and care about invocation order. On shutdown the order is reversed, so you can think of it as a Last-In-First-Out (LIFO) sequence.

The <servlet> ElementTop

The top-level <servlet> element is used to describe and point to a servlet class and is used in conjunction with the top-level <servlet-mapping> element to allow controlled access to resources. The <servlet> element contains several sub-level elements which can themselves contain sub-level elements as shown in the following diagram.

The <description>, <display-name> and <icon> sub-level elements are an optional group of descriptive elements. If present the <icon> sub-level element must come before the <servlet-name> sub-level element.

The <servlet-name> sub-level element is mandatory and can only appear once within the top-level <servlet> element. The <servlet-name> sub-level element must come before the <servlet-class> sub-level element. The value of the servlet name you give this element must be unique within the web application and be at least one character long.

The <servlet-class> or <jsp-file> sub-level element is mandatory and can only appear once within the top-level <servlet> element. The <servlet-class> sub-level element defines the fully qualifed name of a Java Servlet class, delimited by dots for the packages our servlet is within. The value you give this class doesn't have to be unique within a web application. The <jsp-file> sub-level element defines a JavaServer Page (JSP) file rather than a servlet to be invoked and is used for JSP files whose URL we want to keep hidden from users.

The <init-param> sub-level element is optional and can appear many times within the top-level <servlet> element. Within <init-param> the <description> sub-level element is optional and the <param-name> and <param-value> sub-level elements are both mandatory, must appear only once and represent a key/value pair. The values within these elements can be retrieved using methods of the ServletConfig interface which are implemented within the GenericServlet class. Examples of using these methods to get values via keys can be found in the ServletConfig & ServletContext lesson.

Default container behaviour is to lazily initialise servlets on first use or when the container deems it necessary. We can also set servlets to load on deployment or server restart, via the DD using the <load-on-startup> sub-level element of the top-level <servlet> element. Any positive integer value placed in the <load-on-startup> sub-level element will ensure that a servlet is loaded on deployment or server restart. If you have several servlets in your web application you can also control the order in which servlets are loaded via the <load-on-startup> sub-level element. The servlets with the highest <load-on-startup> integer values get loaded first down to the lowest with a positive value.

The <run-as> sub-level element is optional and specifies an identity to be used for the execution of the Web application. Within <run-as> the <description> sub-level element is optional and the <role-name> sub-level element is mandatory, must appear only once and contains the name of a security role.

The <security-role-ref> sub-level element is optional and specifies a security role we can link to within servlet code. Within <security-role-ref> the <description> and <role-link> sub-level elements are optional and the <role-name> sub-level element is mandatory, must appear only once and contains the name of a security role that can be linked to within a servlet at deployment time.

The <servlet-mapping> ElementTop

The <servlet-mapping> element is used to map an incoming resource to a servlet and is used in conjunction with the <servlet> top-level element to allow controlled access to resources. The <servlet-mapping> element has two sub-level elements as shown in the following diagram.

The <servlet-name> sub-level element must come before any <url-pattern> sub-level elements. The value of the servlet name you give this element must be unique within the web application and be at least one character long.

When a request comes in for a servlet the part of the address supplied by the client after the web application name, is used to match against <url-pattern> sub-level elements within the DD. When one is found the <servlet-name> sub-level element of the <servlet-mapping> top-level element is used to find the <servlet-name> sub-level element within the top-level <servlet> element. From here we can get the location of the servlet via the <servlet-class> sub-level element. This is how the mapping from the request to the servlet, which is hidden from public view in the WEB-INF directory is achieved.

The <session-config> ElementTop

The <session-config> element defines the session timeout attributes for a web application. The <session-config> element has one sub-level element as shown in the following diagram.

The <session-timeout> sub-level element is optional and defaults to 60. The value you enter for the <session-timeout> sub-level element must be an integer and is expressed as whole minutes. Entering a negative value or 0 means the session will never time out. Entering a positive number denotes the period in minutes before the session is invalidated with a maximum value of Integer.MAX_VALUE ÷ 60.

The <security-constraint> ElementTop

The top-level <security-constraint> element is used to declare security constraints for resources within a web application. The <security-constraint> element can consist of up to four sub-level elements as shown in the following diagram.

The top-level <security-constraint> element and there can be many, must contain at least one <web-resource-collection> sub-level element, which can itself consist of up to four sub-level elements these being; <web-resource-name> which is mandatory, appears once and has no specific function apart from describing the group being collected together. The optional <description> sub-level element which can be repeated as often as you want to decribe this web resource collection. The <url-pattern> which is mandatory, can appear once or many times and works the same as all the other URL pattern matchers we have seen. Finally there is the <http-method> which is optional and can be repeated as often as you wish to constrain which type of http methods can be used.

• Valid values for <http-method> are DELETE, GET, HEAD, OPTIONS, POST, PUT and TRACE and be all uppercase.
• If any HTTP method is specified then all other HTTP methods not specified that your servlet supports are unconstrained and can be accessed by anyome regardless of the roles specified in <auth-constraint>.
• If no HTTP methods specified all HTTP methods are constrained and can only be accessed by the roles specified in <auth-constraint>.

Every <security-constraint> can contain 0 or 1 <auth-constraint> sub-level element, which can itself consist of up to two sub-level elements these being; the optional <description> sub-level element which can be repeated as often as you want to decribe this authority constraint. The optional <role-name> sub-level element which can be repeated as often as you want and specifies the roles allowed to access the security constraints held within the <web-resource-collection> element. The <auth-constraint> element must follow the <web-resource-collection> element.

• If no <auth-constraint> element is specified or is empty the container must allow unauthorized access to the URLs specifed within the <web-resource-collection> element.
• If the <auth-constraint> element is present and not empty then the container must perform authentication for the URLs specifed within the <web-resource-collection> element.
• If the <auth-constraint> element is present and the <role-name> sub-level element is present and contains the special value * then all users are allowed.
• Any role names specified within the <role-name> sub-level element are case-sensitive.

Every <security-constraint> can contain 0 or 1 <user-data-constraint> sub-level element, which can itself consist of up to two sub-level elements these being; the optional <description> sub-level element which can be repeated as often as you want to decribe this authority constraint. The mandatory <transport-guarantee> which must appear only once.

If present the <user-data-constraint> element must follow the <web-resource-collection> and <auth-constraint> elements.

Valid values for the mandatory <transport-guarantee> sub-level element are as follows:

• NONE - Which is the default and means the data is not protected during transport.
• INTEGRAL - Which means the data must not be modified during transport.
• CONFIDENTIAL Which means the data must be hidden from view during transport.

The <login-config> ElementTop

The top-level <login-config> element is used to declare that authentication is required. Within the <login-config> element, we can enter an optional authentication type, the optional realm name that should be used for this application; and the attributes that are needed by the form login mechanism as shown in the diagram below.

Although the <login-config> element is shown as 0 or many times and indeed the XML parsing allows this, the container does further validation to ensure that there is only ever one <login-config> element.

The <auth-method> sub-level element is optional and can only appear once within the top-level <login-config> element. Depending on the container the <auth-method> sub-level element can be delimited with commas as a fallback mechanism if the initial authentication method is unavailable. If present the <auth-method> sub-level element can have one of the following values which must be entered as uppercase characters:

• BASIC - Basic authentication is the default and uses the BASE 64 algorithm; no programmatic security is required.
• DIGEST - Digest authentication using the MD5 algorithm; no programmatic security is required.
• CLIENT-CERT - Client certificate authentication using the a digital certificate; no programmatic security is required.
• FORM - Form authentication using a custom login and error screen using programmatic security.

The <realm-name> sub-level element is optional and can only appear once within the top-level <login-config> element. The <realm-name> sub-level element contains the registry used to store user account information and is only applicable to the BASIC and DIGEST authentication types.

The <form-login-config> sub-level element is optional, only applicable to the FORM authentication type, and can only appear once within the the top-level <login-config> element. Within <form-login-config>, the <form-login-page> and <form-error-page> sub-level elements are both mandatory, must appear only once and represent HTML or JSP pages to display where appropriate.

The <security-role> ElementTop

The top-level <security-role> element is used to declare the security roles that are present in the vendor specific users file. The <security-role> element can consist of up to two sub-level elements as shown in the following diagram.

The optional <description> sub-level element which can be repeated as often as you want to decribe the security roles used.

The <role name> sub-level element which is mandatory, can appear once or many times and mirrors the role names held in the vendor-specific users file which are in use for this web application.

• <<    Java Keywords
• HTML Tags     >>