bea.com | products | dev2dev | support | askBEA |
|
e-docs > WebLogic Server > Developing Web Applications for WebLogic Server > weblogic.xml Deployment Descriptor Elements |
Developing Web Applications for WebLogic Server |
weblogic.xml Deployment Descriptor Elements
This following sections describe the deployment descriptor elements that you define in the weblogic.xml file. The root element for weblogic.xml is <weblogic-web-app>. The following elements are defined within the <weblogic-web-app> element:
You can also access the Document Type Descriptor (DTD) for weblogic.xml at http://www.bea.com/servers/wls710/dtd/weblogic710-web-jar.dtd.
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 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 security role and one or more principals in the realm, 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>
The following table describes the elements you can define within a security-role-assignment element.
The reference-descriptor element maps a name used in the Web Application to the JNDI name of a server resource. The reference-description element contains two elements: The resource-description element maps a resource, for example, a DataSource, to its JNDI name. The ejb-reference element maps an EJB to its JNDI name.
The following table describes the elements you can define within a resource-description element
The following table describes the elements you can define within a ejb-reference-description element
.
The session-descriptor element defines parameters for HTTP sessions, as shown in the following example:
<session-descriptor>
<session-param>
<param-name>
CookieDomain
</param-name>
<param-value>
myCookieDomain
</param-value>
</session-param>
</session-descriptor>
Session Parameter Names and Values
The following table describes the valid session parameter names and values you can define within a session-param element:
Specifies the domain for which the cookie is valid. For example, setting CookieDomain to .mydomain.com returns cookies to any server in the *.mydomain.com domain. The domain name must have at least two components. Setting a name to *.com or *.net is not valid. If unset, this parameter defaults to the server that issued the cookie. For more information, see Cookie.setDomain() in the Servlet specification from Sun Microsystems. |
||
Specifies the comment that identifies the session tracking cookie in the cookie file. If unset, this parameter defaults to WebLogic Session Tracking Cookie. You may provide a more specific name for your application. |
||
Sets the life span of the session cookie, in seconds, after which it expires on the client. If the value is 0, the cookie expires immediately. The maximum value is Integer.MAX_VALUE, where the cookie lasts forever. If set to -1, the cookie expires when the user exits the browser. For more information about cookies, see Using Sessions and Session Persistence in Web Applications. |
||
Defines the session cookie name. Defaults to JSESSIONID if unset. You may set this to a more specific name for your application. |
||
Specifies the pathname to which the browser sends cookies. If unset, this parameter defaults to / (slash), where the browser sends cookies to all URLs served by WebLogic Server. You may set the path to a narrower mapping, to limit the request URLs to which the browser sends cookies. |
||
Use of session cookies is enabled by default and is recommended, but you can disable them by setting this property to false. You might turn this option off to test. |
||
Sets the time, in seconds, that WebLogic Server waits between doing house-cleaning checks for timed-out and invalid sessions, and deleting the old sessions and freeing up memory. Use this parameter to tune WebLogic Server for best performance on high traffic sites. The minimum value is every second (1). The maximum value is once a week (604,800 seconds). If unset, the parameter defaults to 60 seconds. |
||
If you have set PersistentStoreType to file, this parameter sets the directory path where WebLogic Server will store the sessions. The directory path is either relative to the temp directory or an absolute path. The temp directory is either a generated directory under the WEB-INF directory of the Web Application, or a directory specified by the context-param javax.servlet.context.tmpdir. 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 PersistentStoreDir. Note that the size of each session can vary as the size of serialized session data changes. You can make file-persistent sessions clusterable by making this directory a shared directory among different servers. |
||
Specifies the name of a JDBC connection pool to be used for persistence storage. |
||
Sets the persistent store method to one of the following options: |
||
Sets the name of the cookie used for cookie-based persistence. For more information, see Using Cookie-Based Session Persistence. |
||
Sets the size of the session ID. The minimum value is 8 bytes and the maximum value is Integer.MAX_VALUE. 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 parameters), which limits the amount of data that can be transmitted using URL re-writing. To allow more space for parameters, use this parameter to limit the size of the session ID that is randomly generated by WebLogic Server. |
||
Sets the time, in seconds, that WebLogic Server waits before timing out a session, where x is the number of seconds between a session's activity. Minimum value is 1, default is 3600, and maximum value is integer MAX_VALUE. 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. This parameter can be overridden by the session-timeout element (defined in minutes) in web.xml. For more information, see session-config. |
||
Sets the time, in seconds, that WebLogic Server waits before timing out a JDBC connection, where x is the number of seconds between. |
||
Enables URL rewriting, which encodes the session ID into the URL and provides session tracking if cookies are disabled in the browser. |
||
If you enable Session Monitoring in the WebLogic Server Administration Console, set this parameter to the name of the session parameter you will use to identify each session that is monitored. |
The jsp-descriptor element defines parameter names and values for JSPs. You define the parameters as name/value pairs. The following example shows how to configure the compileCommand parameter. Enter all of the JSP configurations using the pattern demonstrated in this example:
<jsp-descriptor>
<jsp-param>
<param-name>
compileCommand
</param-name>
<param-value>
sj
</param-value>
</jsp-param>
</jsp-descriptor>
JSP Parameter Names and Values
The following table describes the parameter names and values you can define within a <jsp-param> element.
javac, or the Java compiler defined for a server under the configuration |
Specifies the full pathname of the standard Java compiler used to compile the generated JSP servlets. For example, to use the standard Java compiler, specify its location on your system as shown below: <param-value> For faster performance, specify a different compiler, such as IBM Jikes or Symantec sj. |
|
Passes one or more command-line flags to the compiler. Enclose multiple flags in quotes, separated by a space. For example: <jsp-param> |
||
Name of a Java compiler that is executed in WebLogic Servers's virtual machine. (Used in place of an executable compiler such as javac or sj.) If this parameter is set, the compileCommand parameter is ignored. |
||
When set to true this adds JSP line numbers to generated class files to aid debugging. |
||
Specifies the default character set used in the JSP page. Use standard Java character set names. If not set, this parameter defaults to the encoding for your platform. A JSP page directive (included in the JSP code) overrides this setting. For example: |
||
When set to true, the JSP compiler uses the encoding specified with the contentType attribute contained in the page directive on the JSP page, or, if a contentType is not specified, the encoding defined with the encoding parameter in the jsp-descriptor. When set to false, the JSP compiler uses the default encoding for the JVM when creating the intermediate .java file. |
||
When true, upon the first request for a JSP the newly created JspStub is mapped to the exact request. If exactMapping is set to false the webapp container generates non-exact url mapping for JSPs. exactMapping allows path info for JSP pages. |
||
Saves the Java files that are generated as an intermediary step in the JSP compilation process. Unless this parameter is set to true, the intermediate Java files are deleted after they are compiled. |
||
If a JSP file has numerous or deeply nested custom JSP tags and you receive a java.lang.VerifyError exception when compiling, use this flag to allow the JSPs to compile correctly. |
||
Specifies the package into which all JSP pages are compiled. |
||
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. If set to 0, pages are checked on every request. If set to -1, page checking and recompiling is disabled. |
||
When set to true, WebLogic Server automatically precompiles all JSPs when the Web Application is deployed or re-deployed or when starting WebLogic Server. |
||
When set to true, debugging information is printed out to the browser, the command prompt, and WebLogic Server log file. |
||
The name of a directory where WebLogic Server saves the generated Java and compiled class files for a JSP. |
The auth-filter element specifies an authentication filter HttpServlet class.
The <container-descriptor> element defines general parameters for Web Applications.
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 that the default behavior has changed with the release of the Servlet 2.3 specification, which states that authentication is not required for forwarded requests.
If the redirect-content-type element is set, then the servlet container sets that type on the response for internal redirects (for example, for welcome files).
If the redirect-content element is set, then the servlet container will use that as the value for the user readable data used in a redirect.
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.
The <charset-params> Element is used to define codeset behavior for non-unicode operations.
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
A path which, if included in the URL of a request, signals WebLogic Server to use the Java character set specified by <java-charset-name>. |
||
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
Specifies the IANA character set name that is to be mapped to the Java character set specified by the <java-charset-name> 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.
Contains the URL pattern of the mapping. Must follow the rules specified in Section 11.2 of the Servlet API Specification. |
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 preprocessor element contains the declarative data of a preprocessor.
The following table describes the elements you can define within the preprocessor element.
The preprocessor-mapping element defines a mapping between a preprocessor and a URL pattern.
The following table describes the elements you can define within the preprocessor-mapping element.
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 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. See "Two-Phase Deployment" in Deploying WebLogic Server Applications..
The order of precedence for context root determination for a Web application is as follows:
Use the wl-dispatch-policy element to assign the Web application to a configured execute queue by identifying the execute queue name. This Web application level param can be overridden at the individual servlet/jsp level. For example:
<servlet>
...
<init-param>
<param-name>wl-dispatch-policy</param-name>
<param-value>CriticalAppQueue</param-value>
</init-param>
</servlet>
This is an equivalent of <run-as> for init method for servlets.
<init-as>
<servlet-name>FooServlet</servlet-name>
<principal-name>joe</principal-name>
</init-as>
This is an equivalent of <run-as> for destroy method for servlets.
<servlet-name>BarServlet</servlet-name>
<principal-name>bob</principal-name>
This sorts the directory listing by file name, size, or date last modified.
<index-directory-enabled>true</index-directory-enabled>
<index-directory-sort-by>SIZE</index-directory-sort-by>