Deployment Descriptor Elements (web.xml)

Deployment Descriptor

A Deployment Descriptor is an XML file that provides both structural and application assembly information. Deployment descriptors describe how to package J2EE components into an application.

Types of Deployment Descriptor

There are five types of deployment descriptors, each of which corresponds to a type of deployment unit:

·         EJB deployment descriptors are defined in the Enterprise JavaBeans specification.

·         Web deployment descriptors are defined in the Java Servlet specification.

·         Application and Application client deployment descriptors are both defined in the J2EE platform specification.

·         Resource adapter deployment descriptors for Java Connectors are defined by the J2EE Connector architecture specification.

Deployment descriptors contain information used by a component's container and also contain information that the component can access directly by way of the JNDI. The JNDI is a standard interface to an enterprise object name service.

The following sections describe the deployment descriptor elements defined in the web.xml file under the root element <web-app>:

context-param tag

This tag provides parameters to the entire context / web application.

Uses include things like defining an administrator email address to send errors from your application, or other settings that are relevant to your application as a whole.

To access the values from your Java/JSP code, use the following syntax:

String value = getServletContext().getInitParameter(“AdministratorEmail");

A single <context-param> tag is used for each parameter.

Example:

<context-param>

               <param-name>AdministratorEmail</param-name>

   <param-value>test@gmail.com</param-value>   

</context-param>

description tag

The optional description element provides descriptive text about the Web application.

display-name tag

The optional display-name element specifies the Web application display name, a short name that can be displayed by GUI tools.

Example:

<display-name>Give your Name</display-name>

distributable tag

This tag marks a web application as distributable, which means it is suitable for running in a distributed environment, such as a clustered Tomcat installation.

If marked as distributable, all new sessions, and changes to existing sessions will be replicated to other members of the cluster by the session-replicator, according to the replication rules in server.xml.

If an application is run in a cluster without being marked as distributable, session changes will only occur on a single JVM. Therefore, when the user connects to one of the other JVM's, their session will not be recognized, and a new session will be created. This may force them to log in again, establishing a 2nd session on the other JVM. As they switch between the two servers, various other problems may arise.

In a load-balanced cluster, user requests are sent to two or more JVM's. To implement session-failover, all applications running on the cluster must be distributable to properly maintain session state across the multiple servers.

Example:

               <distributable />

ejb-ref tag

An EJB reference is an entry in the application component environment. However, <env-entry> must not be used to declare it. Instead, it must be declared using the <ejb-ref> tag of the web deployment descriptor. The elements of the <ejb-ref> tag are:

• description: an optional descriptor of the EJB reference entry.
• ejb-ref-name: a unique EJB reference name.
• ejb-ref-type: specifies the expected type of the EJB. The value must either be Session or Entity.
• home: specifies the full class name of the EJB's home interface.
• remote: specifies the full class name of the EJB's remote interface.
• ejb-link: specify the <ejb-name> of an EJB in an encompassing J2EE application package.
• run-as: A security role whose security context is applied to the referenced EJB. Must be a security role defined with the <security-role> element.

Example:

<ejb-ref>

  <description>A reference to an entity bean to access employee records</description>

  <ejb-ref-name>ejb/EmployeeRecord</ejb-ref-name>

  <ejb-ref-type>Entity</ejb-ref-type>

  <home>com.company.Employee.EmployeeRecordHome</home>

  <remote>com.company.Employee.EmployeeRecordRemote</remote>

</ejb-ref>

ejb-local-ref tag

The ejb-local-ref element is used for the declaration of a reference to an enterprise bean's local home.

• description: an optional descriptor of the EJB reference entry.
• ejb-ref-name: a unique EJB reference name.
• ejb-ref-type: specifies the expected type of the EJB. The value must either be Session or Entity.
• local-home: specifies the full class name of the EJB's local home interface.
• local: specifies the full class name of the EJB's local interface.

Example:

<ejb-local-ref>

               <ejb-ref-name>ejb/OpLocal</ejb-ref-name>

               <ejb-ref-type>Session</ejb-ref-type>

               <local-home>org.objectweb.earsample.beans.secusb.OpLocalHome</local-home>

               <local>org.objectweb.earsample.beans.secusb.OpLocal</local>

               <ejb-link>secusb.jar#Op</ejb-link>

</ejb-local-ref>

 

env-entry tag

This tag provides environment variables (properties) which can be accessed by your web application using JNDI.

Advantages

• Using your own settings file requires additional coding and management.
• Hard-coding parameter values directly into your application code makes them more difficult to change in the future, and more difficult to use different settings for different deployments (eg: JDBC settings, mail server address).
• Other developers using your code will be able to find any relevant parameters more easily, as this is a standard location for such parameters to be set.

A single <env-entry> tag is used for each property.

The property name and value are set using <env-entry-name> and <env-entry-value>. <env-entry-type> is used to specify the data type, which is usually java.lang.String. This can be any fully qualified class name, as long as the class has a constructor that accepts a single string.

Example:

<env-entry> 

    <env-entry-name>webmasterEmail</env-entry-name> 

    <env-entry-type>java.lang.String</env-entry-type> 

    <env-entry-value>admin@domain.com</env-entry-value> 

</env-entry>

 

error-page tag

This is a container tag used to define a custom error page.

Multiple custom error pages can be defined per application. 

Tomcat will check your web.xml for these elements before displaying its default error page.

Error page handlers can be defined according to HTTP error code (eg: 404 errors) or Java Exception type.

Example:

<error-page>

<error-code>404</error-code>

<location>/404.html</location>

</error-page>

filter tag

This is a container tag used to specify a Java filter and its parameters.

A filter is run before servlets or JSP pages get called, so it's possible to "chain" 1 or more filters before the final servlet/page is hit.

The main advantage is that it can sit outside the application, and is a stand-alone module. You can find many free filters on the internet.

Example:

<filter>

<filter-name>Test Filter</filter-name>

<filter-class>com.test.filter.TestFilter</filter-class>

</filter>

filter-mapping tag

This tag specifies a filter name, and either a URL mapping or servlet name, for a filter that has been defined with the <filter> tag.

Multiple <filter-mapping> tags can be specified for a single <filter>, providing different URL patterns.

The <filter-mapping> has two required elements:

• <filter-name> - the filter name, as specified in the <filter-name> element of the <filter> tag
• Either a <url-pattern> or a <servlet-name>.

If a servlet name is specified, the filter will be called whenever the specific servlet is called.

Example:

<filter-mapping>

<filter-name>Test Filter</filter-name>

<url-pattern>*.do</url-pattern>

</filter-mapping>

icon tag

The icon element contains a small-icon and a large-icon element which specify the location within the web application for a small and large image used to represent the web application in a GUI tool.

The small-icon element contains the location within the web application of a file containing a small (16x16 pixel) icon image. The image must be either GIF or JPEG format and the filename must end with the extension of ".gif" or ".jpg".

Example:<small-icon>path/to/icon.gif</small-icon>

The large-icon element contains the location within the web application of a file containing a large (32x32 pixel) icon image. The image must be either GIF or JPEG format and the filename must end with the extension of ".gif" or ".jpg".

Example: <large-icon>path/to/icon.gif</large-icon>

listener tag

The servlet specification includes the capability to track key events in your Web applications through event listeners. This functionality allows more efficient resource management and automated processing based on event status.

Example:

<listener>

<listener-class>com.test.listener.TestListener</listener-class>

</listener>

login-config tag

This tag defines the authorization methods for the application, as well as any attributes required for BASIC or FORM-based authentication.

Subelements

• <auth-method>
• <form-login-config>
• <form-login-page>
• <form-error-page>
• <realm-name>

Examples:

BASIC Authentication (popup dialog box from browser)

<login-config> 

<auth-method>BASIC</auth-method> 

<realm-name>Editor Login</realm-name> 

</login-config>

FORM-based Authentication (uses a login page and an error/access-denied page)

<login-config> 

               <auth-method>FORM</auth-method> 

               <form-login-config> 

                               <form-login-page>/login.jsp</form-login-page> 

                               <form-error-page>/error.jsp</form-error-page> 

               </form-login-config> 

</login-config>

mime-mapping tag

This tag defines a mapping between a file extension and a MIME type.

There are two required sub elements as follows:

• <extension> - file extension (no leading dot), examples: xls, pdf
• <mime-type> - a mime type, eg: application/vnd.ms-excel or text/html

Examples:

Enabling file downloads via the application/octet-stream

While most files will download correctly from your site, if you have created a file with an unknown extension, the browser may attempt to display the file using the text/plain MIME type, which will show in the browser as text.

To avoid this behavior, a mime-mapping can be set for your file to force the browser to download the file. This appropriate MIME type is application/octet-stream. This is a generic type for binary data streams.

Here is an example for an imaginary file type of pqz:

<!-- Send PQZ files as application/octet-stream so the user is asked to download the file --> 

<mime-mapping> 

               <extension>pqz</extension>

               <mime-type>application/octet-stream</mime-type> 

</mime-mapping>

Enabling download of Microsoft Excel spreadsheets

When providing Microsoft Excel spreadsheets for download from your application, some browsers display the file as garbage on the browser unless an appropriate mime-mapping is set.

The desired action is to prompt for the file to be saved, or to open it in Excel. Newer versions of Internet Explorer may also display the file directly in the browser using the embedded Excel Active-X control.

Adding the following mime-mapping element to web.xml sets the correct mime-type, allowing the browser to interpret the file correctly.

<!-- Set Excel mime-mapping so spreadsheets open properly instead of being sent as 

an octet/stream -->

<!-- If this is not done, the user may be prompted to save the file, or it may open as garbage 

text in the browser --> 

<mime-mapping> 

               <extension>xls</extension> 

               <mime-type>application/vnd.ms-excel</mime-type> 

</mime-mapping>

resource-env-ref tag

The resource-env-ref element contains a declaration of a Web application's reference to an administered object associated with a resource in the Web application's environment. It consists of an optional description, the resource environment reference name, and an indication of the resource environment reference type expected by the Web application code.

Example:

<resource-env-ref>

    <resource-env-ref-name>jms/StockQueue</resource-env-ref-name>

    <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>

</resource-env-ref>

resource-ref tag

The optional resource-ref element defines a reference lookup name to an external resource. This allows the servlet code to look up a resource by a "virtual" name that is mapped to the actual location at deployment time.

Use a separate <resource-ref> element to define each external resource name.

Example:

<resource-ref>

<description>Employees Database for HR Applications</description>

<res-ref-name>jdbc/EmployeeDB</res-ref-name>

<res-ref-type>javax.sql.DataSource</res-ref-type>

<res-auth>Container</res-auth>

<res-sharing-scope>shareable</res-sharing-scope>

</resource-ref>

res-auth: 

Specify whether the web Application code signs on to the corresponding resource manager 

programmatically, or whether the Container will sign on to the resource manager on behalf 

of the application. The value of this attribute must be Application or Container. This attribute

is required if the web application will use a <resource-ref> element in the web application 

deployment descriptor, but is optional if the application uses a <resource-env-ref> instead.

res-sharing-scope:

Specify whether connections obtained through this resource manager can be shared. The value of this attribute must be Shareable or Unshareable. By default, connections are assumed to be shareable.

 

security-constraint tag

This tag allows you to force an area of your site to be restricted to authenticated users and/or to use SSL.

Restricting areas to Authenticated Users

A security constraint can be set up to allow access only to Authenticated Users, using the Security Realms feature of the servlet specification.

For example, an administrative area listed at /private can be password-protected using this tag.

Key Point 1: Upon entering the restricted area, the user will be asked to authenticate.

Key Point 2: Use of jsp:forward and jsp:include to request pages from the restricted area, are not subjected to security constraints. eg: Page A can jsp:include protected Page B, with no authentication required.

Constraints contain a <web-resource-collection> element, defining the URL Pattern which will be restricted (eg: /private/*), and an <auth-constraint> area listing the roles that are allowed access.

Two other sections in web.xml are also required:

• <security-roles> to list all roles used by the application
• <login-config> to specify the Authentication method, which may be Form Based or use HTTP (Basic) Authentication.

Forcing the use of SSL

A security constraint can be set up to force certain areas of your site (or your entire site) into SSL mode.

This is useful if those areas will be used for confidential information, such as login details or the entry of credit card details.

Constraints contain a <web-resource-collection> element, defining the URL Pattern which will be restricted (eg: /private/*), and a <user-data-constraint> area listing the transport guarantee level.

For a simple tutorial, see the article Forcing SSL for sections of your website.

Full example forcing authentication as well as SSL

<!—Define roles -->
<security-role>
   <role-name>cms_editors</role-name>
</security-role>
<!-- Define a constraint to restrict access to /private/* -->
<security-constraint>
   <web-resource-collection>
   <web-resource-name>Protected Area</web-resource-name>
   <url-pattern>/private/*</url-pattern>
</web-resource-collection>
<auth-constraint>
   <!-- Only CMS editors can access this area -->
   <role-name>cms_editors</role-name>
</auth-constraint>
<user-data-constraint>
   <!-- All access to this area will be SSL protected -->
   <transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
<!-- This application uses BASIC authentication -->
<login-config>
   <auth-method>BASIC</auth-method>
   <realm-name>Editor Login</realm-name>
</login-config>

security-role tag

This tag is used with a Security Realm, as a container for one or more <role-name> tags, to list the roles which are used by the application.

Each role must be referenced in a <security-role> tag before it can be used in the <auth-constraint> element of a <security-constraint>.

Users are mapped to Roles in the Security Realm itself (for example, a JDBC Authentication Realm).

servlet tag

This is a container tag used to specify a Java servlet and its parameters.

If a jsp-file is specified and the <load-on-startup> element is present, then the JSP is precompiled and loaded when server starts.

The elements you can define within a servlet element:

icon: Location within the Web application for a small and large image used to represent the servlet in a GUI tool. Contains a small-icon and large-icon element.

servlet-name: Defines the canonical name of the servlet, used to reference the servlet definition elsewhere in the deployment descriptor.

display-name: A short name intended to be displayed by GUI tools.

description: A text description of the servlet.

servlet-class: The fully-qualified class name of the servlet. Use only one of either the <servlet-class> tags or <jsp-file> tags in your servlet body.

jsp-file: The full path to a JSP file within the Web application, relative to the Web application root directory. Use only one of either the <servlet-class> tags or <jsp-file> tags in your servlet body.

init-param: Contains a name/value pair as an initialization attribute of the servlet. Use a separate set of <init-param> tags for each attribute.

load-on-startup: The optional content of this element must be a positive integer indicating the order in which the servlet should be loaded. Lower integers are loaded before higher integers. If no value is specified, or if the value specified is not a positive integer, server can load the servlet in any order during application startup.

run-as: Specifies the run-as identity to be used for the execution of the Web application. It contains an optional description and the name of a security role.

security-role-ref: Used to link a security role name defined by <security-role> to an alternative role name that is hard coded in the servlet logic. This extra layer of abstraction allows the servlet to be configured at deployment without changing servlet code.

Example:

<servlet>

<servlet-name>Test</servlet-name>

<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>

<load-on-startup>1</load-on-startup>

</servlet>

servlet-mapping tag

This tag specifies a URL mapping for a servlet that has been defined with the <servlet> tag.

Servlets cannot be called directly unless the InvokerServlet is enabled, so one or more mappings must exist for each servlet, to tell Tomcat when to call the servlet.

Multiple <servlet-mapping> tags can be specified for a single <servlet>, providing different URL patterns.

There are two required elements:

• <servlet-name> - the servlet name, as specified in the <servlet-name> element of the <servlet> tag
• <url-pattern> - the mapping, eg: *.do

Example:

<servlet-mapping>

               <servlet-name>MyServlet</servlet-name>

               <url-pattern>/somePath/*</url-pattern>

</servlet-mapping>

<servlet>

               <servlet-name>MyServlet</servlet-name>

               <servlet-class>com.mycompany.MyServlet</servlet-class>

</servlet>

session-config tag

This tag is used as a container for session settings.

The session timeout tag provides a way to specify the timeout for HTTP sessions.

The value between the tags is specified in minutes.

Examples:

<session-config>

               <session-timeout>120</session-timeout>

</session-config>

taglib tag

The optional taglib element describes a JSP tag library.

This element associates the location of a JSP Tag Library Descriptor (TLD) with a URI pattern. Although you can specify a TLD in your JSP that is relative to the WEB-INF directory, you can also use the <taglib> tag to configure the TLD when deploying your Web application. Use a separate element for each TLD.

Example:

<jsp-config> 

        <taglib> 

               <taglib-uri>mytags</taglib-uri> 

               <taglib-location>/WEB-INF/jsp/mytaglib.tld</taglib-location> 

        </taglib> 

</jsp-config>

Declare this in your JSP file using:

<%@ taglib prefix="mytags" uri="mytags" %>

<mytags:sometag>Test</mytags:sometag>

<mytags:othertag />

welcome-file-list tag

This tag is the container for one or more <welcome-file> tags, listed in order of preference.

Welcome files show when no filename is provided in the URL.

Example:

<welcome-file-list>

    <welcome-file>index.html</welcome-file>

    <welcome-file>index.htm</welcome-file>

    <welcome-file>index.jsp</welcome-file>

</welcome-file-list>