J2EE deployment descriptors

 
 
Every J2EE application module must include an XML based deployment descriptor that provide configuration information for the asset as well as defining relationships to other components.

There are two types of deployments descriptors:
  • vendor neutral deployment descriptors (a.k.a deployment descriptors)
  • vendor specific deployment descriptor (a.k.a deployment plans)
Deployment descriptors are necessary but are not always sufficient to deploy an asset on your server.
Deployment plans provides additional information to map declared resources names, ejb names, security roles, JMS roles (if any) to actual resources in the server. The deployment plans also contain specific server settings and configurations.

rss feed






Explain web.xml based on web-app_2_3.dtd (J2EE 1.3)

Show a valid web.xml file.

Occurrence of an element (column #) meaning:

1 = must occur one time
? = must occur zero or 1 time
+ = must occur one or more times
* = must occur zero or more times

Note:
a | b means either a or b



Information

Element # Description
web-app 1 Is the root of the deployment descriptor for a web application.
  icon ? Contains small-icon and large-icon elements that specify the file names for small and a large GIF or JPEG icon images used to represent the parent element in a GUI tool.
    small-icon ? Specify the file name for a small (16 x 16) GIF or JPEG icon image used to represent the parent element in a GUI tool.

The file name is a relative path within the web application's war file.

Example:

<small-icon>employee-service-icon16x16.jpg</small-icon>
    large-icon ? Specify the file name for a large (32 x 32) GIF or JPEG icon image used to represent the parent element in a GUI tool.

The file name is a relative path within the web application's war file.

Example:

<large-icon>employee-service-icon32x32.jpg</large-icon>
  display-name ? Contains a short name that is intended to be displayed by tools. The display name need not be unique.
  description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
  distributable ? This empty element indicates that this web application is programmed appropriately to be deployed into a distributed servlet container.
  context-param * Contains the declaration of a web application's servlet context initialization parameters.

You set each context-param within a single context-param element, using <param-name> and <param-value> elements.
You can access these parameters in your code using the javax.servlet.ServletContext.getInitParameter() and javax.servlet.ServletContext.getInitParameterNames() methods.
    param-name 1 Contains the name of a parameter. Each parameter name must be unique in the web application.
    param-value 1 Contains the value of a parameter.
    description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
  filter * The filter is mapped to either a servlet or a URL pattern in the filter-mapping element, using the filter-name value to reference. Filters can access the initialization parameters declared in the deployment descriptor at runtime via the FilterConfig interface.
    icon ? Contains small-icon and large-icon elements that specify the file names for small and a large GIF or JPEG icon images used to represent the parent element in a GUI tool.
      small-icon ? Specify the file name for a small (16 x 16) GIF or JPEG icon image used to represent the parent element in a GUI tool.

The file name is a relative path within the web application's war file.

Example:

<small-icon>employee-service-icon16x16.jpg</small-icon>
      large-icon ? Specify the file name for a large (32 x 32) GIF or JPEG icon image used to represent the parent element in a GUI tool.

The file name is a relative path within the web application's war file.

Example:

<large-icon>employee-service-icon32x32.jpg</large-icon>
    filter-name 1 The logical name of the filter. This name is used to map the filter and corresponds to the name assigned in the <filter-mapping> element with the <filter-name> element. Each filter name is unique within the web application.
    display-name ? Contains a short name that is intended to be displayed by tools. The display name need not be unique.
    description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
    filter-class 1 The fully qualified classname of the filter.
    init-param * Contains a name/value pair as an initialization param of the filter.
      param-name 1 Contains the name of a parameter. Each parameter name must be unique in the web application.
      param-value 1 Contains the value of a parameter.
      description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
  filter-mapping * The container uses the filter-mapping declarations to decide which filters to apply to a request, and in what order. The container matches the request URI to a Servlet in the normal way. To determine which filters to apply it matches filter-mapping declarations either on servlet-name, or on url-pattern for each filter-mapping element, depending on which style is used. The order in which filters are invoked is the order in which filter-mapping declarations that match a request URI for a servlet appear in the list of filter-mapping elements. The filter-name value must be the value of the <filter-name> sub-elements of one of the <filter> declarations in the deployment descriptor.
    filter-name 1 The logical name of the filter. This name corresponds to the name assigned in the <filter> element with the <filter-name> element. Each filter name is unique within the web application.
    url-pattern | servlet-name 1 If servlet-name element is used it contains the canonical name of the servlet. Each servlet name is unique within the web application.

If url-pattern element is used it contains the url pattern of the mapping. Describes a pattern used to resolve URLs. The portion of the URL after the http://host:port + ContextPath is compared to the <url-pattern> by the Application Server. If the patterns match, the filter mapped in this element is called.

Example patterns:

/process/request/*
/foo/*
/contents
*.do

Must follow the rules specified in Section 11.2 of the Servlet API Specification.
  listener * Define an application listener using the listener element.
    listener-class 1 Declares a class in the application must be registered as a web application listener bean. The value is the fully qualified classname of the listener class.

For example:

<listener>
   <listener-class>
      com.xyz.demo.ContextListener
   </listener-class>
</listener>

<listener>
   <listener-class>
      com.xyz.demo.SessionListener
   </listener-class>
</listener>
  servlet * Contains the declarative data of a servlet. If a jsp-file is specified and the load-on-startup element is present, then the JSP should be precompiled and loaded when the Application Server starts.
    icon ? Contains small-icon and large-icon elements that specify the file names for small and a large GIF or JPEG icon images used to represent the parent element in a GUI tool.
      small-icon ? Specify the file name for a small (16 x 16) GIF or JPEG icon image used to represent the parent element in a GUI tool.

The file name is a relative path within the web application's war file.

Example:

<small-icon>employee-service-icon16x16.jpg</small-icon>
      large-icon ? Specify the file name for a large (32 x 32) GIF or JPEG icon image used to represent the parent element in a GUI tool.

The file name is a relative path within the web application's war file.

Example:

<large-icon>employee-service-icon32x32.jpg</large-icon>
    servlet-name 1 The servlet-name element contains the canonical name of the servlet. Each servlet name is unique within the web application.
    display-name ? Contains a short name that is intended to be displayed by tools. The display name need not be unique.
    description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
    servlet-class|jsp-file 1 Use only one of either the <servlet-class> tags or <jsp-file> tags in your servlet body:

If the jsp-file element is used it contains the full path to a JSP file within the web application beginning with a "/".

If the servlet-class element is used it contains the fully qualified class name of the servlet.
    init-param * Contains a name/value pair as an initialization param of the servlet.

You can access these parameters with the javax.servlet.ServletConfig.getInitParameter() method.
      param-name 1 Contains the name of a parameter. Each parameter name must be unique in the web application.
      param-value 1 Contains the String value of a parameter.
      description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
    load-on-startup ? Indicates that this servlet should be loaded (instantiated and have its init() called) on the startup of the web application.

The optional content of this element must be an integer indicating the order in which the servlet should be loaded.

If the value is a negative integer, or the element is not present, the container is free to load the servlet whenever it chooses. If the value is a positive integer or 0, the container must load and initialize the servlet as the application is deployed.

The container must guarantee that servlets marked with lower integers are loaded before servlets marked with higher integers. The container may choose the order of loading of servlets with the same load-on-start-up value.
    run-as ? The run-as element 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.
      description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
      role-name 1 The role-name element contains the name of a security role. This can be a role name that is mapped to a principal name in deployment plan. The name must conform to the lexical rules for an NMTOKEN.
    security-role-ref * Contains the declaration of a security role reference in the web application's code.

The <security-role-ref> element links 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

If the security role is not specified, the Deployer must choose an appropriate security role.
      description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
      role-name 1 The security role name used in the code. The value must be the String used as the parameter to the EJBContext.isCallerInRole(String roleName) method or the HttpServletRequest.isUserInRole(String role) method.
      role-link ? The <role-link> element is a reference to a defined <security-role>.
  servlet-mapping * The servlet-mapping element defines a mapping between a servlet and a url pattern.
    servlet-name 1 The <servlet-name> element contains the canonical name of the servlet.

This name corresponds to the name you assigned in the <servlet-name> element in the <servlet> element.

Each servlet name is unique within the web application.
    url-pattern 1 Contains the url pattern of the mapping. Describes a pattern used to resolve URLs. The portion of the URL after the http://host:port + WebAppName is compared to the <url-pattern> by the Application Server. If the patterns match, the servlet mapped in this element will be called.

Example patterns:

/process/request/*
/foo/*
/contents
*.do

Must follow the rules specified in Section 11.2 of the Servlet API Specification.
  session-config ? Defines the session parameters for this web application.
    session-timeout ? The session-timeout element defines the default session timeout interval for all sessions created in this web application. The specified timeout must be expressed in a whole number of minutes. If the timeout is 0 or less, the container ensures the default behaviour of sessions is never to time out.
  mime-mapping * The mime-mapping element defines a mapping between an extension and a mime type.
    extension 1 Contains a string describing an extension. example: "txt"
    mime-type 1 The mime-type element contains a defined mime type. example: "text/plain"
  welcome-file-list ? Contains an ordered list of welcome files elements. When the URL request is a directory name, the Application Server serves the first file specified in the <welcome-file> element. If that file is not found, the server then tries the next file in the list.
    welcome-file + Contains file name to use as a default welcome file, for example:

<welcome-file>index.html</welcome-file>
<welcome-file>index.jsp</welcome-file>
<welcome-file>start.do</welcome-file>
  error-page * Contains a mapping between an error code or exception type to the path of a resource in the web application.

When an error occurs, while the Application Server is responding to an HTTP request, or as a result of a Java exception, the Application Server returns an HTML page that displays either the HTTP error code or a page containing the Java error message. You can define your own HTML page to be displayed in place of these default error pages or in response to a Java exception.
    error-code | exception-type 1 Define either an <error-code> or an <exception-type> but not both.

The error-code contains an HTTP error code, for example: 404.

The exception type contains a fully qualified class name of a Java exception type.
    location 1 Contains the location of the resource in the web application relative to the root of the web application. The value of the location must have a leading "/", for example:

/myErrorPage.html
  taglib * Is used to describe a JSP tag library. This element associates the location of a JSP Tag Library Descriptor (TLD) with a URI pattern.
    taglib-uri 1 Describes a URI, relative to the location of the web.xml document, identifying a Tag Library used in the Web Application. If the URI matches the URI string used in the taglib directive on the JSP page, this taglib is used.
    taglib-location 1 Contains the location (as a resource relative to the root of the web application) where to find the Tag Libary Description file for the tag library. It is a good idea to store the tag library descriptor file under the WEB-INF directory so it is not publicly available over an HTTP request.
  resource-env-ref * 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>
    description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
    resource-env-ref-name 1 Specifies the name of a resource environment reference; its value is the environment entry name used in the web application code. The name is a JNDI name relative to the java:comp/env context and must be unique within a web application.
    resource-env-ref-type 1 Specifies the type of a resource environment reference. It is the fully qualified name of a Java language class or interface.
  resource-ref * The 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. The external resource name is mapped to the actual location name of the resource at deployment time in the Application Server deployment plan.

The resource-ref element consists of an optional description, the resource manager connection factory reference name, the indication of the resource manager connection factory type expected by the web application code, the type of authentication (Application or Container), and an optional specification of the shareability of connections obtained from the resource (Shareable or Unshareable).

<resource-ref>
<res-ref-name>jdbc/EmployeeAppDB</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
    description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
    res-ref-name 1 The name of the resource used in the JNDI tree. Servlets in the Web Application use this name to look up a reference to the resource.

The name is a JNDI name relative to the java:comp/env context. The name must be unique within a web application.
    res-type 1 Specifies the type of the data source. The type is specified by the fully qualified Java language class or interface expected to be implemented by the data source.
    res-auth 1 Specifies whether the web application code signs on programmatically to the resource manager, or whether the Container will sign on to the resource manager on behalf of the web application. In the latter case, the Container uses information that is supplied by the Deployer.

The value of this element must be one of the two following:

<res-auth>Application</res-auth>
<res-auth>Container</res-auth>
    res-sharing-scope ? The res-sharing-scope element specifies whether connections obtained through the given resource manager connection factory reference can be shared. The value of this element, if specified, must be one of the two following:

<res-sharing-scope>Shareable</res-sharing-scope>
<res-sharing-scope>Unshareable</res-sharing-scope>

The default value is Shareable.
  security-constraint * The <security-constraint> element defines the access privileges to a collection of resources defined by the <web-resource-collection> element.
    display-name ? Contains a short name that is intended to be displayed by tools. The display name need not be unique.
    web-resource-collection + Is used to identify a subset of the resources and HTTP methods on those resources within a web application to which a security constraint applies. If no HTTP methods are specified, then the security constraint applies to all HTTP methods.
      web-resource-name 1 Contains the name of this web resource collection.
      description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
      url-pattern * Use one or more of the <url-pattern elements to declare to which URL patterns this security constraint applies.

Must follow the rules specified in Section 11.2 of the Servlet API Specification.
      http-method * Use one or more of the <http-method> elements to declare which HTTP methods (usually, GET or POST) are subject to the authorization constraint. If you omit the <http-method> element, the default behavior is to apply the security constraint to all HTTP methods.
    auth-constraint ? Indicates the user roles that should be permitted access to this resource collection.
      description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
      role-name * The role-name must either correspond to the role-name of one of the security-role elements defined for this web application, or be the specially reserved role-name "*" that is a compact syntax for indicating all roles in the web application. If both "*" and rolenames appear, the container interprets this as all roles. If no roles are defined, no user is allowed access to the portion of the web application described by the containing security-constraint. The container matches role names case sensitively when determining access.
    user-data-constraint ? The user-data-constraint element defines how the client should communicate with the server.
      description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
      transport-guarantee 1 Specifies that the communication between client and server should be NONE, INTEGRAL, or CONFIDENTIAL.

NONE means that the application does not require any transport guarantees.

A value of INTEGRAL means that the application requires that the data sent between the client and server be sent in such a way that it can't be changed in transit.

CONFIDENTIAL means that the application requires that the data be transmitted in a fashion that prevents other entities from observing the contents of the transmission.

In most cases, the presence of the INTEGRAL or CONFIDENTIAL flag will indicate that the use of SSL is required.
  login-config ? The login-config element is used to configure the authentication method that should be used, the realm name that should be used for this application, and the attributes that are needed by the form login mechanism.
    auth-method ? Used to configure the authentication mechanism for the web application. As a prerequisite to gaining access to any web resources which are protected by an authorization constraint, a user must have authenticated using the configured mechanism. Legal values for this element are "BASIC", "DIGEST", "FORM", or "CLIENT-CERT".
    realm-name ? Specifies the realm name to use in HTTP Basic authorization.
    form-login-config ? Specifies the login and error pages that should be used in form based login. If form based authentication is not used, these elements are ignored.
      form-login-page 1 Defines the location in the web app where the page that can be used for login can be found. The path begins with a leading / and is interpreted relative to the root of the WAR.
      form-error-page 1 Defines the location in the web app where the error page that is displayed when login is not successful can be found. The path begins with a leading / and is interpreted relative to the root of the WAR.
  security-role * Contains the definition of a security role. The definition consists of an optional description of the security role, and the security role name.

<security-role>
<description>
This role includes all employees who are authorized
to access the employee service application.
</description>
<role-name>employee</role-name>
</security-role>
    description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
    role-name 1 The role-name element contains the name of a security role. The name must conform to the lexical rules for an NMTOKEN.
  env-entry * Contains the declaration of a web application's environment entry.
    description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
    env-entry-name 1 Contains the name of a web applications's environment entry. The name is a JNDI name relative to the java:comp/env context. The name must be unique within a web application.

Example:

<env-entry-name>minAmount</env-entry-name>
    env-entry-value ? Contains the value of a web application's environment entry. The value must be a String that is valid for the constructor of the specified type that takes a single String parameter, or for java.lang.Character, a single character. If a value is not specified, one must be supplied during deployment.

Example:

<env-entry-value>100.00</env-entry-value>
    env-entry-type 1 Contains the fully-qualified Java type of the environment entry value that is expected by the web application's code.

The following are the legal values of env-entry-type:

java.lang.Boolean
java.lang.Byte
java.lang.Character
java.lang.String
java.lang.Short
java.lang.Integer
java.lang.Long
java.lang.Float
java.lang.Double
  ejb-ref * Is used for the declaration of a reference to an enterprise bean's home. The declaration consists of:
  • an optional description
  • the EJB reference name used in the code of the web application that's referencing the enterprise bean
  • the expected type of the referenced enterprise bean
  • the expected home and remote interfaces of the referenced enterprise bean
  • optional ejb-link information, used to specify the referenced enterprise bean
    description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
    ejb-ref-name 1 The ejb-ref-name element contains the name of an EJB reference. The EJB reference is an entry in the web application's environment and is relative to the java:comp/env context. The name must be unique within the web application.

It is recommended that name is prefixed with "ejb/".

Example:

<ejb-ref-name>ejb/Payroll</ejb-ref-name>
    ejb-ref-type 1 The expected type of the referenced enterprise bean. The ejb-ref-type element must be one of the following:

<ejb-ref-type>Entity</ejb-ref-type> <ejb-ref-type>Session</ejb-ref-type>
    home 1 The home element contains the fully-qualified name of the enterprise bean's home interface.

Example:

<home>com.aardvark.payroll.PayrollHome</home>
    remote 1 Contains the fully-qualified name of the enterprise bean's remote interface.

Example:

<remote>com.wombat.empl.EmployeeService</remote>
    ejb-link ? To specify that an EJB reference is linked to an enterprise bean. The name in the ejb-link element is composed of a path name specifying the ejb-jar containing the referenced enterprise bean with the ejb-name of the target bean appended and separated from the path name by "#". The path name is relative to the war file containing the web application that is referencing the enterprise bean. This allows multiple enterprise beans with the same ejb-name to be uniquely identified.

Examples:
<ejb-link>EmployeeRecord</ejb-link>

<ejb-link>../products/product.jar#ProductEJB</ejb-link>
  ejb-local-ref * The ejb-local-ref element is used for the declaration of a reference to an enterprise bean's local home.
    description ? Should include any information that the web application war file producer wants to provide to the deployer. Tools used by the deployer will display the description when processing the parent element that contains the description.
    ejb-ref-name 1 The EJB reference name used in the code of the web application that's referencing the enterprise bean
    ejb-ref-type 1 The expected type of the referenced enterprise bean. The ejb-ref-type element must be one of the following:

<ejb-ref-type>Entity</ejb-ref-type> <ejb-ref-type>Session</ejb-ref-type>
    local-home 1 The local-home element contains the fully-qualified name of the enterprise bean's local home interface.
    local 1 Contains the fully-qualified name of the enterprise bean's local interface.
    ejb-link ? To specify the referenced enterprise bean.

The name in the ejb-link element is composed of a path name specifying the ejb-jar containing the referenced enterprise bean with the ejb-name of the target bean appended and separated from the path name by "#". The path name is relative to the war file containing the web application that is referencing the enterprise bean. This allows multiple enterprise beans with the same ejb-name to be uniquely identified.

Examples:
<ejb-link>EmployeeRecord</ejb-link>

<ejb-link>../products/product.jar#ProductEJB</ejb-link>