Skip Headers

Oracle® Containers for J2EE Servlet Developer's Guide 10g Release 3 (10.1.3) B14426-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# B Web Module C onfiguration Files

This appendix contains reference information for the OC4J-specific Web module configuration files `global-web-application.xml` (for global and default configuration) and `orion-web.xml` (for application-level configuration). There is also an overview of these files and their relationship to the standard `web.xml` file.

- Overview of Web Application Configuration Files

- Hierarchy of orion-web.xml and global-web-application.xml

- Elements and Attributes of orion-web.xml, global-web-application.xml

## Overview of Web Application Configuration Files

A Web descriptor specifies and configures a set of J2EE Web components: static pages, servlets, and JSP pages. The Web components may together form an independent Web application and be deployed in an independent WAR file. More typically, however, they will form just part of an overall J2EE application, being deployed in a WAR file within the EAR file of the J2EE application.

OC4J uses three categories of Web descriptors. The following sections discuss each of them and summarize the relationships between them:

- Standard web.xml Configuration File

- Oracle global-web-application.xml Configuration File

- Oracle orion-web.xml Configuration File

- Summary of Relationship Between Web Application Configuration Files

### Standard web.xml Configuration File

The servlet specification defines the concept and XSD of a Web descriptor, called `web.xml`, that you must include in the `/WEB-INF` directory of the associated WAR file. The `web.xml` file specifies and configures the Web components of the WAR file, as well as other components, such as EJBs, that the Web components may call. See the servlet specification for more information.

Here is sample `web.xml` configuration specifying, among other things, a servlet, the servlet mapping, and a local EJB lookup:

    <web-app>
       <display-name>stateful, web-app:</display-name>
       <description>no description</description>
       <welcome-file-list>
          <welcome-file>index.html</welcome-file>
       </welcome-file-list>

       <ejb-local-ref>
          <ejb-ref-name>CartBean</ejb-ref-name>
          <ejb-ref-type>Session</ejb-ref-type>
          <local-home>cart.CartHome</local-home>
          <local>cart.Cart</local>
       </ejb-local-ref>

       <servlet>
          <servlet-name>cart</servlet-name>
          <servlet-class>cart.CartServlet</servlet-class>
          <init-param>
             <param-name>param1</param-name>
             <param-value>1</param-value>
          </init-param>
       </servlet>
       <servlet-mapping>
          <servlet-name>cart</servlet-name>
          <url-pattern>/cart</url-pattern>
       </servlet-mapping>
       <security-role>
          <role-name>users</role-name>
       </security-role>
    </web-app>

### Oracle global-web-application.xml Configuration File

The OC4J `server.xml` file, through its `<global-web-app-config>` element, specifies the OC4J global Web application descriptor. It is typically `global-web-application.xml`, in the same directory as `server.xml`. This descriptor defines default behavior for Web applications in OC4J.

The global Web application descriptor is defined by the XSD `orion-web.xsd`. This is the same XSD as for the application-level, OC4J-specific Web descriptor, `orion-web.xml`, described in the next section, "Oracle orion-web.xml Configuration File".

The `orion-web` XSD is a superset of the standard XSD for `web.xml`. There is a `<web-app>` subelement of the `<orion-web-app>` top-level element in `orion-web` XSD, which has the same specification as the top-level `<web-app>` element of `web.xml`. There are also many other subelements of `<orion-web-app>` for specifying and configuring OC4J-specific features.

For any default settings you specify within the `<web-app>` element in `global-web-application.xml`, you can add to or, optionally, override these settings through `<web-app>` settings in `web.xml`. You can then add to or, optionally, override the resulting settings through `<web-app>` settings in `orion-web.xml`.

Note: Avoid using the `<web-app>` element in `global-web-application.xml` or `orion-web.xml` if possible. Because it is customary to look in `web.xml` for any `<web-app>` entries, having such entries elsewhere could be confusing and may cause difficulty during troubleshooting.

For any default settings you specify outside the `<web-app>` element in `global-web-application.xml`, you can add to or, optionally, override these settings through parallel settings in `orion-web.xml`.

For detailed information about the elements and attributes of the OC4J global Web application descriptor, see "Elements and Attributes of orion-web.xml, global-web-application.xml".

### Oracle orion-web.xml Configuration File

In addition to the standard Web descriptor, `web.xml`, and the OC4J global Web application descriptor, `global-web-application.xml` (which establishes default behavior), there is an OC4J-specific application-level Web descriptor, `orion-web.xml`.

The `orion-web.xml` descriptor is defined by a corresponding XSD. This is the same XSD as for the global Web application descriptor that was described in the previous section, "Oracle global-web-application.xml Configuration File".

You can provide an `orion-web.xml` file as well as the `web.xml` file, also in the `/WEB-INF` directory of your WAR file. Use `orion-web.xml` to add to or, optionally, override any default settings in `global-web-application.xml`, as well as to add to or override any settings in `web.xml`.

Including an `orion-web.xml` file in your WAR file (inside the EAR file) is optional. If you include it, OC4J copies it into the deployment directory during deployment (under the `j2ee/home/application-deployments` directory by default). Otherwise, OC4J generates `orion-web.xml` for you in the deployment directory, using default settings from `global-web-application.xml`. Additionally, some `web.xml` settings will influence the generation of `orion-web.xml`. For example, `<resource-ref>` entries in `web.xml` will result in corresponding `<resource-ref-mapping>` entries in `orion-web.xml`. .

