bea.com | products | dev2dev | support | askBEA |
|
e-docs > WebLogic Server > Developing Web Applications for WebLogic Server > web.xml Deployment Descriptor Elements |
Developing Web Applications for WebLogic Server |
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:
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.
The optional display-name element specifies the Web Application display name, a short name that can be displayed by GUI tools.
The optional description element provides descriptive text about the Web Application.
The distributable element is not used by WebLogic Server.
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.
<context-param>
<param-name>weblogic.httpd.inputCharset./*</param-name>
<param-value>UTF-8</param-value>
</context-param>
The following table describes the elements you can define within a context-param element.
The filter element defines a filter class and its initialization parameters. For more information on filters, see Configuring Filters
The following table describes the elements you can define within a servlet element.
The following table describes the elements you can define within a filter-mapping element.
Define an application listener using the listener element.
For more information, see Configuring an Event Listener.
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 is precompiled and loaded when WebLogic Server starts.
The following table describes the elements you can define within a servlet element.
This is an element within the servlet.
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 an icon element.
This is an element within the servlet.
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.
WebLogic Server recognizes the special initialization parameter, wl-dispatch-policy, to assign a servlet or JSP to an available execute queue. For example, the following example assigns a servlet to use the execute threads available in an execute queue named CriticalWebApp:
<servlet>
...
<init-param>
<param-name>wl-dispatch-policy</param-name>
<param-value>CriticalWebApp</param-value>
</init-param>
</servlet>
If the CriticalWebApp queue is not available, the servlet will use execute threads available in the default WebLogic Server execute queue. See Setting Thread Count for more information about configuring execute threads in WebLogic Server. See Using Execute Queues to Control Thread Usage for more information about creating and using queues.
This is an element within the servlet.
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.
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.
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. |
||
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. /soda/grape/* The URL must follow the rules specified in the Servlet 2.2 Specification. For additional examples of servlet mapping, see Servlet Mapping. |
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.
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. Maximum value: Integer.MAX_VALUE ÷ 60
For more information, see jsp-descriptor. |
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.
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 Configuring Welcome Pagesand "How WebLogic Server Resolves HTTP Requests."
The following table describes the element you can define within a welcome-file-list 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.
Note: Define either an <error-code> or an <exception-type> but not both.
A fully-qualified class name of a Java exception type, for example, java.lang.string |
||
The location of the resource to display in response to the error. For example, /myErrorPg.html. |
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.
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.
<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>
The following table describes the elements you can define within a resource-env-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.
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 Java type of the resource that corresponds to the reference name. Use the full package name of the Java type. |
||
Used to control the resource sign on for security. If set to APPLICATION, 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. |
||
Specifies whether connections obtained through the given resource manager connection factory reference can be shared. |
The security-constraint element defines the access privileges to a collection of resources defined by the <web-resource-collection> element.
For more information, see Configuring Security in Web Applications.
The following table describes the elements you can define within a security-constraint element.
Defines the components of the Web Application to which this security constraint is applied. |
||
Defines which groups or principals have access to the collection of web resources defined in this security constraint. See also auth-constraint. |
||
Defines how the client should communicate with the server. See also user-data-constraint |
Each <security-constraint> element must have one or more <web-resource-collection> elements. These define the area of the Web Application to which this security constraint is applied.
This is an element within the security-constraint.
The following table describes the elements you can define within a web-resource-collection element.
This is an element within the security-constraint.
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.
Defines which security roles can access resources defined in this security-constraint. Security role names are mapped to principals using the security-role-ref. See security-role-ref. |
This is an element within the security-constraint.
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.
Use the optional login-config element to configure 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.
Specifies the method used to authenticate the user. Possible values: BASIC - uses browser authentication |
||
The name of the realm that is referenced to authenticate the user credentials. If omitted, the realm defined with the Auth Realm Name field on the Web Application Note: The <realm-name> element does not refer to security realms within WebLogic Server. This element defines the realm name to use in HTTP Basic authorization. Note: The system security realm is a collection of security information that is checked when certain operations are performed in the server. The servlet security realm is a different collection of security information that is checked when a page is accessed and basic authentication is used. |
||
Use this element if you configure the <auth-method> to FORM. See form-login-config. |
This is an element within the login-config.
Use the <form-login-config> element if you configure the <auth-method> to FORM.
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. |
||
The URI of a Web resource relative to the document root, sent to the user in response to a failed authentication login. |
The following table describes the elements you can define within a security-role element.
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. |
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 an env-entry 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 an ejb-ref element.
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. |
||
The <ejb-name> of an EJB in an encompassing J2EE application package. |
||
A security role whose security context is applied to the referenced EJB. Must be a security role defined with the <security-role> element. |
The ejb-local-ref element is used for the declaration of a reference to an enterprise bean's local home. The declaration consists of:
The following table describes the elements you can define within an ejb-local-ref element.