BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
| WebLogic Server Doc Home | Web Applications | Previous Topic | Next Topic | Contents | Index | View as PDF

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:

- description Element

- weblogic-version Element

- security-role-assignment Element

    <role-name>

    <principal-name>

- reference-descriptor Element

    resource-description Element

    <res-ref-name>

    <jndi-name>

    ejb-reference-description Element

    <ejb-ref-name>

    <jndi-name>

- session-descriptor Element

    Session Parameter Names and Values

- jsp-descriptor Element

    JSP Parameter Names and Values

- container-descriptor Element

    check-auth-on-forward Element

- charset-params Element

    input-charset Element

    <resource-path>

    <java-charset-name>

    charset-mapping Element

    <iana-charset-name>

    <java-charset-name>

The DOCTYPE header for weblogic.xml is as follows:

>     <!DOCTYPE weblogic-web-app PUBLIC
>       "-//BEA Systems, Inc.//DTD Web Application 6.1//EN"
>       "http://www.bea.com/servers/wls610/dtd/weblogic-web-jar.dtd">

You can also access the Document Type Descriptor (DTD) for weblogic.xml at http://www.bea.com/servers/wls610/dtd/weblogic-web-jar.dtd.

description Element

The description element is a text description of the Web Application.

weblogic-version Element

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.

security-role-assignment Element

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.

Element | Required Optional | Description
--- | --- | ---
<role-name> | Required | Specifies the name of a security role.
<principal-name> | Required | 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 the Programming WebLogic Security.

reference-descriptor 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.

resource-description Element

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

Element | Required/ Optional | Description
--- | --- | ---
<res-ref-name> | Required | Specifies the name of a resource reference.
<jndi-name> | Required | Specifies a JNDI name for the resource.

.

ejb-reference-description Element

The following table describes the elements you can define within a ejb-reference-description element

Element | Required/ Optional | Description
--- | --- | ---
<ejb-ref-name> | Required | Specifies the name of an EJB reference used in your Web Application.
<jndi-name> | Required | Specifies a JNDI name for the reference.

.

session-descriptor 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:

Parameter Name | Default Value | Parameter Value
--- | --- | ---
CookieDomain | Null | 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.
CookieComment | Weblogic Server Session Tracking Cookie | 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.
CookieMaxAgeSecs | -1 | 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.
CookieName | JSESSIONID | Defines the session cookie name. Defaults to JSESSIONID if unset. You may set this to a more specific name for your application. When using ProxyByExtension, you may use either the ;jsessionid identifier or the ?jsessionid identifier to pass rewritten URLs.
CookiePath | Null | 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.
CookiesEnabled | true | 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 Using URL Rewriting.
CookieSecure | false | If set, the client's browser will only send the cookie back over an HTTPS connection. This ensures that the cookie ID is secure and should only be used on websites that exclusively use HTTPS. Once this feature is enabled, session cookies over HTTP will no longer work; if your client is directed to a non-HTTPS location the session will not be sent.
EncodeSessionIdInQueryParams | false | By default, when you use the HTTPServletResponse.encodeURL(URL) method to encode a URL in the HTTP response, the session identifier is added to the URL as a path parameter after the ; character in the URL. This behavior is defined by the Servlet 2.3 J2EE specification, implemented as of Version 6.1 of WebLogic Server. In Versions 6.0 and previous of WebLogic Server, however, the default behavior was to add the session identifier as a query parameter after the ? character in the URL. To enable this old behavior, set this session parameter to true. Note: You typically use this parameter when WebLogic Server interacts with Web Servers that do not completely comply with the Servlet 2.3 specification.
InvalidationIntervalSecs | 60 | 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.
PersistentStoreDir | session_db | 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. You must create this directory manually.
PersistentStoreTable | wl_servlet_sessions | Applies only when PersistentStoreType is set to jdbc. This is used when you choose a database table name other than the default.
PersistentStorePool | None | Specifies the name of a JDBC connection pool to be used for persistence storage. For more information on setting up a database connection pool, see Managing JDBC Connectivity.
PersistentStoreType | memory | Sets the persistent store method to one of the following options: memory—Disables persistent session storage. file—Uses file-based persistence (See also PersistentStoreDir, above). jdbc—Uses a database to store persistent sessions. (see also PersistentStorePool, above). replicated—Same as memory, but session data is replicated across the clustered servers. cookie—All session data is stored in a cookie in the user's browser. replicated_if_clustered—If the Web application is deployed on a clustered server, the in-effect PersistentStoreType will be replicated. Otherwise, memory is the default.
PersistentStoreCookieName | WLCOOKIE | Sets the name of the cookie used for cookie-based persistence. For more information, see Using Cookie-Based Session Persistence.
IDLength | 52 | 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.
TimeoutSecs | 3600 | 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 Element.
JDBConnectionTimeoutSecs | 120 | Sets the time, in seconds, that WebLogic Server waits before timing out a JDBC connection, where x is the number of seconds between.
URLRewritingEnabled | true | Enables URL rewriting, which encodes the session ID into the URL and provides session tracking if cookies are disabled in the browser.
ConsoleMainAttribute |  | 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. For more information, see Monitoring a WebLogic Domain.