Note: When OC4J copies `orion-web.xml`, it may make changes to the file but these changes are transparent. For example, an attribute setting that specifies the default value may be ignored or removed.

For detailed information about the elements and attributes of the OC4J-specific Web descriptor, see "Elements and Attributes of orion-web.xml, global-web-application.xml".

### Sum mary of Relationship Between Web Application Configuration Files

You can think of the relationship between `global-web-application.xml`, `web.xml`, and `orion-web.xml` as follows:

1. The `global-web-application.xml` file establishes defaults for any Web application in OC4J.

2. The `web.xml` file overlays anything defined in the `<web-app>` element of `global-web-application.xml`, adding to and possibly overriding any Web components and other settings defined there.

3. The `orion-web.xml` file overlays everything, adding to and possibly overriding any settings from `global-web-application.xml` and `web.xml`.

## Hiera rchy of orion-web.xml and global-web-application.xml

Here is an overview of the element hierarchy for the `global-web-application.xml` and `orion-web.xml` files.

    <orion-web-app>
       <classpath>
       <context-param-mapping>
       <mime-mappings>
       <virtual-directory>
       <access-mask>
          <host-access>
          <ip-access>
       <servlet-chaining>
       <request-tracker>
       <session-tracking>
          <session-tracker>
       <resource-ref-mapping>
          <lookup-context>
             <context-attribute>
       <resource-env-ref-mapping>
       <security-role-mapping>
          <group>
          <user>
       <env-entry-mapping>
       <ejb-ref-mapping>
       <service-ref-mapping>
       <expiration-setting>
       <web-app>
       <jazn-web-app>
       <web-app-class-loader>

## Elem ents and Attributes of orion-web.xml, global-web-application.xml

This section is an alphabetical dictionary of elements of the `orion-web.xml` and `global-web-application.xml` files. See the preceding section, "Hierarchy of orion-web.xml and global-web-application.xml", if you are interested in the hierarchy.

The element descriptions in this section generally apply to either `global-web-application.xml` or to an application-specific `orion-web.xml` configuration file. The `global-web-application.xml` file configures the global application and sets defaults; the `orion-web.xml` file can override these defaults for a particular application deployment, as appropriate. See "Summary of Relationship Between Web Application Configuration Files" for a summary.

Notes: Where attributes are discussed, note that attribute values are always set inside quotes: `attribute="value"`. Most attributes of interest can be set through the Application Server Control deployment plan editor. See the Oracle Containers for J2EE Deployment Guide for information.

### <ac cess-mask>

Parent element: <orion-web-app>

Child elements: <host-access>, <ip-access>

Required? Optional; zero or one

Use subelements of `<access-mask>` to specify optional access masks for this application. You can use host names or domains to filter clients, through `<host-access>` subelements, or you can use IP addresses and subnets to filter clients, through `<ip-access>` subelements, or you can do both.

Table B-1 <access-mask> Attributes

Name | Description
--- | ---
default | Values: allow|deny Default: allow Specifies whether to allow requests from clients not identified through a `<host-access>` or `<ip-access>` subelement. Use separate `mode` attributes for the `<host-access>` and `<ip-access>` subelements to specify whether to allow requests from clients that are identified through those subelements.

### <clas spath>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

Use this element to inform OC4J of additional code locations for Web application class loading—either library files or locations for individual class files.

Table B-2 <classpath> Attributes

Name | Description
--- | ---
path | Values: String Default: n/a (required) You can specify one or more locations, separated by commas or semicolons, where a location can be either of the following: The complete path to a JAR or ZIP file, including the file name A directory path In either case, you can use an absolute path or a path that is relative to the configuration file location (`global-web-application.xml` or `orion-web.xml`, as applicable). If you specify a directory path, the classloader recognizes only individual class files in the specified directory, not JAR or ZIP files (unless those are specified separately). For example, assume the following setting in `orion-web.xml`:
    <classpath path=
          /abc/def/lib1.jar,
          /abc/def/zip1.jar,
          /abc/def,mydir
    />
The classloader recognizes the following: The `lib1.jar` and `zip1.jar` libraries (but no other libraries in `/abc/def`) Any class files in `/abc/def` Any class files in `mydir`, relative to the location of `orion-web.xml`

### <co ntext-attribute>

Parent element: <lookup-context>

Child elements: None

Required? Required if you use `<lookup-context>`; one or more

Each occurrence of this element specifies an attribute to send to a nondefault, such as third-party, JNDI context named in the parent `<lookup-context>` element.

The only mandatory attribute in JNDI is `java.naming.factory.initial`, which is the class name of the context factory implementation.

Table B-3 <context-attribute> Attributes

Name | Description
--- | ---
name | Values: String Default: n/a (required) Specifies the name of the attribute.
value | Values: String Default: n/a (required) Specifies the desired value of the attribute.

### <co ntext-param-mapping>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

This element carries information in the content of the element itself, as follows:

In `orion-web.xml`, a `<context-param-mapping>` element overrides the value specified through a corresponding `<context-param>` element in `web.xml`, for a servlet context parameter. Use the `name` attribute to match a `<param-name>` setting in `web.xml`, and use the element value to specify the new value:

    <context-param-mapping name="..." >deploymentValue</context-param-mapping>

