web.xml Deployment Descriptor Elements

 

This following sections describe the deployment descriptor elements defined in the web.xml file. The root element for web.xml is <web-app>. The following elements are defined within the <web-app> element:

• icon Element

• display-name Element

• description Element

• context-param Element

• servlet Element

• servlet-mapping Element

• session-config Element

• mime-mapping Element

• welcome-file-list Element

• error-page Element

• taglib Element

• resource-ref Element

• security-constraint Element

• login-config Element

• env-entry Element

• ejb-ref Element

icon Element

The icon element specifies the location within the Web Application for a small and large image used to represent the Web Application in a GUI tool. (The servlet element also has an element called the icon element, used to supply an icon to represent a servlet in a GUI tool.)

This element is not currently used by WebLogic Server.

The following table describes the elements you can define within an icon element.

Element	Required/ Optional	Description
<small-icon>	Optional	Specifies the location for a small (16x16 pixel) .gif or .jpg image used to represent the Web Application in a GUI tool. Currently, this is not used by WebLogic Server.
<large-icon>	Optional	Specifies the location for a large (32x32 pixel) .gif or .jpg image used to represent the Web Application in a GUI tool. Currently, this element is not used by WebLogic Server.
<display-name>	Optional	Currently, this element is not used by WebLogic Server.
<description>	Optional	Currently, this element is not used by WebLogic Server.
<distributable>	Optional	Currently, this element is not used by WebLogic Server.

display-name Element

The optional display-name element specifies the Web Application display name, a short name that is intended to be displayed by GUI tools.

description Element

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

context-param Element

The optional context-param element declares 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.

The following table describes the elements you can define within a context-param element.

Element	Required/ Optional	Description
<param-name>	Required	The name of a parameter.
<param-value>	Required	The value of a parameter.
<description>	Required	A text description of a parameter.

servlet Element

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

The following table describes the elements you can define within a servlet element.

