|
|
This document provides a complete reference for the elements in the WebLogic Server-specific deployment descriptor weblogic.xml. If your Web application does not contain a weblogic.xml deployment descriptor, WebLogic Server automatically selects the default values of the deployment descriptor elements. To see the schema for weblogic.xml, go to
http://www.bea.com/ns/weblogic/920/weblogic-web-app.xsd.
The following sections describe the complex deployment descriptor elements that can be defined in the weblogic.xml deployment descriptor under the root element <weblogic-web-app>:
The description element is a text description of the Web application.
The weblogic-version element indicates the version of WebLogic Server on which this Web application (as defined in the root element <weblogic-web-app>) is intended to be deployed. This element is informational only and is not used by WebLogic Server.
The security-role-assignment element declares a mapping between a Web application security role and one or more principals in WebLogic Server, as shown in the following example.
<security-role-assignment><role-name>PayrollAdmin</role-name><principal-name>Tanya</principal-name><principal-name>Fred</principal-name><principal-name>system</principal-name>
</security-role-assignment>
You can also use it to mark a given role as an externally defined role, as shown in the following example:
<security-role-assignment><role-name>roleadmin</role-name><externally-defined/>
</security-role-assignment>
| Notes: | In the <security-role-assignment> element, either <principal-name> or <externally-defined> must be defined. Both cannot be omitted. |
The following table describes the elements you can define within a security-role-assignment element.
Specifies the name of a principal that is defined in the security realm. You can use multiple
<principal-name> elements to map principals to a role. For more information on security realms, see Managing WebLogic Security.
|
||
Specifies that a particular security role is defined globally in a security realm; WebLogic Server uses this security role as the principal name, rather than looking it up in a global realm. When the security role and its principal-name mapping are defined elsewhere, this is used as an indicative placeholder.
|
| Note: | If you do not define a security-role-assignment element and its sub-elements, the Web application container implicitly maps the role name as a principal name and logs a warning. The EJB container does not deploy the module if mappings are not defined. |
| Note: | Consider the following usage scenarios for the role name is “role_xyz” |
The run-as-role-assignment element maps a run-as role name (a sub-element of the servlet element) in web.xml to a valid user name in the system. The value can be overridden for a given servlet by the run-as-principal-name element in the servlet-descriptor. If the run-as-role-assignment is absent for a given role name, the Web application container uses the first principal-name defined in the security-role-assignment. The following example illustrates how to use the run-as-role-assignment element.
<run-as-role-assignment>
<role-name>RunAsRoleName</role-name>
<run-as-principal-name>joe</run-as-principal-name>
</run-as-role-assignment>
The following table describes the elements you can define within a run-as-role-assignment element.
The resource-description element is used to map the JNDI name of a server resource to an EJB resource reference in WebLogic Server.
The following table describes the elements you can define within a resource-description element
.
The resource-env-description element maps a resource-env-ref, declared in the ejb-jar.xml deployment descriptor, to the JNDI name of the server resource it represents.
The following table describes the elements you can define within a resource-env-description element.
The following table describes the elements you can define within a ejb-reference-description element.
The following table describes the elements you can define within a service-reference-description element.
The session-descriptor elements that define parameters for servlet sessions.
| Note: | When initializing session context, most session descriptors from weblogic-application.xml take precedence over those from weblogic.xml, with the default value being used for undefined properties regardless if it exists in weblogic.xml. However, when both XML files are being used, the following properties in weblogic.xml are honored first: |
debug-enabled cache-size cookie-max-age-secs timeout-secs max-in-memory-sessions monitoring-attribute-name invalidation-interval-secs
Sets the time, in seconds, that WebLogic Server waits before timing out a session. The default value is 3600 seconds.
On busy sites, you can tune your application by adjusting the timeout of sessions. While you want to give a browser client every opportunity to finish a session, you do not want to tie up the server needlessly if the user has left the site or otherwise abandoned the session.
|
||||
|
If you are writing a WAP application, you must use URL rewriting because the WAP protocol does not support cookies. Also, some WAP devices have a 128-character limit on URL length (including attributes), which limits the amount of data that can be transmitted using URL re-writing. To allow more space for attributes, use this attribute to limit the size of the session ID that is randomly generated by WebLogic Server.
You can also limit the length to a fixed 52 characters, and disallow special characters, by setting the WAPEnabled attribute. For more information, see
URL Rewriting and Wireless Access Protocol in Developing Web Applications for WebLogic Server.
|
||||
|
Without the ability to configure bound in-memory servlet session use, as new sessions are continually created, the server eventually throws out of memory. To protect against this, WebLogic Server provides a configurable bound on the number of sessions created. When this number is exceeded, the weblogic.servlet.SessionCreationException occurs for each attempt to create a new session. This feature applies to both replicated and non-replicated in-memory sessions.
|
||||
|
For more information about cookies, see
Using Sessions and Session Persistence.
|
||||
|
||||
Sets the name of the cookie used for cookie-based persistence. The
WLCOOKIE cookie carries the session state, which should not be shared between Web applications.
For more information, see
Using Cookie-Based Session Persistence.
|
||||
|
Ensure that you have enough disk space to store the number of valid sessions multiplied by the size of each session. You can find the size of a session by looking at the files created in the
persistent-store-dir. Note that the size of each session can vary as the size of serialized session data changes.
|
||||
The jsp-descriptor element specifies a list of configuration parameters for the JSP compiler. The following table describes the elements you can define within a jsp-descriptor element..
Sets the interval, in seconds, at which WebLogic Server checks to see if JSP files have changed and need recompiling. Dependencies are also checked and recursively reloaded if changed.
|
||
|
For more information, see Backwards Compatibility Flags.
|
||
Specifies the default character set used in the JSP page. Use standard
Java character set nameshttp://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.htm).
|
||
The auth-filter element specifies an authentication filter HttpServlet class.
| Note: | This is a deprecated element for the current release. Instead, use servlet authentication filters. |
The <container-descriptor> element specifies a list of parameters that affect the behavior of the Web application.
Add the <check-auth-on-forward/> element when you want to require authentication of forwarded requests from a servlet or JSP. Omit the tag if you do not want to require re-authentication. For example:
<container-descriptor>
<check-auth-on-forward/>
</container-descriptor>
| Note: | As a best practice, BEA does not recommend that you enable the check-auth-on-forward property. |
The <filter-dispatched-requests-enabled> element controls whether or not filters are applied to dispatched requests. The default value is false.
| Note: | Because 2.4 servlets are backward compatible with 2.3 servlets (per the 2.4 specification), when 2.3 descriptor elements are detected by WebLogic Server, the <filter-dispatched-requests-enabled> element defaults to true. |
The <redirect-with-absolute-url> element controls whether the javax.servlet.http.HttpServletResponse.SendRedirect() method redirects using a relative or absolute URL. Set this element to false if you are using a proxy HTTP server and do not want the URL converted to a non-relative link.
The default behavior is to convert the URL to a non-relative link.
user readable data used in a redirect.
The <index-directory-enabled> element controls whether or not to automatically generate an HTML directory listing if no suitable index file is found.
The default value is false (does not generate a directory). Values are true or false.
The <index-directory-sort-by> element defines the order in which the directory listing generated by weblogic.servlet.FileServlet is sorted. Valid sort-by values are NAME, LAST_MODIFIED, and SIZE. The default sort-by value is NAME.
The <servlet-reload-check-secs> element defines whether a WebLogic Server will check to see if a servlet has been modified, and if it has been modified, reloads it.
A value specified in the console will always take precedence over a manually specified value.
The <resource-reload-check-secs> element is used to perform metadata caching for cached resources that are found in the resource path in the Web application scope. This parameter identifies how often WebLogic Server checks whether a resource has been modified and if so, it reloads it.
Values specified for this parameter using the Admin Console are given precedence.
The <single-threaded-servlet-pool-size> element defines the size of the pool used for SingleThreadMode instance pools. The default value is 5.
| Note: | SingleThreadMode instance pools are deprecated in this release. |
The <session-monitoring-enabled> element, if set to true, allows runtime MBeans to be created for sessions. When set to false, the default value, runtime MBeans are not created. A value specified in the console takes precedence over a value set manually.
The <save-sessions-enabled> element controls whether session data is cleaned up during redeploy or undeploy. It affects memory and replicated sessions. Setting the value to true means session data is saved. Setting to false means session data will be destroyed when the Web application is redeployed or undeployed. The default is false.
The <prefer-web-inf-classes> element, if set to true, will cause classes located in the WEB-INF directory of a Web application to be loaded in preference to classes loaded in the application or system classloader. The default value is false. A value specified in the console will take precedence over a value set manually.
The <default-mime-type> element default value is null. This element allows the user to specify the default mime type for a content-type for which the extension is not mapped.
The <client-cert-proxy-enabled> element default value is true. When set to true, WebLogic Server passes identity certificates from the clients to the backend servers. Also, WebLogic Server is notified whether to honor or discard the incoming WL-Proxy-Client-Cert header.
A proxy-server plugin encodes each identity certification in the WL-Proxy-Client-Cert header and passes it to the backend WebLogic Server instances. Each WebLogic Server instance takes the certificate information from the header, ensured it came from a secure source, and uses that information to authenticate the user. For the background WebLogic Server instances, this parameter must be set to true (either at the cluster/server level or at the Web application level).
If you set this element to true, use a weblogic.security.net.ConnectionFilter to ensure that each WebLogic Server instance accepts connections only from the machine on which the proxy-server plugin is running. If you specify true without using a connection filter, a potential security vulnerability is created because the WL-Proxy-Client-Cert header can be spoofed.
The <relogin-enabled> element is a backward compatibility parameter. If a user has logged in already and tries to access a resource for which s/he does not have privileges, a FORBIDDEN (403) response occurs.
In the security-constraints elements defined in web.xml descriptor of a Web application, the auth-constraint element indicates the user roles that should be permitted access to this resource collection. Here role-name = "*" is a compact syntax for indicating all roles in the Web application. In past releases, role-name = "*" was treated as all users/roles defined within the realm.
This allow-all-roles element is a backward compatibility switch to restore old behavior. The default behavior is to allow all roles defined in the Web application. The value specified in weblogic-xml takes precedence over the value defined in the WebAppContainerMBean.
To use native I/O while serving static files with weblogic.servlet.FileServlet, which is implicitly registered as the default servlet, set native-io-enabled to true. (The default value is false.) native-io-enabled element applies only on Windows.
The minimum-native-file-size element applies only when native-io-enabled is set to true. It sets the minimum file size for using native I/O. If the file being served is larger than this value, native I/O is used. If you do not set this value, the default value used is 4K.
When the disable-implicit-servlet-mappings flag is set to true, the Web application container does not create implicit mappings for internal servlets (*.jsp, *.class, and so on); only for the default servlet mapping. A typical use case for turning off implicit servlet mappings would be when configuring HttpClusterServlet or HttpProxyServlet.
When optimistic-serialization is turned on, WebLogic Server does not serialize-deserialize context and request attributes upon getAttribute(name) when the request is dispatched across servlet contexts.
This means that you must make sure that the attributes common to Web applications are scoped to a common parent classloader (application scoped) or you must place them in the system classpath if the two Web applications do not belong to the same application.
When optimistic-serialization is turned off (default value), WebLogic Server serialize-deserializes context and request attributes upon getAttribute(name) to avoid the possibility of ClassCastExceptions.
The optimistic-serialization value can also be specified at domain level in the WebAppContainerMBean, which applies for all Web applications. The value in weblogic.xml, if specified, overrides the domain level value.
The require-admin-trafffic element defines whether traffic should go through the administration channel. When set to true traffic is allowed to go through the administration channel. Otherwise, traffic can only go through administration channel when the Web application is in administrative mode. For example:
<container-descriptor>
<require-admin-traffic>true</require-admin-traffic>
</container-descriptor>
The <charset-params> element is used to define code set behavior for non-unicode operations. For example:
<charset-params>
<input-charset>
<resource-path>/*</resource-path>
<java-charset-name>UTF-8</java-charset-name>
</input-charset>
</charset-params>
Use the <input-charset> element to define which character set is used to read GET and POST data. For example:
<input-charset>
<resource-path>/foo</resource-path>
<java-charset-name>SJIS</java-charset-name>
</input-charset>
For more information, see Determining the Encoding of an HTTP Request.
The following table describes the elements you can define within a <input-charset> element
.
Use the <charset-mapping> element to map an IANA character set name to a Java character set name. For example:
<charset-mapping>
<iana-charset-name>Shift-JIS</iana-charset-name>
<java-charset-name>SJIS</java-charset-name>
</charset-mapping>
For more information, see Mapping IANA Character Sets to Java Character Sets.
The following table describes the elements you can define within a <charset-mapping> element
.
Use the virtual-directory-mapping element to specify document roots other than the default document root of the Web application for certain kinds of requests, such as image requests. All images for a set of Web applications can be stored in a single location, and need not be copied to the document root of each Web application that uses them. For an incoming request, if a virtual directory has been specified servlet container will search for the requested resource first in the virtual directory and then in the Web application’s original document root. This defines the precedence if the same document exists in both places.
<virtual-directory-mapping>
<local-path>c:/usr/gifs</local-path>
<url-pattern>/images/*</url-pattern>
<url-pattern>*.jpg</url-pattern>
</virtual-directory-mapping>
<virtual-directory-mapping>
<local-path>c:/usr/common_jsps.jar</local-path>
<url-pattern>*.jsp</url-pattern>
</virtual-directory-mapping>The following table describes the elements you can define within the virtual-directory-mapping element.
The WebLogic Server implementation of virtual directory mapping requires that you have a directory that matches the url-pattern of the mapping. The image example requires that you create a directory named images at c:/usr/gifs/images. This allows the servlet container to find images for multiple Web applications in the images directory.
Use this element to specify a class for URL pattern matching. The WebLogic Server default URL match mapping class is weblogic.servlet.utils.URLMatchMap, which is based on J2EE standards. Another implementation included in WebLogic Server is SimpleApacheURLMatchMap, which you can plug in using the url-match-map element.
Rule for SimpleApacheURLMatchMap:
If you map *.jws to JWSServlet then
http://foo.com/bar.jws/baz will be resolved to JWSServlet with pathInfo = baz.
Configure the URLMatchMap to be used in weblogic.xml as in the following example:
<url-match-map>
weblogic.servlet.utils.SimpleApacheURLMatchMap
</url-match-map>
The security-permission element specifies a single security permission based on the Security policy file syntax. Refer to the following URL for Sun's implementation of the security permission specification:
http://java.sun.com/j2se/1.3/docs/guide/security/PolicyFiles.html#FileSyntax
Disregard the optional codebase and signedBy clauses.
<security-permission-spec>
grant { permission java.net.SocketPermission "*", "resolve" };
</security-permission-spec>
permission java.net.SocketPermission is the permission class name.
"*" represents the target name.
The context-root element defines the context root of this stand-alone Web application. If the Web application is part of an EAR, not stand-alone, specify the context root in the EAR’s META-INF/application.xml file. A context-root setting in application.xml takes precedence over context-root setting in weblogic.xml.
Note that this weblogic.xml element only acts on deployments using the two-phase deployment model.
The order of precedence for context root determination for a Web application is as follows:
| Note: | The context-root element cannot be set for individual Web applications in EAR libraries. It can only bet set for Web application libraries. |
Use the wl-dispatch-policy element to assign the Web application to a configured work manager by identifying the work manager name. This Web application-level parameter can be overridden at the individual servlet or jsp level by using the per-servlet-dispatch-policy element.
Use the servlet-descriptor element to aggregate the servlet-specific elements.
The following table describes the elements you can define within the servlet-descriptor element.
The work-manager element is a sub-element of the <weblogic-web-app> element. You can define the following elements within the work-manager element.
The logging element is a sub-element of the <weblogic-web-app> element. You can define the following elements within the logging element.
The library-ref element references a library module, which is intended to be used as a Web application library in the current Web application.
<library-ref><library-name>WebAppLibraryFoo</library-name><specification-version>2.0</specification-version><implementation-version>8.1beta</implementation-version><exact-match>false</exact-match></library-ref>
Only the following sub-elements are relevant to Web applications: library-name, specification-version, implementation-version, and exact-match.
You can define the following elements within the library-ref element.
For WebLogic Server 10.0, backward compatibility for WebLogic Server 9.2 or earlier is supported via the backward-compatible element within the jsp-descriptor element. For additional information about web application backward compatibility, see
Compatibility with Previous Releases in Upgrading WebLogic Application Environments.
JSP 2.1 is supported as of WebLogic Server 10.0. Depending on the version of the Web application (version 2.4 or 2.5) and the setting of the backward-compatible element in the weblogic.xml descriptor file, Weblogic Server 10.0 will also support JSP 2.0.
backward-compatibility flag is set to false, then:backward-compatibility flag is set to true, then all JSP/TAG files will follow the previous JSP 2.0 or earlier behavior.backward-compatibility flag is set.
The Servlet 2.5 specification mandates that only the java.lang.*, javax.servlet.*, javax.servlet.jsp.*, and javax.servlet.http.* packages be implicitly imported. In compliance with the Servlet 2.5 specification, WebLogic Server 10.0 will only import these mandated packages. Whereas, previous releases of WebLogic Server also imported the java.io.*, java.util.*, and javax.servlet.jsp.tagext.* packages.
WebLogic Server 10.0 will follow the previous 2.4 or earlier behavior and import the non-mandated packages, if any of the following occur:
To configure your Web container at a global level, use the WebAppContainerMBean. For information on the WebAppContainerMBean attributes and how to use them to specify domain-wide defaults for all of your Web applications, see the WebAppContainerMBean at
http://e-docs.bea.com/wls/docs100/wlsmbeanref/mbeans/WebAppContainerMBean.html.
|