Table B-4 <context-param-mapping> Attributes

Name | Description
--- | ---
name | Values: String Default: n/a (required) The name of the parameter for which you are specifying a new value.

### <ejb-ref-map ping>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

Use this element to declare a JNDI location for an EJB. This is in conjunction with a corresponding `<ejb-ref>` or `<ejb-local-ref>` element to declare the EJB in the `web.xml` file. The `<ejb-ref-mapping>` element `name` attribute corresponds to an `<ejb-ref-name>` element in `web.xml`, and the `location` attribute specifies a JNDI location.

Table B-5 <ejb-ref-mapping> Attributes

Name | Description
--- | ---
name | Values: String Default: n/a (required) Specifies the EJB reference name, from an `<ejb-ref-name>` element in `web.xml`.
location | Values: String Default: n/a (required) Specifies a JNDI location from which to look up the EJB home.

### <env-e ntry-mapping>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

In `orion-web.xml`, an `<env-entry-mapping>` element overrides the value specified through a corresponding `<env-entry>` element in `web.xml`, for an environment entry. Use the `name` attribute to match an `<env-entry-name>` setting in `web.xml`, and use the element value to specify the new value:

    <env-entry-mapping name="..." >deploymentValue</env-entry-mapping>

Table B-6 <env-entry-mapping> Attributes

Name | Description
--- | ---
name | Values: String Default: n/a (required) The name of the environment entry for which you are specifying a new value.

### <ex piration-setting>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

This element sets the expiration for a given set of resources; that is, how long before the resources would expire in the browser. (The browser reloads an expired resource upon the next request for it.) This is useful for caching policies, such as for not reloading images as frequently as documents.

Table B-7 <expiration-setting> Attributes

Name | Description
--- | ---
expires | Values: String (integer, seconds) Default: 0 Specifies the number of seconds before expiration, or `"never"` for no expiration. The default setting calls for immediate expiration.
url-pattern | Values: String Default: n/a (required) Specifies the URL pattern that the expiration applies to. This could be as in the following example:
    url-pattern="*.gif"

### <gro up>

Parent element: <security-role-mapping>

Child elements: None

Required? Optional; zero or more

Use this subelement of `<security-role-mapping>` to specify a group to map to the security role specified in the parent `<security-role-mapping>` element. All the members of the specified group are included in this role.

Table B-8 <group> Attributes

Name | Description
--- | ---
name | Values: String Default: n/a (required) Specifies the name of the group.

### <ho st-access>

Parent element: <access-mask>

Child elements: None

Required? Optional; zero or more

This subelement of `<access-mask>` specifies a host name or domain from which to allow or deny access.

Table B-9 <host-access> Attributes

Name | Description
--- | ---
domain | Values: String Default: n/a (required) Specifies the host or domain.
mode | Values: allow|deny Default: n/a (required) Specifies whether to allow or deny access from the specified host or domain.

### <ip-ac cess>

Parent element: <access-mask>

Child elements: None

Required? Optional; zero or more

This subelement of `<access-mask>` specifies an IP address and subnet mask from which to allow or deny access.

Table B-10 <ip-access> Attributes

