Licensed to the Apache Software Foundation (ASF) under one or more

  contributor license agreements.  See the NOTICE file distributed with

  this work for additional information regarding copyright ownership.

  The ASF licenses this file to You under the Apache License, Version 2.0

  (the "License"); you may not use this file except in compliance with

  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software

  distributed under the License is distributed on an "AS IS" BASIS,

  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  See the License for the specific language governing permissions and

  limitations under the License.

-->

This is the XML DTD for the Servlet 2.3 deployment descriptor.

All Servlet 2.3 deployment descriptors must include a DOCTYPE

of the following form:

    "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"

    "http://java.sun.com/dtd/web-app_2_3.dtd">

-->

The following conventions apply to all J2EE deployment descriptor

elements unless indicated otherwise.

- In elements that contain PCDATA, leading and trailing whitespace

  in the data may be ignored.

- In elements whose value is an "enumerated type", the value is

  case sensitive.

- In elements that specify a pathname to a file within the same

  JAR file, relative filenames (i.e., those not starting with "/")

  are considered relative to the root of the JAR file's namespace.

  Absolute filenames (i.e., those starting with "/") also specify

  names in the root of the JAR file's namespace.  In general, relative

  names are preferred.  The exception is .war files where absolute

  names are preferred for consistency with the servlet API.

-->

The web-app element is the root of the deployment descriptor for

a web application.

-->

context-param*, filter*, filter-mapping*, listener*, servlet*,

servlet-mapping*, session-config?, mime-mapping*, welcome-file-list?,

error-page*, taglib*, resource-env-ref*, resource-ref*, security-constraint*,

login-config?, security-role*, env-entry*, ejb-ref*,  ejb-local-ref*)>

The auth-constraint element indicates the user roles that should

be permitted access to this resource collection. The role-name

used here 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.

Used in: security-constraint

-->

The auth-method element is 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".

Used in: login-config

-->

The context-param element contains the declaration of a web

application's servlet context initialization parameters.

Used in: web-app

-->

The description element is used to provide text describing the parent

element.  The description element should include any information that

the web application war file producer wants to provide to the consumer of

the web application war file (i.e., to the Deployer). Typically, the tools

used by the web application war file consumer will display the description

when processing the parent element that contains the description.

Used in: auth-constraint, context-param, ejb-local-ref, ejb-ref,

env-entry, filter, init-param, resource-env-ref, resource-ref, run-as,

security-role, security-role-ref, servlet, user-data-constraint,

web-app, web-resource-collection

-->

The display-name element contains a short name that is intended to be

displayed by tools.  The display name need not be unique.

Used in: filter, security-constraint, servlet, web-app

Example:

<display-name>Employee Self Service</display-name>

-->

The distributable element, by its presence in a web application

deployment descriptor, indicates that this web application is

programmed appropriately to be deployed into a distributed servlet

container

Used in: web-app

-->

The ejb-link element is used in the ejb-ref or ejb-local-ref

elements 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.

Used in: ejb-local-ref, ejb-ref

Examples:

    <ejb-link>EmployeeRecord</ejb-link>

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

-->

The ejb-local-ref element is used for the declaration of a reference to

an enterprise bean's local 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 local home and local interfaces of the referenced

      enterprise bean

    - optional ejb-link information, used to specify the referenced

      enterprise bean

Used in: web-app

-->

        local-home, local, ejb-link?)>

The ejb-ref element 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

Used in: web-app

-->

        home, remote, ejb-link?)>

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/".

Used in: ejb-local-ref, ejb-ref

Example:

<ejb-ref-name>ejb/Payroll</ejb-ref-name>

-->

The ejb-ref-type element contains 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>

Used in: ejb-local-ref, ejb-ref

-->

The env-entry element contains the declaration of a web application's

environment entry. The declaration consists of an optional

description, the name of the environment entry, and an optional

value.  If a value is not specified, one must be supplied

during deployment.

-->

env-entry-type)>

The env-entry-name element contains the name of a web application'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>

Used in: env-entry

-->

The env-entry-type element 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

Used in: env-entry

-->

The env-entry-value element 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.

Example:

<env-entry-value>100.00</env-entry-value>

Used in: env-entry

-->

The error-code contains an HTTP error code, ex: 404

Used in: error-page

-->

The error-page element contains a mapping between an error code