Element	Required/ Optional	Description
<icon>	Optional	Specifies the 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. Currently, this element is not used by WebLogic Server.
<servlet-name>	Required	Defines the canonical name of the servlet, used to reference the servlet definition elsewhere in the deployment descriptor.
<display-name>	Optional	A short name intended to be displayed by GUI tools.
<description>	Optional	A text description of the servlet.
<servlet-class>	Required (or use <jsp- file>	The fully-qualified class name of the servlet. You may use only one of either the <servlet-class> tags or <jsp-file> tags in your servlet body.
<jsp-file>	Required (or use <servlet- class>	The full path to a JSP file within the Web Application, relative to the Web Application root directory. You may use only one of either the <servlet-class> tags or <jsp-file> tags in your servlet body.
<init-param>	Optional	Contains a name/value pair as an initialization parameter of the servlet. Use a separate set of <init-param> tags for each parameter.
<load-on-startup>	Optional	WebLogic Server initializes this servlet when WebLogic Server starts up. The optional contents 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, WebLogic Server can load the servlet in any order in the startup sequence.
<security-role- ref>	Optional	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.

icon Element

This is an element within the servlet Element.

The icon element specifies the location within the Web Application for small and large images used to represent the servlet in a GUI tool.

The following table describes the elements you can define within a icon element.

Element	Required/ Optional	Description
<small-icon>	Optional	Specifies the location within the Web Application for a small (16x16 pixel) .gif or .jpg image used to represent the servlet in a GUI tool. Currently, this element is not used by WebLogic Server.
<large-icon>	Optional	Specifies the location within the Web Application for a small (32x32 pixel) .gif or .jpg image used to represent the servlet in a GUI tool. Currently, this element is not used by WebLogic Server.

init-param Element

This is an element within the servlet Element.

The optional init-param element contains a name/value pair as an initialization parameter of the servlet. Use a separate set of init-param tags for each parameter.

You can access these parameters with the javax.servlet.ServletConfig.getInitParameter() method.

The following table describes the elements you can define within a init-param element.

Element	Required/ Optional	Description
<param-name>	Required	Defines the name of this parameter.
<param-value>	Required	Defines a String value for this parameter.
<description>	Optional	Text description of the initialization parameter.

security-role-ref Element

This is an element within the servlet Element.

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.

The following table describes the elements you can define within a security-role-ref element.

Element	Required/ Optional	Description
<description>	Optional	Text description of the role.
<role-name>	Required	Defines the name of the security role or principal that is used in the servlet code.
<role-link>	Required	Defines the name of the security role that is defined in a <security-role> element later in the deployment descriptor.

servlet-mapping Element

The servlet-mapping element defines a mapping between a servlet and a URL pattern.

The following table describes the elements you can define within a servlet-mapping element.

Element	Required/ Optional	Description
<servlet-name>	Required	The name of the servlet to which you are mapping a URL pattern. This name corresponds to the name you assigned a servlet in a <servlet> declaration tag.
<url-pattern>	Required	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 WebLogic Server. If the patterns match, the servlet mapped in this element will be called. Example patterns: /soda/grape/* /foo/* /contents *.foo The URL must follow the rules specified in Section 10 of the Servlet 2.2 Specification. For additional examples of servlet mapping, see Servlet Mapping.

session-config Element

The session-config element defines the session parameters for this Web Application.

The following table describes the element you can define within a session-config element.

Element	Required/ Optional	Description
<session-timeout>	Optional	The number of minutes after which sessions in this Web Application expire. The value set in this element overrides the value set in the TimeoutSecs parameter of the <session-descriptor> element in the WebLogic-specific deployment descriptor weblogic.xml, unless one of the special values listed here is entered. Default value: -2 Maximum value: Integer.MAX_VALUE ÷ 60 Special values: -2 = Use the value set by TimeoutSecs in <session-descriptor> element of weblogic.xml -1 = Sessions do not timeout. The value set in <session-descriptor> element of weblogic.xml is ignored. For more information, see "session-descriptor Element" on page B-4.

mime-mapping Element

The mime-mapping element defines a mapping between an extension and a mime type.

The following table describes the elements you can define within a mime-mapping element.

Element	Required/ Optional	Description
<extension>	Required	A string describing an extension, for example: txt.
<mime-type>	Required	A string describing the defined mime type, for example: text/plain.

welcome-file-list Element

The optional welcome-file-list element contains an ordered list of welcome-file elements.

When the URL request is a directory name, WebLogic Server serves the first file specified in this element. If that file is not found, the server then tries the next file in the list.

For more information, see Welcome Files and How WebLogic Server Resolves HTTP Requests.

The following table describes the element you can define within a welcome-file-list element.

Element	Required/ Optional	Description
<welcome-file>	Optional	File name to use as a default welcome file, such as index.html

error-page Element

The optional error-page element specifies a mapping between an error code or exception type to the path of a resource in the Web Application.

When an error occurs-while WebLogic Server is responding to an HTTP request, or as a result of a Java exception-WebLogic 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.

For more information, see Customizing HTTP Error Responses and How WebLogic Server Resolves HTTP Requests.

The following table describes the elements you can define within an error-page element.

Element	Required/ Optional	Description
<error-code>	Optional	A valid HTTP error code, for example 404.
<exception-type>	Optional	A fully-qualified class name of a Java exception type, for example java.lang.
<location>	Required	The location of the resource to display in response to the error. For example /myErrorPg.html

taglib Element

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.

The following table describes the elements you can define within a taglib element.

Element	Required/ Optional	Description
<taglib-location>	Required	Gives the file name of the tag library descriptor relative to the root of the Web Application. It is good idea to store the tag library descriptor file under the WEB-INF directory so it is not publicly available over an HTTP request.
<taglib-uri>	Required	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.

resource-ref Element

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. The external resource name is mapped to the actual location name of the resource at deployment time in the WebLogic-specific deployment descriptor weblogic.xml.

The following table describes the elements you can define within a resource-ref element.

Element	Required/ Optional	Description
<description>	Optional	A text description.
<res-ref-name>	Required	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.
<res-type>	Required	The Java type of the resource that corresponds to the reference name. Use the full package name of the Java type.
<res-auth>	Required	Used to control the resource sign on for security. If set to SERVLET, indicates that the application component code performs resource sign on programmatically. If set to CONTAINER WebLogic Server uses the security context established with the login-config element. See "login-config Element" on page A-15.

security-constraint Element

The security-constraint element defines the access privileges to a collection of resources via their URL mapping.

For more information, see Configuring Security in Web Applications.

The following table describes the elements you can define within a security-constraint element.

Element	Required/ Optional	Description
<web-resource- collection>	Required	Defines the components of the Web Application that this security constraint is applied to.
<auth-constraint>	Optional	Defines which groups or principals have access to the collection of web resources defined in this security constraint. See also "auth-constraint Element" on page A-13.
<user-data- constraint>	Optional	Defines how the client should communicate with the server. See also "user-data-constraint Element" on page A-13

web-resource-collection Element

Each <security-constraint> element must have one or more <web-resource-collection> elements. These define the area of the Web Application that this security constraint is applied to.

This is an element within the security-constraint Element.

The required web-resource-collection element define the area of the Web Application that this security constraint is applied to.

The following table describes the elements you can define within a web-resource-collection element.

Element	Required/ Optional	Description
<web-resource- name>	Required	The name of this Web resource collection.
<description>	Optional	A text description of this security constraint.
<url-pattern>	Optional	Use one or more of these elements to declare which URL patterns this security constraint applies to. If you do not use at least one of these elements, this <web-resource-collection> is ignored by WebLogic Server.
<http-method>	Optional	Use one or more of these elements to declare which HTTP methods (GET | POST |...) are subject to the authorization constraint. If you omit this element, the default behavior is to apply the security constraint to all HTTP methods.

auth-constraint Element

This is an element within the security-constraint Element.

The optional auth-constraint element defines which groups or principals have access to the collection of Web resources defined in this security constraint.

The following table describes the elements you can define within an auth-constraint element.

Element	Required/ Optional	Description
<description>	Optional	A text description of this security constraint.
<role-name>	Optional	Defines which security roles can access resources defined in this security-constraint. Security role names are mapped to principals using the security-role-ref Element. See "security-role-ref Element" on page A-6.

user-data-constraint Element

This is an element within the security-constraint Element.

The user-data-constraint element defines how the client should communicate with the server.

The following table describes the elements you may define within a user-data-constraint element.

Element	Required/ Optional	Description
<description>	Optional	A text description.
<transport- guarantee>	Required	Specifies that the communication between client and server. WebLogic Server establishes a Secure Sockets Layer (SSL) connection when the user is authenticated using the INTEGRAL or CONFIDENTIAL constraint. Range of values: NONE-the application does not require any transport guarantees. INTEGRAL-the application requires that the data sent between the client and server be sent in such a way that it cannot be changed in transit. CONFIDENTIAL-the application requires that the data be transmitted in a fashion that prevents other entities from observing the contents of the transmission.

login-config Element

The optional login-config element configures how the user is authenticated, the realm name that should be used for this application, and the attributes that are needed by the form login mechanism.

If this element is present, the user must be authenticated in order to access any resource that is constrained by a <security-constraint> defined in the Web Application. Once authenticated, the user can be authorized to access other resources with access privileges.

The following table describes the elements you can define within a login-config element.

Element	Required/ Optional	Description
<auth-method>	Optional	Specifies the method used to authenticate the user. Possible values: BASIC - uses browser authentication FORM - uses a user-written HTML form CLIENT-CERT
<realm-name>	Optional	The name of the realm that is referenced to authenticate the user credentials. If omitted, the WebLogic realm is used by default. For more information, see Specifying a Security Realm.
<form-login- config>	Optional	Use this element if you configure the <auth-method> to FORM. See "form-login-config Element" on page A-15.

form-login-config Element

This is an element within the login-config Element.

Use the form-login-config element if you configure the <auth-method> to FORM.

.

Element	Required/ Optional	Description
<form-login-page>	Required	The URI of a Web resource relative to the document root, used to authenticate the user. This can be an HTML page, JSP, or HTTP servlet, and must return an HTML page containing a FORM that conforms to a specific naming convention. For more information, see Setting Up Authentication for Web Applications
<form-error-page>	Required	The URI of a Web resource relative to the document root, sent to the user in response to a failed authentication login.

security-role Element

The following table describes the elements you can define within a security-role element.

Element	Required/ Optional	Description
<description>	Optional	A text description of this security role.
<role-name>	Required	The role name. The name you use here must have a corresponding entry in the WebLogic-specific deployment descriptor, weblogic.xml, which maps roles to principals in the security realm. For more information, see "security-role-assignment Element" on page B-2.

env-entry Element

The optional env-entry element declares an environment entry for an application. Use a separate element for each environment entry.

The following table describes the elements you can define within a env-entry element.

Element	Required/ Optional	Description
<description>	Optional	A textual description.
<env-entry-name>	Required	The name of the environment entry.
<env-entry-value>	Required	The value of the environment entry.
<env-entry-type>	Required	The type of the environment entry. Can be set to one of the following Java types: java.lang.Boolean java.lang.String java.lang.Integer java.lang.Double java.lang.Float

ejb-ref Element

The optional ejb-ref element defines a reference to an EJB resource. This reference is mapped to the actual location of the EJB at deployment time by defining the mapping in the WebLogic-specific deployment descriptor file, weblogic.xml. Use a separate <ejb-ref> element to define each reference EJB name.

The following table describes the elements you can define within a ejb-ref element.

Element	Required/ Optional	Description
<description>	Optional	A text description of the reference.
<ejb-ref-name>	Required	The name of the EJB used in the Web Application. This name is mapped to the JNDI Tree in the WebLogic-specific deployment descriptor weblogic.xml. For more information, see "ejb-reference-description Element" on page B-3.
<ejb-ref-type>	Required	The expected Java class type of the referenced EJB.
<home>	Required	The fully qualified class name of the EJB home interface.
<remote>	Required	The fully qualified class name of the EJB remote interface.
<ejb-link>	Optional	The <ejb-name> of an EJB in an encompassing J2EE application package.