jsp-descriptor Element

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

Parameter Name | Default Value | Parameter Value
--- | --- | ---
compileCommand | javac, or the Java compiler defined for a server under the configuration /tuning tab of the WebLogic Server Administration Console | 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> /jdk130/bin/javac.exe </param-value> For faster performance, specify a different compiler, such as IBM Jikes or Symantec sj.
compileFlags | None | Passes one or more command-line flags to the compiler. Separate multiple flags with a space. For example: <jsp-param> <param-name>compileflags</param-name> <param-value>-g -v</param-value> </jsp-param>
compilerclass | None | 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.
encoding | Default encoding of your platform | Specifies the default character set used in the JSP page. Use standard Java character set names. If unset, this parameter defaults to the encoding for your platform. A JSP page directive (included in the JSP code) overrides this setting. For example: <%@ page contentType="text/html; charset=custom-encoding"%>
compilerSupports Encoding | true | 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.
keepgenerated | false | 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.
noTryBlocks | false | 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.
packagePrefix | jsp_servlet | Specifies the package into which all JSP pages are compiled.
pageCheckSeconds | 1 | 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, the page is not checked until server restart. Any classes used by the JSP page that live in the servlet classpath are also re-loaded.
precompile | false | When set to true, WebLogic Server automatically precompiles all modified JSPs when the Web Application is deployed or re-deployed or when starting WebLogic Server.
verbose | true | When set to true, debugging information is printed out to the browser, the command prompt, and WebLogic Server log file.
workingDir | internally generated directory | The name of a directory where WebLogic Server saves the generated Java and compiled class files for a JSP.
compiler | javac | Sets the JSP compiler for use with this instance of WebLogic Server.
superclass | weblogic.servlet.jsp.JspBase | Provides a means to override the default superclass for JSPs. The JSPs are compiled as servlet classes extending from this base class.
precompileContinue | false | When set to true, WebLogic Server continues precompiling all modified JSPs even if some of those JSPs fail during compilation. Only takes effect when precompile is set to true.

container-descriptor Element

The <container-descriptor> element defines general parameters for Web Applications.

check-auth-on-forward Element

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.

redirect-with-absolute-url

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.

charset-params Element

The <charset-params> Element is used to define codeset behavior for non-unicode operations.

input-charset Element

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

Element | Required/ Optional | Description
--- | --- | ---
<resource-path> | Required | 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>.
<java-charset-name> | Required | Specifies the Java characters set to use.

.

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

Element | Required/ Optional | Description
--- | --- | ---
<iana-charset-name> | Required | Specifies the IANA character set name that is to be mapped to the Java character set specified by the <java-charset-name> element.
<java-charset-name> | Required | Specifies the Java characters set to use.

.

Copyright © 2001 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.