or exception type to the path of a resource in the web application

Used in: web-app

-->

The exception type contains a fully qualified class name of a

Java exception type.

Used in: error-page

-->

The extension element contains a string describing an

extension. example: "txt"

Used in: mime-mapping

-->

Declares a filter in the web application. 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.

Used in: web-app

-->

filter-class, init-param*)>

The fully qualified classname of the filter.

Used in: filter

-->

Declaration of the filter mappings in this web application. 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.

Used in: web-app

-->

The logical name of the filter. This name is used to map the filter.

Each filter name is unique within the web application.

Used in: filter, filter-mapping

-->

The form-error-page element 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.

Used in: form-login-config

-->

The form-login-config element 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.

Used in: login-config

-->

The form-login-page element 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.

Used in: form-login-config

-->

The home element contains the fully-qualified name of the enterprise

bean's home interface.

Used in: ejb-ref

Example:

<home>com.aardvark.payroll.PayrollHome</home>

-->

The http-method contains an HTTP method (GET | POST |...).

Used in: web-resource-collection

-->

The icon element 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.

Used in: filter, servlet, web-app

-->

The init-param element contains a name/value pair as an

initialization param of the servlet

Used in: filter, servlet

-->

The jsp-file element contains the full path to a JSP file within

the web application beginning with a `/'.

Used in: servlet

-->

The large-icon element contains the name of a file

containing a large (32 x 32) icon image. The file

name is a relative path within the web application's

war file.

The image may be either in the JPEG or GIF format.

The icon can be used by tools.

Used in: icon

Example:

<large-icon>employee-service-icon32x32.jpg</large-icon>

-->

The listener element indicates the deployment properties for a web

application listener bean.

Used in: web-app

-->

The listener-class element 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.

Used in: listener

-->

The load-on-startup element indicates that this servlet should be

loaded (instantiated and have its init() called) on the start-up

of the web application. The optional contents of

these 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.

Used in: servlet

-->

The local element contains the fully-qualified name of the

enterprise bean's local interface.

Used in: ejb-local-ref

-->

The local-home element contains the fully-qualified name of the

enterprise bean's local home interface.

Used in: ejb-local-ref

-->

The location element 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 `/'.

Used in: error-page

-->

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.

Used in: web-app

-->

The mime-mapping element defines a mapping between an extension

and a mime type.

Used in: web-app

-->

The mime-type element contains a defined mime type. example:

"text/plain"

Used in: mime-mapping

-->

The param-name element contains the name of a parameter. Each parameter

name must be unique in the web application.

Used in: context-param, init-param

-->

The param-value element contains the value of a parameter.

Used in: context-param, init-param

-->

The realm name element specifies the realm name to use in HTTP

Basic authorization.

Used in: login-config

-->

The remote element contains the fully-qualified name of the enterprise

bean's remote interface.

Used in: ejb-ref

Example:

<remote>com.wombat.empl.EmployeeService</remote>

-->

The res-auth element 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>

Used in: resource-ref

-->

The res-ref-name element specifies the name of a resource manager

connection factory reference.  The name is a JNDI name relative to the

java:comp/env context.  The name must be unique within a web application.

Used in: resource-ref

-->

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.

Used in: resource-ref

-->

The res-type element 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.

Used in: resource-ref

-->

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.

Used in: web-app

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-env-ref-type)>

The resource-env-ref-name element 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.

Used in: resource-env-ref

-->

The resource-env-ref-type element specifies the type of a resource

environment reference.  It is the fully qualified name of a Java

language class or interface.

Used in: resource-env-ref

-->

The resource-ref element contains a declaration of a web application's

reference to an external resource. It 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).

Used in: web-app

Example:

    <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>

-->

        res-sharing-scope?)>

The role-link element is a reference to a defined security role. The

role-link element must contain the name of one of the security roles

defined in the security-role elements.

Used in: security-role-ref

-->

The role-name element contains the name of a security role.

The name must conform to the lexical rules for an NMTOKEN.

Used in: auth-constraint, run-as, security-role, security-role-ref

-->

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.

Used in: servlet

-->

The security-constraint element is used to associate security

constraints with one or more web resource collections

Used in: web-app

-->

auth-constraint?, user-data-constraint?)>

The security-role element contains the definition of a security

role. The definition consists of an optional description of the

security role, and the security role name.