Name | Description
--- | ---
ip | Values: String Default: n/a (required) Specifies the IP address, as a 32-bit value (for example, `"123.124.125.126`").
netmask | Values: String Default: No default Specifies the relevant subnet mask, if any (example: `"255.255.255.0"`).
mode | Values: allow|deny Default: n/a (required) Specifies whether to allow or deny access from the specified IP address and subnet mask.

### <jazn-w eb-app>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or one

Use this element to configure the OracleAS JAAS Provider and Single Sign-On (SSO) properties for servlet execution. You must set these features appropriately to invoke a servlet under the privileges of a particular security subject.

When Oracle Identity Management is being used as the security provider for a Web application, with SSO for authentication, you can synchronize a servlet session with the OracleAS JAAS Provider user context through `<jazn-web-app>`. To synchronize the session with the user context, set the `sso.session.synchronize` property to "`true`", the default, in a `<property>` subelement under `<jazn-web-app>`:

    <jazn-web-app ...>
    <property name="sso.session.synchronize" value="true"/>
    </jazn-web-app>

Or you can set the property to "false".

For additional information about JAAS and the features described for this element, see the Oracle Containers for J2EE Security Guide. You can also refer to related Sun Microsystems documentation at the following location:

    http://java.sun.com/j2se/1.4.2/docs/guide/security/jaas/JAASRefGuide.html

Table B-11 <jazn-web-app> Attributes

Name | Description
--- | ---
auth-method | Values: BASIC|SSO|COREIDSSO Default: BASIC This is the method of HTTP client authentication. "`BASIC`" is for basic J2EE authentication; "`SSO`" is for Oracle Application Server Single Sign-On. "`COREIDSSO`" is for using Oracle COREid Access and Identity as the security provider, with single sign-on Another value for `auth-method`, "`DIGEST`", is deprecated in the OC4J 10.1.3 implementation, but still supported for backward compatibility. Instead, you can use the standard `DIGEST` setting for `auth-method` in the `web.xml` file. Note: Use "`BASIC`" if your application uses a custom `LoginModule` instance.
runas-mode | Values: Boolean Default: false This mode is deprecated in the OC4J 10.1.3 implementation, but still supported for backward compatibility. A new, consolidated JAAS mode replaces the `runas-mode` and `doasprivileged-mode` for servlets. Set `runas-mode` to "`true`" to invoke the servlet using the privileges of a particular subject. A subject is defined by an instance of the `javax.security.auth.Subject` class and includes a set of facts regarding a single entity, such as a person. Such facts include identities and security-related attributes, such as passwords and cryptographic keys. With the default `runas-mode="false"` setting, `doasprivileged-mode` is ignored.
doasprivileged-mode | Values: Boolean Default: true This mode is deprecated in the OC4J 10.1.3 implementation, but still supported for backward compatibility. A new, consolidated JAAS mode replaces the `runas-mode` and `doasprivileged-mode` for servlets. `Assuming runas-mode="true"`, use the default "`true`" setting of `doasprivileged-mode` to use privileges of a particular subject without being limited by the access-control restrictions of the server. Values of `runas-mode="true"` and `doasprivileged-mode="true"` result in use of the static `Subject.doAsPrivileged()` method when the servlet is invoked. Values of `runas-mode="true"` and `doasprivileged-mode="false"` result in use of the static `Subject.doAs()` method. In either case, the JAAS Provider passes in the `Subject` instance in the method call. When the `doAsPrivileged()` method is used, the JAAS Provider invokes the method with a null `java.security.AccessControlContext` instance. This is to start the action freshly and execute the servlet without the restrictions of the current server `AccessControlContext` instance. When the `doAs()` method is used, an `AccessControlContext` instance is retrieved from the current thread (from the server).

### <lo okup-context>

Parent element: <resource-ref-mapping>

Child elements: <context-attribute>

Required? Optional; zero or one

This element, through its `location` attribute, specifies an optional JNDI context that will be used instead of the default context in looking up the resource mapped in the parent `<resource-ref-mapping>` element. This is useful when you are connecting to third-party modules, such as a third-party JMS server, for example. (Either use the JNDI context implementation supplied by the resource vendor, or, if none exists, write an implementation that negotiates with the vendor software.)

Table B-12 <lookup-context> Attributes

Name | Description
--- | ---
location | Values: String Default: n/a (required) Specifies the name of a nondefault (such as third-party) JNDI context.

### <mi me-mappings>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

This element defines the path to a file containing MIME mappings to use.

Table B-13 <mime-mappings> Attributes

Name | Description
--- | ---
path | Values: String Default: n/a (required) Specifies the path or URL for the file, either absolute or relative to the location of the `orion-web.xml` file.

### <o rion-web-app>

Parent element: n/a (root)

Child elements: <access-mask>, <classpath>, <context-param-mapping>, <ejb-ref-mapping>, <env-entry-mapping>, <expiration-setting>, <jazn-web-app>, <mime-mappings>, <request-tracker>, <resource-env-ref-mapping>, <resource-ref-mapping>, <security-role-mapping>, <service-ref-mapping>, <servlet-chaining>, <session-tracking>, <virtual-directory>, <web-app>, <web-app-class-loader>

Required? Required; one only

This is the root element for specifying OC4J-specific configuration of a Web application.

Note: The `always-redeploy`, `deployment-time`, and `deployment-version` attributes are not supported for direct use, so are not documented, although `deployment-time` and `deployment-version` may receive container-generated values for the time of deployment and the OC4J version. Modifying these parameters has no effect.

Table B-14 <orion-web-app> Attributes

Name | Description
--- | ---
autojoin-session | Values: Boolean Default: true Specifies whether users should be assigned a session as soon as they log in to the application.
default-buffer-size | Values: Non-negative integer (bytes) Default: 2048 Specifies the default size of the output buffer for servlet responses, in bytes.
default-charset | Values: String Default: iso-8859-1 For JSP pages only, this attribute specifies the ISO character set to use by default. In general, for JSP 2.0 users, we instead recommend standard `<page-encoding>` functionality (under the `web.xml` `<jsp-config>` element, according to the JSP 2.0 specification), to specify character sets according to URL patterns. However, `default-charset` may be useful if you have large numbers of JSP pages, particularly across multiple applications, to avoid the necessity of making numerous changes in your EAR files. Also, you can use `default-charset` to set a base default, then use `<page-encoding>` functionality to override the default for particular URL patterns. See the JSP and servlet specifications for more information about the `<jsp-config>` and `<page-encoding>` elements.
default-mime-type | Values: String Default: No default This specifies a default content type for servlet responses, for situations where the `setContentType()` method is not called from the servlet implementation. If `default-mime-type` is not specified, then there is no default content type.
development | Values: Boolean Default: false This attribute is a convenience flag to use during development. If `development` is set to `"true"`, then the OC4J server checks a particular directory for updates to servlet source files. If a source file has changed since the last request, then OC4J will, upon the next request, recompile the servlet, redeploy the Web application, and reload the servlet and any dependency classes. The directory is determined by the setting of the `source-directory` attribute. Note that the OC4J JSP container does not take any special action for the `development` flag. Any related functionality is handled by the OC4J servlet container.
directory-browsing | Values: allow|deny Default: deny Specifies whether to allow directory browsing for a URL that ends in "`/`". Assume the following circumstances: There is no `index.html` file in the application root directory. There is no welcome file defined in the `web.xml` file. If `directory-browsing` is set to "`allow`" under these circumstances, then a URL ending in "`/`" results in the contents of the corresponding directory being displayed in the user's browser. If `directory-browsing` is set to "`deny`" under these circumstances, then a URL ending in "`/`" results in an error indicating that the directory contents cannot be displayed. If there is a defined welcome file or there is an `index.html` file in the application root directory, then the contents of that file are displayed, regardless of the `directory-browsing` setting.
enable-jsp-dispatcher-shortcut | Values: Boolean Default: true A "`true`" setting results in significant performance improvements by the OC4J JSP container, especially in conjunction with a "`true`" setting for the `simple-jsp-mapping` attribute. This is particularly true for JSP pages with numerous `jsp:include` statements. Use of the "`true`" setting assumes, however, that if you define JSP files with `<jsp-file>` elements in `web.xml`, then you have corresponding `<url-pattern>` specifications for those files.
file-modification-check-interval | Values: String (integer, milliseconds) Default: 1000 This attribute determines when to check a static file, such as an HTML file, to see whether its timestamp has changed and it should therefore be reloaded from the file system. When a static file is first accessed, it is loaded from the file system and also cached. For each subsequent access, there is the following logic: If the elapsed time since the last check of the file timestamp is less than the specified file-check interval, then the timestamp is not checked and the file is loaded from cache. If the elapsed time since the last check of the file timestamp is greater than the specified file-check interval, then the timestamp is checked. If the timestamp has changed since the last check, the file is loaded from the file system, otherwise it is loaded from cache. Specify this value in milliseconds. Zero or a negative number specifies that the file timestamp is always checked. For performance reasons, a very large value ("`1000000`", for example) is recommended in a production environment.
jsp-cache-directory | Values: String Default: ./persistence (relative to the deployment directory of the application) This attribute specifies the JSP cache directory, which is used as a base directory for output files from the JSP translator. It is also used as a base directory for application-level TLD caching.
jsp-cache-tlds | Values: on|off|standard Default: standard This flag indicates whether persistent TLD caching is enabled for JSP pages. The "`standard`" or "`on`" setting enables caching, and in either case `.tld` files are inherited from the global TLD locations according to the `jsp-taglib-locations` attribute of `<orion-web-app>`. The "`standard`" setting also results in a search for `.tld` files in the application `/WEB-INF` directory, and these are added to the files inherited from the global level. Note that the `/WEB-INF/lib` and `/WEB-INF/classes` subdirectories are not searched. The "`on`" setting also results in a search for `.tld` files among all files within the application, and these are added to the files inherited from the global level. The "`off`" setting disables persistent TLD caching.
jsp-print-null | Values: Boolean Default: true Set this flag to "`false`" to print an empty string instead of the default "null" string for null output from a JSP page.
jsp-taglib-locations | Values: String Default: See below If persistent TLD caching is enabled for JSP pages (through the `jsp-cache-tlds` attribute), you can use `jsp-taglib-locations` to specify a semicolon-delimited list of one or more directories to use as "well-known" locations. Tag library JAR files can be placed in these locations for sharing across multiple JSP pages and Web applications, and for TLD caching You can specify any combination of absolute directory paths or relative directory paths. Relative paths would be under `ORACLE_HOME` if `ORACLE_HOME` is defined, or under the current directory (from which the OC4J process was started) if `ORACLE_HOME` is not defined. The default value is as follows: `ORACLE_HOME``/j2ee/home/jsp/lib/taglib/` if `ORACLE_HOME` is defined `./jsp/lib/taglib` if `ORACLE_HOME` is not defined. Important: Use the `jsp-taglib-locations` attribute only in `global-web-application.xml`, not in `orion-web.xml`.
jsp-timeout | Values: Non-negative integer (seconds) Default: 0 (no timeout) Specifies a period of time after which any JSP page will be removed from memory if it has not been requested. This frees up resources in situations in which some pages are called infrequently.
persistence-path | Values: String Default: No default (by default, no persistence) Indicates where to store servlet `HttpSession` objects for persistence across server restarts or application redeployments. Specify a relative path, which will be relative to an OC4J temporary storage area under the `application-deployments` directory. If no value is specified, then there is no persistence of session objects across restarts or redeployments. Session objects must be serializable (directly or indirectly implementing the `java.io.Serializable` interface) or remoteable (directly or indirectly implementing the `java.rmi.Remote` interface) for this feature to work. Note: This attribute is ignored if OC4J clustering is enabled.
schema-major-version | Values: String Default: No default The major version number of the `orion-web.xml` XSD. If you create `orion-web.xml` manually, set this attribute to 10 for use with the OC4J 10.1.3 implementation. Note: This attribute does not appear directly in the XSD for `orion-web.xml`. It is according to the `attributeGroup` specification in the top-level OC4J XSD.
schema-minor-version | Values: String Default: No default The minor version number of the `orion-web.xml` XSD. If you create `orion-web.xml` manually, set this attribute to 0 for use with the OC4J 10.1.3 implementation. Note: This attribute does not appear directly in the XSD for `orion-web.xml`. It is according to the `attributeGroup` specification in the top-level OC4J XSD.
servlet-webdir | Values: String Default: /servlet/ (see note below) Use this attribute, in conjunction with a `true` setting for the OC4J system property `http.webdir.enable`, to enable servlet invocation by class name in standalone OC4J. Once the system property is set, any `servlet-webdir` setting that starts with a slash ("`/`") enables this feature and specifies a special URL portion to insert after the context path to instruct OC4J to invoke a servlet by class name. Anything appearing after this path in a URL is assumed to be a class name, including the package. See "Invoking a Servlet by Class Name During OC4J Development" for additional information. This feature is typically for use in an OC4J standalone environment during development and testing; it presents a significant security risk and should not be used in a production environment. (For production deployment, use the standard `web.xml` mechanisms to define the context path and servlet path.) Here is an example of servlet invocation by class name, assuming a context path of "`/`" and a setting of `servlet-webdir="/servlet/"`:
    http://www.example.com:8888/servlet/foo.SessionServlet
Invocation by class name is disabled by a setting of `servlet-webdir=""` (empty quotes) or by the OC4J system property setting `http.webdir.enable=false`. Note: Any `servlet-webdir` setting, including the default, is overridden by the default `false` setting of `http.webdir.enable`. See the Oracle Containers for J2EE Configuration and Administration Guide for general information about OC4J system properties.
simple-jsp-mapping | Values: Boolean Default: false Set this to "`true`" if "`*.jsp`" is mapped to only the `oracle.jsp.runtimev2.JspServlet` front-end JSP servlet. This would be specified in the `<servlet>` elements of any Web descriptors affecting your application (`global-web-application.xml`, `web.xml`, and `orion-web.xml`). A "`true`" setting allows performance improvements for JSP pages.
source-directory | Values: String Default: /WEB-INF/src (if it exists), or /WEB-INF/classes For situations in which the `development` attribute is set to `"true"`, the `source-directory` setting specifies where to look for servlet source files to auto-compile. If you use the default location, OC4J keeps track of the location of the `/WEB-INF` directory of your application after deployment. Note that modified source files will be found anywhere under the `source-directory` directory, according to package name.
temporary-directory | Values: String Default: ./temp This is the path to a temporary directory that can be used by servlets and JSP pages for scratch files. The path can be either absolute, or relative to the deployment directory. A servlet may use a temporary directory, for example, to write information to disk as a user is entering data in a form (perhaps for interim or short-term storage before the information is written to a database). The specified directory can then be recalled from the servlet context, where it is available through the attribute `javax.servlet.context.tempdir`, as in the following example.
    File file = (File)application.getAttribute
                      ("javax.servlet.context.tempdir");
A `java.io.File` object is returned, from which you can obtain directory information and contents.

Note: Processing related to the enable-jsp-dispatcher-shortcut, `jsp-cache-directory`, `jsp-cache-tlds`, `jsp-print-null`, `jsp-taglib-locations`, `jsp-timeout`, and `simple-jsp-mapping` attributes are handled by the OC4J JSP container. For more information about these attributes and related features, see the Oracle Containers for J2EE Support for JavaServer Pages Developer's Guide.

### <req uest-tracker>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

This element specifies a servlet to use as a request tracker. A request tracker is invoked for each separate request sent from a browser to the server, at the time that the corresponding response is committed (immediately before the response is actually sent). Request trackers are useful for logging information, for example.

You must define any request trackers in `orion-web.xml`, not `global-web-application.xml`, because a `<request-tracker>` element points to a servlet defined within the same application. There can be multiple request trackers, each one defined in a separate `<request-tracker>` element.

Table B-15 <request-tracker> Attributes

Name | Description
--- | ---
servlet-name | Values: String Default: n/a (required) Specifies the servlet to invoke. You can specify either the designated servlet name or the class name, according to the corresponding `<servlet-name>` or `<servlet-class>` element (both of which are subelements of a `<servlet>` element) in the `web.xml` file.

### <reso urce-env-ref-mapping>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

Use this element to declare a JNDI location for an environment resource. This is in conjunction with a corresponding `<resource-env-ref>` element in the `web.xml` file, which declares the resource. The `<resource-env-ref-mapping>` element `name` attribute corresponds to a `<resource-env-ref-name>` element in `web.xml`, and the `location` attribute specifies a JNDI location.

Table B-16 <resource-env-ref-mapping> Attributes

Name | Description
--- | ---
name | Values: String Default: n/a (required) Specifies the resource name, from `web.xml`.
location | Values: String Default: n/a (required) Specifies the JNDI location from which to look up the resource.

### <res ource-ref-mapping>

Parent element: <orion-web-app>

Child elements: <lookup-context>

Required? Optional; zero or more

Use this element to declare a JNDI location for an external resource, such as a data source, JMS queue, or mail session. This is in conjunction with a corresponding `<resource-ref>` element in the `web.xml` file, which declares the resource. The `<resource-ref-mapping>` element `name` attribute corresponds to a `<res-ref-name>` element in `web.xml`, and the `location` attribute specifies the JNDI location.

Following is an example using this element and its subelements:

      <resource-ref-mapping location="jdbc/HyperSonicDS" name="jdbc/myDS">
        <lookup-context location="foreign/resource/location">
          <context-attribute name="java.naming.factory.initial" value="classname" />
          <context-attribute name="name" value="value" />
        </lookup-context>
      </resource-ref-mapping>

Table B-17 <resource-ref-mapping> Attributes

Name | Description
--- | ---
name | Values: String Default: n/a (required) Specifies the resource name, from `web.xml`. For example:
    name="jdbc/TheDSVar"
location | Values: String Default: n/a (required) Specifies a JNDI location from which to look up the resource. For example:
    location="jdbc/TheDS"

### <sec urity-role-mapping>

Parent element: <orion-web-app>

Child elements: <group>, <user>

Required? Optional; zero or more

This element maps a security role to specified users and groups, or to all users. It maps to a security role of the same name specified through a `<security-role>` element in the `web.xml` file. Use either the `impliesAll` attribute or an appropriate combination of subelements—`<group>`, `<user>`, or both.

See the Oracle Containers for J2EE Enterprise JavaBeans Developer's Guide for additional information about the `<security-role-mapping>` element in OC4J configuration files.

Important: OC4J has an automatic security mapping feature. By default, if a security role defined in `web.xml` has the same name as an OC4J group defined in `system-jazn-data.xml` (or other valid user manager), then OC4J maps them. However, this feature is completely disabled if you do any explicit mapping through the `<security-role-mapping>` element. If you use `<security-role-mapping>` at all, OC4J assumes that you want explicit mapping only. This is to prevent unintended implicit mappings when a user may intend to declare explicit mappings only.

Table B-18 <security-role-mapping> Attributes

Name | Description
--- | ---
impliesAll | Values: Boolean Default: false Specifies whether this mapping applies to all users.
name | Values: String Default: n/a (required) Specifies the name of the security role, matching a name specified in a `<role-name>` subelement of a `<security-role>` element in `web.xml`.

### <servi ce-ref-mapping>

Parent element: <orion-web-app>

Child elements: According to its own schema definition

Required? Optional; zero or more

This element is for use in conjunction with a `<service-ref>` element that appears in the `web.xml` file to declare a Web service. You can use it to specify OC4J-specific quality of service features for the corresponding Web service, such as security, logging, and auditing. See the Oracle Application Server Web Services Developer's Guide for complete information.

Note that as a `<service-ref>` element can appear in a `web.xml`, `ejb-jar.xml`, or `application-client.xml` file, a corresponding `<service-ref-mapping>` element can appear in an `orion-web.xml`, `orion-ejb-jar.xml`, or `orion-application-client.xml` file. Supported features of the `<service-ref-mapping>` element are according to its own XSD, which is imported into the `orion-web`, `orion-ejb-jar`, and `orion-application-client` XSDs.

### <ser vlet-chaining>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

This element specifies a servlet to call when the response of the current servlet is set to a specified MIME type. The specified servlet is called after the current servlet. This is known as servlet chaining, for filtering or transforming certain kinds of output.

Important: Servlet chaining is an older and proprietary mechanism with functionality similar to that of standard servlet filtering, which was introduced in version 2.3 of the servlet specification. Use servlet filtering instead. The OC4J `<servlet-chaining>` element is deprecated in the current release and will be desupported in the next release.

Table B-19 <servlet-chaining> Attributes

Name | Description
--- | ---
mime-type | Values: String Default: n/a (required) Specifies the MIME type to trigger the chaining (for example, `"text/html"`).
servlet-name | Values: String Default: n/a (required) Specifies the servlet to call when the specified MIME type is encountered. The servlet name is tied to a servlet class through its definition in the `<web-app>` element of `global-web-application.xml`, `web.xml`, or `orion-web.xml`.

### <session-tracker>

Parent element: <session-tracking>

Child elements: None

Required? Optional; zero or more

This subelement of `<session-tracking>` specifies a servlet to use as a session tracker. A session tracker is invoked as soon as a session is created; specifically, at the same time as the invocation of the `sessionCreated()` method of the HTTP session listener (an instance of a class implementing the `javax.servlet.http.HttpSessionListener` interface). Session trackers are useful for logging information, for example.

You must define any session trackers in `orion-web.xml`, not `global-web-application.xml`, because a `<session-tracker>` element points to a servlet defined within the same application. There can be multiple session trackers, each one defined in a separate `<session-tracker>` element.

Table B-20 <session-tracker> Attributes

Name | Description
--- | ---
servlet-name | Values: String Default: n/a (required) Specifies the servlet to invoke. You can specify either the designated servlet name or the class name, according to the corresponding `<servlet-name>` or `<servlet-class>` element under the relevant `<servlet>` element in the `web.xml` file.
set-secure | Values: Boolean Default: false Specifies whether all session cookies generated by OC4J for an application will be returned by the client only when the HTTPS protocol is being used. If set-secure="`true`", all session cookies will include the `secure` attribute, which instructs the browser to return the cookies only over the secure HTTPS protocol. If set-secure="`false`", the browser will return cookies over any protocol.

### <ses sion-tracking>

Parent element: <orion-web-app>

Child elements: <session-tracker>

Required? Optional; zero or one

This element specifies the session-tracking settings for this application. Session tracking is accomplished through cookies, assuming a cookie-enabled browser. The servlet to use as the session tracker is specified through the `<session-tracker>` subelement.

Notes: If cookies are disabled, session tracking can be achieved only if your servlet explicitly calls the `encodeURL()` method of the response object, or the `encodeRedirectURL()` method for redirects. OC4J does not support auto-encoding, in which session IDs are automatically encoded into the URL by the servlet container. This process is nonstandard and expensive.

Table B-21 <session-tracking> Attributes

Name | Description
--- | ---
cookies | Values: enabled|disabled Default: enabled Specifies whether to send session cookies. The name of a session cookie is `JSESSIONID`. (See "How OC4J Can Use Cookies for Session Tracking" for information about the `JSESSIONID` cookie.)
cookie-domain | Values: String Default: No default Specifies the desired domain for `JSESSIONID` session cookies. This overrides any `domain` setting in applicable `Set-Cookie` HTTP response headers. You can use this attribute to track a single client or user over multiple Web sites. The setting must start with a period ("`.`"). For example:
    <session-tracking cookie-domain=".us.oracle.com" />
In this case, the same session cookie is used and reused when the user visits any site that matches the "`.us.oracle.com`" domain pattern, such as `webserv1.us.oracle.com` or `webserv2.us.oracle.com`. The domain specification must consist of at least two elements, such as "`.us.oracle.com`" or "`.oracle.com`". A setting of "`.com`", for example, is illegal. Here are two scenarios in which cookie domain functionality is useful: You can use it to share session state between nodes of a Web application running on different hosts. In an OC4J standalone environment, you can use it for a shared application, where `shared="true"` in a `<web-app>` element in the Web site XML file. In such an application, some requests go through a secure port and some go through a nonsecure port, with each port denoting a separate Web site. You would want the same cookie used regardless of which port is being used. (In this scenario, using `cookie-domain` is unnecessary, however, if you use the default ports of 80 for HTTP and 443 for HTTPS. The client would already recognize these as different ports of the same Web site, and only a single cookie would be used.)
cookie-path | Values: String Default: No default You can use this to optionally specify the URL path value that applies to `JSESSIONID` session cookies. This specifies the subset of URLs for which session cookies are valid within any applicable domain (which depends on the cookie domain setting). If specified, it overrides any `path` setting in applicable `Set-Cookie` HTTP response headers. If not specified, and if there is no `path` setting in the `Set-Cookie` headers, the default cookie path is the Web application context path.
cookie-max-age | Values: Non-negative integer (seconds) Default: No default This number is sent with `JSESSIONID` session cookies and specifies a maximum interval (in seconds) for the browser to save the cookie. By default, the cookie is kept in memory during the browser session and discarded afterward.

### <u ser>

Parent element: <security-role-mapping>

Child elements: None

Required? Optional; zero or more

Use this subelement of `<security-role-mapping>` to specify a user to map to the security role specified in the parent `<security-role-mapping>` element.

Table B-22 <user> Attributes

Name | Description
--- | ---
name | Values: String Default: n/a (required) Specifies the name of the user.

### <vi rtual-directory>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

This element adds a virtual directory mapping for static content, working in a way that is conceptually similar to symbolic links on a UNIX system, for example. The virtual directory enables you to make the contents of the real document root directory available to the application without physically residing in the Web application WAR file. This would be useful, for example, to link an enterprise-wide error page into multiple WAR files.

Table B-23 <virtual-directory> Attributes

Name | Description
--- | ---
real-path | Values: String Default: n/a (required) This is a real path, such as `/usr/local/realpath` in UNIX or `C:\testdir` in Windows.
virtual-path | Values: String Default: n/a (required) This is a virtual path to map to the specified real path.

### <we b-app>

Parent element: <orion-web-app>

Child elements: According to its own schema definition in the servlet specification

Required? Optional; zero or one

This element is used as in the standard `web.xml` file. See "Standard web.xml Configuration File" for an overview, or the servlet specification for complete information. You can establish defaults for `<web-app>` settings in `global-web-application.xml`. In `web.xml`, application-specific `<web-app>` settings can override the defaults. In `orion-web.xml`, deployment-specific `<web-app>` settings can override the settings in `web.xml`.

### <web-ap p-class-loader>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or one

Use this element for class-loading instructions.

Table B-24 <web-app-class-loader> Attributes

Name | Description
--- | ---
search-local-classes-first | Values: Boolean Default: false Set this to "`true`" to search and load WAR file classes before system classes. By default, system classes are searched and loaded first.
include-war-manifest-class-path | Values: Boolean Default: true Set this to "`false`" to not include the classpath specified in the WAR file manifest `Class-Path` attribute when searching and loading classes from the WAR file (regardless of the `search-local-classes-first` setting). Otherwise, the classplath from the WAR file manifest is included.

Notes: If both attributes are set to "`true`", the overall classpath is constructed so that classes physically residing in the WAR file are loaded prior to any classes from the WAR file manifest classpath. So you can assume that in the event of any conflict, classes physically residing in the WAR file will take precedence. To comply with the servlet specification, `search-local-classes-first` functionality cannot be used in loading classes in `java.*` or `javax.*` packages. If you want to use an XML parser or JDBC driver packaged with your application in place of the Oracle XML parser or JDBC driver, set the `search-local-classes-first` attribute to "`true`". You also need to specify the default inherited Oracle library in the `<remove-inherited>` tag in `orion-application.xml`. For complete instructions, see Oracle Containers for J2EE Developer's Guide.