Skip Headers

Oracle® Application Server Containers for J2EE Servlet Developer's Guide 10g Release 2 (10.1.2) B14017-02 |
| Library | Product | Contents | Index

Previous | Next |

# 6 Configuration File Descriptions

This chapter describes the elements and attributes of OC4J configuration files for servlets and Web sites. It includes the following sections:

- Configuration for global-web-application.xml and orion-web.xml

- Configuration for Web Site XML Files

  Note: The detailed discussion in this chapter regarding configuration files and their elements and attributes assumes an OC4J standalone development environment. In an Oracle Application Server environment using Enterprise Manager, configuration is through Application Server Control Console Web module pages, and many of the files and their properties are invisible to the user. For considerations in configuring and deploying a production application with Enterprise Manager in Oracle Application Server, see Chapter 7, "Configuration with Enterprise Manager".

## Config uration for global-web-application.xml and orion-web.xml

The following sections provide detailed information about the `global-web-application.xml` and `orion-web.xml` configuration files:

- Element Descriptions for global-web-application.xml and orion-web.xml

- DTD for global-web-application.xml and orion-web.xml

- Hierarchical Representation of global-web-application.xml and orion-web.xml

- Sample global-web-application.xml Settings

For an overview of these files, see "OC4J and J2EE Web Descriptors".

### Element Des criptions for global-web-application.xml and orion-web.xml

This section describes the elements and attributes of the `global-web-application.xml` and `orion-web.xml` files.

The element descriptions in this section apply to either `global-web-application.xml` or 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.

<orion-web-app ... >

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

Notes: The `autoreload-jsp-pages` and `autoreload-jsp-beans` attributes of the `<orion-web-app>` element are not currently supported by the OC4J JSP container. You can use the JSP `main_mode` configuration parameter for functionality equivalent to that of `autoreload-jsp-pages`. See the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for information about this parameter. The `<servlet-filter>` subelement and the `document-root`, `get-locale-from-user`, `internationalize-resources`, and `default-mime-type` attributes are no longer supported.

Subelements of `<orion-web-app>`:

    <classpath>
    <context-param-mapping>
    <mime-mappings>
    <virtual-directory>
    <access-mask>
    <cluster-config>
    <servlet-chaining>
    <request-tracker>
    <session-tracking>
    <resource-ref-mapping>
    <env-entry-mapping>
    <security-role-mapping>
    <ejb-ref-mapping>
    <expiration-setting>
    <jazn-web-app>
    <web-app-class-loader>
    <authenticate-on-dispatch>
    <web-app>

Attributes of `<orion-web-app>`:

- `default-buffer-size`: Spec ifies the default size of the output buffer for servlet responses, in bytes. The default is `"2048"`.

  Note: The `default-buffer-size` attribute does not affect JSP buffer size.

- `default-charset`: This attribute specifies the ISO character set to use by default. The default is `"iso-8859-1"`.

- `deployment-version`: This attribute specifies the version of OC4J under which this Web application was deployed. If this value does not match the current version, then the application is redeployed. This is an internal server value and should not be changed.

- `development`: This attribute is a convenience flag 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 (described next). Supported values for `development` are `"true"` and `"false"` (default).

  Note: The OC4J JSP container does not currently support the `development` flag. It is for servlets only. Use the JSP `main_mode` flag for similar functionality for JSP pages, as documented in the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide. Features of the old Orion JSP container that relate to the `development` flag do not apply to the OC4J JSP container.

- `source-directory`: 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. The default is `"/WEB-INF/src"` if it exists, otherwise `"/WEB-INF/classes"`.

- `directory-browsing`: Specifies whether to allow directory browsing for a URL that ends in "`/`". Supported values are `"allow"` and `"deny"` (default).

  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.

- `file-modification-check-interval`: This attribute applies to static files such as HTML files and is the amount of time, in milliseconds, for which a file-modification check is valid. Within that time period since the last check, further checks are not necessary. Zero or a negative number specifies that a check always occurs. The default is `"1000`". For performance reasons, a very large value ("`1000000`", for example) is recommended in a production environment.

- `jsp-print-null`: Set this flag to "`false`" to print an empty string instead of the default "null" string for null output from a JSP page. The default is "`true`".

- `jsp-timeout`: Specify an integer value, in seconds, 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. The default value is 0 (zero), for no timeout.

- `jsp-cache-directory`: 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. The default value is "`./persistence`", relative to the deployment directory of the application.

- `jsp-cache-tlds`: This flag indicates whether persistent TLD caching is enabled for JSP pages. TLD caching is implemented both at a global level, for TLD files in "well-known" tag library locations, and at an application level, for TLD files under the `WEB-INF` directory. Use a "`true`" or "`on`" setting, which is the default, to search for TLD files among all application files. A setting of "`standard`" searches for TLD files only in `/WEB-INF` and subdirectories other than `/WEB-INF/classes` or `/WEB-INF/lib`. A setting of "`false`" or "`off`" disables this feature. Well-known locations are according to the `jsp-taglib-locations` attribute.

- `jsp-taglib-locations`: 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.

  or:

  - `./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`.

- `simple-jsp-mapping`: Set this flag to "`true`" if "`*.jsp`" is mapped to only the `oracle.jsp.runtimev2.JspServlet` front-end JSP servlet in the `<servlet>` elements of any Web descriptors affecting your application (`global-web-application.xml`, `web.xml`, and `orion-web.xml`). This allows performance improvements for JSP pages. The default setting is "`false`".

- `enable-jsp-dispatcher-shortcut`: A "`true`" setting, which is the case by default, 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.

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

- `persistence-path`: Indicates where OC4J should 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. There is no default value. If no value is defined, then there is no persistence of session objects across restarts or redeployments. Following is an example:

      <orion-web-app ... persistence-path="persistdir" ... >
        ...
      </orion-web-app>

  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.

  The `persistence-path` attribute is ignored if OC4J clustering is enabled, according to the `<cluster-config>` subelement of the `<orion-web-app>` element.

- `servlet-webdir`: Specifies the path for invoking a servlet by class name. Anything appearing after this path in a URL is assumed to be a class name, including the package, as appropriate.

  This feature is typically for use in an OC4J standalone environment during development and testing. For deployment, use the standard `web.xml` mechanisms for defining the context path and servlet path.

  Here is an example of servlet invocation by class name, assuming a setting of `servlet-webdir="/servlet/"`:

      http://www.example.com:8888/servlet/foo.bar.SessionServlet

  Important: Any `servlet-webdir` setting that starts with a slash ("`/`") enables invocation by class name. This presents a significant security risk and should not be used in a production environment. You can disable invocation by class name with a setting of `servlet-webdir=""` (empty quotes) or by setting the OC4J system property `http.webdir.enable` to a value of `false`. The `servlet-webdir` attribute for an application takes its default value from `global-web-application.xml` if there is a setting there. If there is no setting in `global-web-application.xml`, then the default value is `""`. Also see "Servlet Invocation by Class Name During OC4J Development" and "Additional Security Considerations".

- `temporary-directory`: 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. The default setting is "`./temp`".

  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.

<classpath ... >

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

Attribute of `<classpath>`:

- `path`: 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`

<context-param-mapping ... >deploymentValue</context-param-mapping>

In `orion-web.xml`, this element overrides the value of a `context-param` setting in the `web.xml` file. It is used to keep the EAR assembly clean of deployment-specific values. The new value is specified in the tag body.

Attribute of `<context-param-mapping>`:

- `name`: This attribute specifies the name of the `context-param` setting to override.

<mime-mappings ... >

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

Attribute of `<mime-mappings>`:

- `path`: This attribute specifies the path or URL for the file, either absolute or relative to the location of the `orion-web.xml` file.

<virtual-directory ... >

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.

Attributes of `<virtual-directory>`:

- `real-path`: This is a real path, such as `/usr/local/realpath` in UNIX or `C:\testdir` in Windows.

- `virtual-path`: This is a virtual path to map to the specified real path.

<access-mask ... >

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.

Subelements of `<access-mask>`:

    <host-access>
    <ip-access>

Attribute of `<access-mask>`:

- `default`: Specifies whether to allow requests from clients not identified through a `<host-access>` or `<ip-access>` subelement. Supported values are `"allow"` (default) and `"deny"`. 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.

<host-access ... >

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

Attributes of `<host-access>`:

- `domain`: Specifies the host or domain.

- `mode`: Specifies whether to allow or deny access from the specified host or domain. Supported values are "`allow`" (default) or "`deny`".

<ip-access ... >

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

Attributes of `<ip-access>`:

- `ip`: Specifies the IP address, as a 32-bit value (example: `"123.124.125.126`").

- `netmask`: Specifies the relevant subnet mask (example: `"255.255.255.0"`).

- `mode`: Specifies whether to allow or deny access from the specified IP address and subnet mask. Supported values are "`allow`" (default) or "`deny`".

<cluster-config ... >

Use this element if, and only if, you want to use OC4J clustering. Remove it or comment it out otherwise. Clustered applications have their HTTP session data replicated between clusters in the cluster island. Objects in the HTTP session data must be serializable (directly or indirectly implementing the `java.io.Serializable` interface) or remoteable (directly or indirectly implementing the `java.rmi.Remote` interface) for the session replication to work.

See the Oracle Application Server Performance Guide for general information about clustering.

Attributes of `<cluster-config>`:

- `host`: This is the multicast host/IP for transmitting and receiving cluster data. The default is `"230.230.0.1"`.

- `id`: This is the ID (number) of this cluster node to identify itself within the cluster. The default is based on the local machine IP.

- `port`: This is the port through which to transmit and receive cluster data. The default is `"9127"`.

<servlet-chaining ... >

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.

Note: Servlet chaining is an older mechanism with essentially the same functionality as standard servlet filtering, which was introduced in version 2.3 of the servlet specification. Use servlet filtering instead. See "Servlet Filters".

Attributes of `<servlet-chaining>`:

- `mime-type`: Specifies the MIME type to trigger the chaining, such as `"text/html"`.

- `servlet-name`: 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`.

<request-tracker ... >

This element specifies a servlet to use as a request tracker. 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.

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

There can be multiple request trackers, each one defined in a separate `<request-tracker>` element.

Attribute of `<request-tracker>`:

- `servlet-name`: Specifies the servlet to invoke. You can specify either the 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.

<session-tracking ... >

This element specifies the session-tracking settings for this application. Session tracking is accomplished through cookies, assuming a cookie-enabled browser.

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. Therefore, OC4J does not support the `<session-tracking>` attributes `autoencode-urls` and `autoencode-absolute-urls`. Also see "Session Tracking in OC4J".

For general information about servlet sessions, see "Servlet Sessions".

The servlet to use as the session tracker is specified through a subelement.

Subelement of `<session-tracking>`:

    <session-tracker>

Attributes of `<session-tracking>`:

- `autojoin-session`: Specifies whether users should be assigned a session as soon as they log in to the application. Supported values are `"true"` and `"false"` (default).

- `cookies`: Specifies whether to send session cookies. Supported values are `"enabled"` (default) and `"disabled"`.

- `cookie-domain`: Specifies the desired domain for cookies. 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 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 OC4J standalone, you can use it for a shared application, when `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-max-age`: This number is sent with the session cookie and specifies a maximum interval (in seconds) for the browser to persist the cookie to the browser cookie cache. By default, the cookie is kept in memory during the browser session and discarded afterward.

<session-tracker ... >

This subelement of `<session-tracking>` specifies a servlet to use as a session tracker. 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.

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

There can be multiple session trackers, each one defined in a separate `<session-tracker>` element.

Attribute of `<session-tracker>`:

- `servlet-name`: Specifies the servlet to invoke. You can specify either the 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.

<resource-ref-mapping ... >

Use this element to declare a reference to an external resource such as a data source, JMS queue, or mail session. This ties a resource reference name to a JNDI location when deploying.

Subelement of `<resource-ref-mapping>`:

    <lookup-context>

Attributes of `<resource-ref-mapping>`:

- `location`: Specifies the JNDI location from which to look up the resource. For example:

      location="jdbc/TheDS"

- `name`: Specifies the resource reference name, which matches the name of a `resource-ref` element in the `web.xml` file. For example:

      name="jdbc/TheDSVar"

<lookup-context ... >

This subelement of `<resource-ref-mapping>` specifies an optional JNDI context (`javax.naming.Context` instance) that will be used to retrieve the resource. This is useful when 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.

Subelement of `<lookup-context>`:

    <context-attribute>

Attribute of `<lookup-context>`:

- `location`: Specifies the name to look for in the "foreign" (such as third-party) JNDI context when retrieving the resource.

<context-attribute ... >

This subelement of `<lookup-context>` (which is a subelement of `<resource-ref-mapping>`) specifies an attribute to send to the "foreign", such as third-party, JNDI context.

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

Attributes of `<context-attribute>`:

- `name`: Specifies the name of the attribute.

- `value`: Specifies the value of the attribute.

<env-entry-mapping ... >deploymentValue</env-entry-mapping>

In `orion-web.xml`, this element overrides the value of an `env-entry` setting in the `web.xml` file. It is used to keep the EAR assembly clean of deployment-specific values. The new value is specified in the tag body.

Attribute of `<env-entry-mapping>`:

- `name`: Specifies the name of the `env-entry` setting to override.

<security-role-mapping ... >

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 in the `web.xml` file. The `impliesAll` attribute or an appropriate combination of subelements—`<group>`, `<user>`, or both—should be used.

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

Subelements of `<security-role-mapping>`:

    <group>
    <user>

Attributes of `<security-role-mapping>`:

- `impliesAll`: Specifies whether this mapping implies all users. Supported values are `"true"` or `"false"` (default).

- `name`: Specifies the name of the security role. It must match a name specified in a `<role-name>` subelement of a `<security-role>` element in `web.xml`.

  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 `jazn-data.xml` (or other valid user managers), 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.

<group ... >

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

Attribute of `<group>`:

- `name`: Specifies the name of the group.

<user ... >

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

Attribute of `<user>`:

- `name`: Specifies the name of the user.

<ejb-ref-mapping ... >

This element creates a mapping between an EJB reference, defined in an `<ejb-ref>` element, and a JNDI location when deploying.

The `<ejb-ref>` element can appear within the `<web-app>` element of `orion-web.xml` or `web.xml` and is used to declare a reference to an EJB.

Attributes of `<ejb-ref-mapping>`:

- `location`: Specifies the JNDI location from which to look up the EJB home.

- `name`: Specifies the EJB reference name, which matches the `<ejb-ref-name>` setting of the `<ejb-ref>` element.

<expiration-setting ... >

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.

Attributes of `<expiration-setting>`:

- `expires`: Specifies the number of seconds before expiration, or `"never"` for no expiration. The default setting is "`0`" (zero), for immediate expiration.

- `url-pattern`: Specifies the URL pattern that the expiration applies to, such as in the following example:

      url-pattern="*.gif"

<jazn-web-app ... >

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.

Attributes of `<jazn-web-app>`:

- `auth-method`: Supported values are "`SSO`", to employ Oracle Application Server Single Sign-On for HTTP client authentication, and "`DIGEST`", to use the digest authentication mechanism. Note that these settings are also supported for `<jazn-web-app>` in the `orion-application.xml` file.

- `runas-mode`: 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`: 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).

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

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

<web-app-class-loader ... >

Use this element for classloading instructions. See "Loading WAR File Classes Before System Classes in OC4J" for additional information.

Attributes of `<web-app-class-loader>`:

- `search-local-classes-first`: Set this to "`true`" to search and load WAR file classes before system classes. The default setting is "`false`".

- `include-war-manifest-class-path`: 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. The default setting is "`true`".

  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.

<authenticate-on-dispatch ... >

Use this element to disable OC4J authentication of forward or include targets.

Attributes of `<authenticate-on-dispatch>`:

- `value`: Set this to "`false`" to disable authentication of forward or include targets, which complies with the servlet specification. The default value is "`true`" to protect against security violations for applications developed against previous OC4J versions.

<web-app ... >

This element is used as in the standard `web.xml` file; see the servlet specification for details. In `global-web-application.xml`, defaults for `<web-app>` settings can be established. 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`.

### DTD for global-web-ap plication.xml and orion-web.xml

This section provides the OC4J-specific portion of the DTD for the `global-web-application.xml` and `orion-web.xml` files in the OC4J 10.1.2 implementation. This does not include the DTD portion for the standard `<web-app>` element of the `web.xml` file. (The DTD for `global-web-application.xml` and `orion-web.xml` is a superset of the standard `web.xml` DTD.)

    <!ENTITY % CHARSET "CDATA">

    <!ENTITY % WEBPATH "CDATA">

    <!ENTITY % NUMBER "CDATA">

    <!ENTITY % HOST "CDATA">

    <!ENTITY % PATH "CDATA">

    <!ENTITY % CLASSNAME "CDATA">

    <!-- A group that this security-role-mapping implies. Ie all the members of the
     specified group are included in this role. -->
    <!ELEMENT group (#PCDATA)>
    <!ATTLIST group name CDATA #IMPLIED
    >

    <!-- An attribute sent to the context. The only mandatory attribute in JNDI is
     the 'java.naming.factory.initial' which is the classname of the context factory
     implementation. -->
    <!ELEMENT context-attribute (#PCDATA)>
    <!ATTLIST context-attribute name CDATA #IMPLIED
    value CDATA #IMPLIED
    >

    <!-- Defines the relative/absolute path to a file containing mime-mappings to
     use. -->
    <!ELEMENT mime-mappings (#PCDATA)>
    <!ATTLIST mime-mappings path CDATA #IMPLIED
    >

    <!-- Specifies a codebase where classes used by this application (such as
     servlets/beans) can be found. -->
    <!ELEMENT classpath (#PCDATA)>
    <!ATTLIST classpath path CDATA #REQUIRED
    >

    <!-- The specification of an optional javax.naming.Context implementation used
     for retrieving the resource. This is useful when hooking up with 3rd party
     modules, such as a 3rd party JMS server for instance. Either use the context
     implementation supplied by the resource vendor or if none exists write an
     implementation which in turn negotiates with the vendor software. -->
    <!ELEMENT lookup-context (context-attribute+)>
    <!ATTLIST lookup-context location CDATA #IMPLIED
    >

    <!-- Specifies a servlet to use as request-tracker; request-trackers are invoked
     for every request and are useful for logging purposes, for example -->
    <!ELEMENT request-tracker (#PCDATA)>
    <!ATTLIST request-tracker servlet-name CDATA #IMPLIED
    >

    <!-- The resource-ref element is used for the declaration of a reference to
     an external resource such as a datasource, JMS queue, mail session or similar.
     The resource-ref-mapping ties this to a JNDI-location when deploying. -->
    <!ELEMENT resource-ref-mapping (lookup-context?)>
    <!ATTLIST resource-ref-mapping location CDATA #IMPLIED
    name CDATA #REQUIRED
    >

    <!-- Tag that is defined if the application is to be clustered. Clustered
     applications have their ServletContext and session data
     shared between the apps in the cluster, the values have to be either
     Serializable or be remote RMI-objects (implement java.rmi.Remote). -->
    <!ELEMENT cluster-config (#PCDATA)>
    <!ATTLIST cluster-config host %HOST; "230.0.0.1"
    id CDATA "based on local IP"
    port %NUMBER; "9127"
    >

    <!-- Specifies an optional access-mask for this application, hostnames and
     ip/subnets can be used to filter out allowed clients of this application. -->
    <!ELEMENT access-mask (host-access*, ip-access*)>
    <!ATTLIST access-mask default (allow|deny) "allow"
    >

    <!-- Overrides the value of an env-entry in the assembly descriptor. It is used
     to keep the .ear (assembly) clean from deployment-specific values. The body is
     the value. -->
    <!ELEMENT env-entry-mapping (#PCDATA)>
    <!ATTLIST env-entry-mapping name CDATA #IMPLIED
    >

    <!-- Specifies the Expires setting for a given set of resources, useful for
     caching policies (for instance for browsers not to reload images as frequently
     as documents). -->
    <!ELEMENT expiration-setting (#PCDATA)>
    <!ATTLIST expiration-setting expires CDATA #IMPLIED
    url-pattern CDATA #IMPLIED
    >

    <!-- Overrides the value of a context-param in the assembly descriptor. It is
     used to keep the .ear (assembly) clean from deployment-specific values. The
     body is the value. -->
    <!ELEMENT context-param-mapping (#PCDATA)>
    <!ATTLIST context-param-mapping name CDATA #IMPLIED
    >

    <!-- Session-tracking settings for this application. -->
    <!ELEMENT session-tracking (session-tracker*)>
    <!ATTLIST session-tracking autoencode-absolute-urls (true|false) "false"
    autoencode-urls (true|false) "true"
    autojoin-session (true|false) "false"
    cookie-domain CDATA #IMPLIED
    cookie-max-age %NUMBER; "in memory only"
    cookies (enabled|disabled) "enabled"
    >

    <!-- A user that this security-role-mapping implies. -->
    <!ELEMENT user (#PCDATA)>
    <!ATTLIST user name CDATA #IMPLIED
    >

    <!-- Adds a virtual directory mapping, used to include files that doesnt
     physically reside below the document root among the web-exposed files. -->
    <!ELEMENT virtual-directory (#PCDATA)>
    <!ATTLIST virtual-directory real-path %PATH; #IMPLIED
    virtual-path %PATH; #IMPLIED
    >

    <!-- Specifies an ip/netmask who is allowed access. -->
    <!ELEMENT ip-access (#PCDATA)>
    <!ATTLIST ip-access ip CDATA #REQUIRED
    mode (allow|deny) #REQUIRED
    netmask CDATA #IMPLIED
    >

    <!-- Specifies a servlet to use as chainer for a specified mime-type. Useful to
     filter/transform certain kinds of output. -->
    <!ELEMENT servlet-chaining (#PCDATA)>
    <!ATTLIST servlet-chaining mime-type CDATA #IMPLIED
    servlet-name CDATA #IMPLIED
    >

    <!-- Specifies a domain or netmask who is allowed access. -->
    <!ELEMENT host-access (#PCDATA)>
    <!ATTLIST host-access domain CDATA #REQUIRED
    mode (allow|deny) #REQUIRED
    >

    <!-- The ejb-ref element is used for the declaration of a reference to
     another enterprise bean's home. The ejb-ref-mapping ties this to JNDI-location
     when deploying. -->
    <!ELEMENT ejb-ref-mapping (#PCDATA)>
    <!ATTLIST ejb-ref-mapping location CDATA #IMPLIED
    name CDATA #REQUIRED
    >

    <!-- The runtime mapping (to groups and users) of a role. Maps to a
     security-role of the same name in the assembly descriptor. -->
    <!ELEMENT security-role-mapping (group*, user*)>
    <!ATTLIST security-role-mapping impliesAll CDATA #IMPLIED
    name CDATA #IMPLIED
    >

    <!-- Specifies a servlet to use as session-tracker; session-trackers are invoked
     as soon as a session is created and are useful for logging purposes, for
     example -->
    <!ELEMENT session-tracker (#PCDATA)>
    <!ATTLIST session-tracker servlet-name CDATA #IMPLIED
    >

    <!-- JAZN configuration -->
    <!ELEMENT jazn-web-app (#PCDATA)>
    <!ATTLIST jazn-web-app auth-method CDATA #IMPLIED
    runas-mode (true | false) "false"
    doasprivileged-mode (true | false) "true"
    >

    <!-- Web-app classloader configuration -->
    <!ELEMENT web-app-class-loader EMPTY>
    <!ATTLIST web-app-class-loader
    search-local-classes-first (true | false) "false"
    include-war-manifest-class-path (true | false) "true"
    >

    <!-- Authentication of forward/include targets -->
    <!ELEMENT authenticate-on-dispatch EMPTY>
    <!ATTLIST authenticate-on-dispatch
    value (true | false) "true"
    >

    <!-- This file contains the orion-specific configuration for a web-application.
     The path to the file is located at
     ORION_HOME/application-deployments/deploymentName/warname(.war)/orion-web.xml
     or (web-app-root/)WEB-INF/orion-web.xml if no deployment-directory is specified
     in server.xml. -->
    <!ELEMENT orion-web-app (  classpath*,  context-param-mapping*,  mime-mappings*,
      virtual-directory*,  access-mask?,  cluster-config?,  servlet-chaining*,
      request-tracker*,  session-tracking?,  resource-ref-mapping*,
      security-role-mapping*,  env-entry-mapping*,  ejb-ref-mapping*,
      expiration-setting*,  web-app?, jazn-web-app?, web-app-class-loader?,
      authenticate-on-dispatch? )>
    <!ATTLIST orion-web-app autoreload-jsp-beans (true|false) "true"
    autoreload-jsp-pages (true|false) "true"
    default-buffer-size CDATA "2048"
    default-charset %CHARSET; "iso-8859-1"
    deployment-version CDATA #IMPLIED
    development (true|false) "false"
    directory-browsing (allow|deny) "deny"
    file-modification-check-interval %NUMBER; "1000"
    jsp-cache-directory CDATA #IMPLIED
    jsp-cache-tlds (true|on|standard|false|off) "true"
    jsp-taglib-locations CDATA #IMPLIED
    jsp-print-null (true|false) "true"
    jsp-timeout %NUMBER; "0 (never)"
    simple-jsp-mapping (true|false) "false"
    enable-jsp-dispatcher-shortcut (true|false) "true"
    persistence-path CDATA #IMPLIED
    servlet-webdir %PATH; "/servlet/"
    source-directory CDATA #IMPLIED
    temporary-directory CDATA #IMPLIED
    >

### Hierarchical Repre sentation of global-web-application.xml and orion-web.xml

This section contains a representation of the hierarchy of the `global-web-application.xml` and `orion-web.xml` files.

Note: For simplicity of presentation, end-tags are omitted.

    <orion-web-app default-buffer-size="..." default-charset="..."
                   deployment-version="..." development="..."
                   source-directory="..." directory-browsing="..."
                   file-modification-check-interval="..."
                   jsp-print-null="..." jsp-timeout="..." jsp-cache-directory="..."
                   jsp-cache-tlds="..." jsp-taglib-locations="..."
                   simple-jsp-mapping="..." enable-jsp-dispatcher-shortcut="..."
                   persistence-path="..." servlet-webdir="..."
                   temporary-directory="...">
         <classpath path="...">
         <context-param-mapping name="...">
         <mime-mappings path="...">
         <virtual-directory real-path="..." virtual-path="...">
         <access-mask default="...">
              <host-access domain="..." mode="...">
              <ip-access ip="..." netmask="..." mode="...">
         <cluster-config host="..." id="..." port="...">
         <servlet-chaining mime-type="..." servlet-name="...">
         <request-tracker servlet-name="...">
         <session-tracking autojoin-session="..." cookies="..."
                           cookie-domain="..." cookie-max-age="...">
              <session-tracker servlet-name="...">
         <resource-ref-mapping location="..." name="...">
              <lookup-context location="...">
                   <context-attribute name="..." value="...">
         <env-entry-mapping name="...">
         <security-role-mapping impliesAll="..." name="...">
              <group name="...">
              <user name="...">
         <ejb-ref-mapping location="..." name="...">
         <expiration-setting expires="..." url-pattern="...">
         <jazn-web-app auth-method="..." runas-mode="..."
                       doasprivileged-mode="...">
         <web-app-class-loader search-local-classes-first="..."
                               include-war-manifest-class-path="...">
         <authenticate-on-dispatch value="...">
         <web-app>   AS IN STANDARD WEB.XML

### Sample global-web-application.xml Settings

This is an abbreviated example of a default `global-web-application.xml` file, showing some `<orion-web-app>` attribute settings, mime-mapping settings, and the setup and mapping of the JSP and RMI front-end servlets (all possibly subject to change in the shipped product):

    <?xml version="1.0" standalone='yes'?>
    <!DOCTYPE orion-web-app PUBLIC '//Evermind//Orion web-application'
     'http://xmlns.oracle.com/ias/dtds/orion-web.dtd'>

    <orion-web-app
       jsp-cache-directory="./persistence"
       servlet-webdir="/servlet"
       development="false"
       jsp-timeout="0"
       jsp-taglib-locations="./jsp/lib/taglib"
    >

       <!-- The mime-mappings for this server -->
       <mime-mappings path="./mime.types" />

       <web-app>

          <servlet>
             <servlet-name>jsp</servlet-name>
             <servlet-class>oracle.jsp.runtimev2.JspServlet</servlet-class>
             <load-on-startup>0</load-on-startup>
             <!-- you can disable page scope listener if you
                  don't need this function. -->
             <init-param>
                <param-name>check_page_scope</param-name>
                <param-value>true</param-value>
             </init-param>
             <!-- you can set main_mode to "justrun" to speed up
                  JSP dispatching, if you don't need to recompile
                  your JSP anymore. You can always switch your
                  main_mode. Please see our doc for details -->
             <!--
             <init-param>
                <param-name>main_mode</param-name>
                <param-value>justrun</param-value>
             </init-param>
             -->
          </servlet>

          <servlet-mapping>
             <servlet-name>jsp</servlet-name>
             <url-pattern>/*.jsp</url-pattern>
          </servlet-mapping>
          <servlet-mapping>
             <servlet-name>jsp</servlet-name>
             <url-pattern>/*.JSP</url-pattern>
          </servlet-mapping>

          <servlet>
             <servlet-name>rmi</servlet-name>
             <servlet-class>
                com.evermind.server.rmi.RMIHttpTunnelServlet
             </servlet-class>
          </servlet>
          <servlet-mapping>
             <servlet-name>rmi</servlet-name>
             <url-pattern>/*.tunnelrmi</url-pattern>
          </servlet-mapping>

       </web-app>
    </orion-web-app>

## Configuration for Web Site XML Files

The following sections provide detailed information about Web site XML configuration files, including `default-web-site.xml`, for an Oracle Application Server environment, and `http-web-site.xml`, for an OC4J standalone environment:

- Element Descriptions for Web Site XML Files

- DTD for Web Site XML Files

- Hierarchical Representation of Web Site XML Files

- Sample default-web-site.xml File

For an overview of these files, see "OC4J Web Site Descriptors".

### Element De scriptions for Web Site XML Files

The element descriptions in this section apply to any OC4J Web site XML file, including `default-web-site.xml` (Oracle Application Server) and `http-web-site.xml` (OC4J standalone).

<web-site ... >

This is the root element for configuring an OC4J Web site.

Subelements of `<web-site>`:

    <description>
    <frontend>
    <web-app>
    <default-web-app>
    <user-web-apps>
    <access-log>
    <odl-access-log>
    <ssl-config>

Attributes of `<web-site>`:

- `cluster-island`: A cluster island is two or more Web servers that share session failover state for replication. Use the `cluster-island` attribute when clustering the Web tier between multiple OC4J instances in Oracle Application Server. If this attribute is set to a cluster island ID (number spawning from 1 and up), then this Web site will participate as a back-end server in the island specified by the ID. The ID is a chosen number that depends on your clustering configuration. If only one island is used, the ID is always 1.

  See the Oracle Application Server Performance Guide for general information about clustering.

- `display-name`: You can use this attribute to specify a user-friendly or informal Web site name.

- `host`: Specifies the host for this Web site, as either a DNS host name or an IP address. If a server is a "multi-home" machine (having multiple IP addresses), you can use the "`[ALL]`" setting to listen to all IP addresses. They would all be combined into this single Web site.

- `log-request-info`: Specifies whether to write information about the incoming request into the Web site log if an error occurs. Supported values are `"true"` and `"false"` (default). The Web site log is enabled through either the `<access-log>` or `<odl-access-log>` element, described later in this section. ("OC4J Logging" provides additional information about enabling logs, including the Web site log.)

- `max-request-size`: Sets a maximum size, in bytes, for incoming requests. If a client sends a request that exceeds this maximum, it will receive a "request entity too large" error. The default maximum is 15000.

- `secure`: Specifies whether to support Secure Socket Layer (SSL) functionality. Supported values are `"true"` and `"false"` (default). For a protocol setting of "`ajp13`" (used in an Oracle Application Server environment), a "`true`" setting results in secure AJP protocol between Oracle HTTP Server and OC4J. For a protocol setting of "`http`" (used in OC4J standalone), a "`true`" setting results in HTTPS protocol between the client and OC4J.

  Also note that a `secure="true"` setting requires that you use the `<ssl-config>` element (a subelement under the `<web-site>` element) to specify the keystore path and password. This element is documented later in this section.

  Note: SSL and HTTPS features are also available through Oracle HTTP Server for communication between Oracle HTTP Server and the client. For information, see Oracle Application Server Security Guide.

- `protocol`: Specifies the protocol that the Web site is using. Possible values are `"http"` and `"ajp13"` (for AJP, the default). In a production environment with Oracle Application Server, you should use only the "`ajp13`" setting. The AJP protocol is for use with Oracle HTTP Server and `mod_oc4j`. Note that each protocol must have a corresponding port, and each port must have a corresponding protocol.

  The "`http`" setting is for OC4J standalone.

  To use either an "`ajp13`" or "`http`" setting in secure mode (SSL), you must set the `secure` flag to "`true`" and use the `<ssl-config>` subelement to specify the keystore path and password. This element is documented later in this section.

- `port`: Specifies the port number for this Web site. Each port must have a corresponding protocol, and each protocol must have a corresponding port. In OC4J standalone, a `port` setting of 8888 is used by default for direct access to the OC4J listener, but you can change this as desired.

  In an Oracle Application Server environment, this port setting is overridden by OPMN, the Oracle Process Management and Notification system. Oracle Application Server uses port 7777 by default for access through Oracle HTTP Server with Oracle Application Server Web Cache enabled.

  Important: In a UNIX environment, port numbers less than 1024 require root privileges for access. Also note that if there is no port specification from the client browser, port 80 is assumed for HTTP protocol and port 443 for HTTPS.

- `use-keep-alives`: Typical behavior for a servlet container is to close a connection once a request has been completed. With a `use-keep-alives` setting of `"true"`, however, a connection is maintained across requests. For AJP protocol, connections are always maintained and this attribute is ignored. For other protocols, the default is `"true"`; disabling it may cause significant performance loss.

- `virtual-hosts`: This optional setting is useful for virtual sites sharing the same IP address. The value is a comma-delimited list of host names tied to this Web site.

<description>Description here.</description>

You can use the body of this element for a brief description of the Web site.

<frontend ... >

This element specifies a perceived front-end host and port of this Web site as seen by HTTP clients. When the site is behind a load balancer or firewall, the `<frontend>` specification is necessary to provide appropriate information to Web application code for functionality such as URL rewriting. Using the host and port specified in the `<frontend>` element, the back-end server running the application knows to refer to the front-end, instead of to itself, in any URL rewriting. This way, subsequent requests properly come in through the front-end again, instead of trying to access the back-end directly.

Attributes of `<frontend>`:

- `host`: Specifies the host name of the front-end server, such as `"www.acme.com"`.

- `port`: Specifies the port number of the front-end server, such as `"80"`.

<web-app ... >

This element binds a particular Web module to this Web site. It specifies the name of a J2EE application archive (EAR file name minus the `.ear` extension) from the `server.xml` file, and the name of a Web module within the J2EE application. The Web module is defined in the J2EE `application.xml` file in the application EAR file (or possibly in the `orion-application.xml` file in the EAR file). The Web module is bound at the location specified by the `<web-app>` element `root` attribute.

Note: It is possible to deploy a WAR file by itself, instead of within an EAR file. In OC4J standalone, such Web applications are added to the OC4J default application. (In OC4J, there must always be a parent application of some sort.) See "OC4J Default Application and Default Web Application" for more information. In this scenario, the Web site XML file `<web-app>` element specifies the name of the default application rather than the name of a J2EE application archive. More details are provided in the attribute descriptions and examples that follow.

Mapping to and from Web site XML files, particularly with respect to the `application` and `name` attributes, is shown in examples elsewhere in this document. See "Example: Mappings to and from Web Site Descriptors" (for a typical scenario of deploying a WAR file within an EAR file) and "Deploying an Independent WAR File to OC4J Standalone" (for the scenario of deploying a WAR file by itself to the OC4J default application).

Attributes of `<web-app>`:

- `access-log`: Set `access-log="false"` to override any `<access-log>` or `<odl-access-log>` element and disable access logging just for the Web application associated with this `<web-app>` element. The default setting is "`true`". (If there is no `<access-log>` or `<odl-access-log>` element in the Web site XML file, then access logging is already disabled and the `access-log` attribute has no further effect.)

- `application`: Specifies the J2EE application archive name, which is the EAR file name without the `.ear` extension, and which corresponds to the `name` attribute of an `<application>` element in the `server.xml` file.

  Notes: If you deploy a WAR file by itself in OC4J standalone, using the OC4J default application as the parent, then the `application` attribute instead reflects the name of the default application, according to the `<global-application>` element in the `server.xml` file.

- `load-on-startup`: This is an optional attribute to specify whether this Web module should be preloaded on application startup. Otherwise, it is loaded upon the first request for it. Supported values are `"true"` and `"false"` (default).

  Preloading of individual servlets, through `<load-on-startup>` elements in the application `web.xml` file, is possible only if this `<web-app>` element `load-on-startup` attribute is enabled. See "Servlet Preloading" for more information.

- `max-inactivity-time`: This is an optional integer attribute to specify the number of minutes of inactivity after which OC4J will shut down the Web module. By default, a Web module is never shut down due to inactivity.

- `name`: Specifies the name of a Web module within the specified J2EE application, and corresponds to the `<web-uri>` value (without the `.war` extension) of a `<web>` subelement of a `<module>` element in the J2EE `application.xml` file. The J2EE `application.xml` file is in the EAR file.

  Notes: If you deploy a WAR file by itself in OC4J standalone, using the OC4J default application as the parent, then the `name` attribute instead reflects the value of the `id` attribute of a `<web-module>` element in the OC4J global `application.xml` file. This is the `application.xml` file for the OC4J default application, but be aware that it is not a standard J2EE file; it is OC4J-specific. Also note that the `id` attribute, as with the `name` attribute of the `<web-app>` element, does not have the `.war` extension. An application can also have an `orion-application.xml` file in the EAR file, with `<web-module>` elements that define additional Web modules, or even override Web modules defined in the J2EE `application.xml` file (although overriding is not advised). The `name` attribute can reflect the `id` value of a `<web-module>` element in `orion-application.xml`, instead of reflecting a `<web-uri>` value in the J2EE `application.xml` file. The `orion-application.xml` file uses the same DTD as the OC4J global `application.xml` file; namely, `orion-application.dtd`.

- `root`: Specifies the path to which the Web module is to be bound, which defines the context path portion of the URL used to invoke the module. For example, if the Web module `CatalogApp` at Web site `www.example.com` is bound to the `root` setting `"/catalog"`, then it can be invoked as follows:

      http://www.example.com/catalog

  Important: The `root` attribute overrides the `<context-root>` value of the corresponding `<web>` element in the J2EE `application.xml` file. Even though the `<context-root>` element is mandatory in an `application.xml` file, its value is not used by OC4J. Specifying a `root` setting of "`/`" will override the OC4J default Web application. This setting or a null setting is not allowed by the `admin.jar` utility when binding a Web application to the Web site.

- `shared`: Allows sharing of a published Web module between Web sites, when a Web site is defined by a particular pairing of a protocol and a port. Supported values are `"true"` and `"false"` (default). Sharing implies the sharing of everything that makes up a Web application, including sessions, servlet instances, and context values. An example is to share a Web application in OC4J standalone between an HTTP site and an HTTPS site at the same context path, when SSL is required for some but not all the communications. (Performance is improved by encrypting only sensitive information, rather than all information.)

  If an HTTPS Web application is marked as shared, its session tracking strategy reverts from SSL session tracking to session tracking through cookies or URL rewriting. This could possibly make the Web application less secure, but may be necessary to work around issues such as SSL session timeouts not being properly supported in some browsers.

  Important: Use `shared="true"` only in OC4J standalone.

<default-web-app ... >

This element creates a reference to the default Web application of this Web site. For users, it is meaningful only in an OC4J standalone environment. See "OC4J Default Application and Default Web Application" for more information.

In an Oracle Application Server environment, the OC4J default Web application has system-level functionality but is not otherwise meaningful. See "OC4J Default Web Application in Oracle Application Server".

The `<default-web-app>` element uses the same attributes as the `<web-app>` element described immediately preceding, but note that the default setting of `load-on-startup` is `"true"`.

<user-web-apps ... >

Use this element to support user directories and applications. Each user has his or her own Web module and associated `web-application.xml` file. User applications are reached at `/``username``/` from the server root.

Attributes of `<user-web-apps>`:

- `max-inactivity-time`: Optional integer attribute to specify the number of minutes of inactivity after which OC4J will shut down the Web module. By default, a Web module is never shut down due to inactivity.

- `path`: Specifies a path to specify the local directory of the user application, including a wildcard for the user name. The default path setting in UNIX, for example, is `"/home/``username``"`, where `username` is replaced by the particular user name.

<access-log ... >

Use this element to enable text-based access logging for this Web site and to specify information about the access log, including the path, file name, and what information is included. The log file is where incoming requests (each access of the Web site) are logged.

Alternatively, use the `<odl-access-log>` element (described immediately following) for ODL logging. See "Oracle Diagnostic Logging Versus Text-Based Logging" for information about ODL.

Notes: For any particular Web application, the `<access-log>` element can be overridden and access logging disabled through a setting of `access-log="false"` in the `<web-app>` element for that Web application in the Web site XML file. Do not use both `<access-log>` and `<odl-access-log>`; you can use only one type of logging. (The last element in the Web site XML file would take precedence, but do not count on this behavior.)

Attributes of `<access-log>`:

- `format`: Specifies one or more of several supported variables that result in information being prepended to log entries. Supported variables are `$time` `$request`, `$ip`, `$host`, `$path`, `$size`, `$method`, `$protocol`, `$user`, `$status`, `$referer`, `$time`, `$agent`, `$cookie`, `$header`, and `$mime`. Between variables, you can type in any separator characters that you want to appear between values in the log message. The default setting is as follows:

      "$ip - $user - [$time] '$request' $status $size"

  As an example, this results in log messages such as the following (with the second message wrapping around to a second line):

      148.87.1.180 - - [06/Nov/2001:10:23:18 -0800] 'GET / HTTP/1.1' 200 2929
      148.87.1.180 - - [06/Nov/2001:10:23:53 -0800] 'GET
      /webservices/statefulTest HTTP/1.1' 200 301

  In this example, the user is null, the time is in brackets (as specified in the `format` setting), the request is in single-quotes (as specified), and the status and size in the first message are 200 and 2929, respectively.

- `path`: Specifies the path and name of the access log. This can be an absolute path or a path relative to the `j2ee/home/config` directory. The default setting in `default-web-site.xml` is the following:

      path="../log/default-web-access.log"

  Note: Note the difference between the `path` attribute of `<access-log>`, which specifies a path and file name, and the `path` attribute of `<odl-access-log>`, which specifies a path only. (ODL log file names are fixed.)

- `split`: Specifies how often to begin a new access log. Supported values are `"none"` (never, which is the default), `"hour"`, `"day"`, `"week"`, or `"month"`. For a value other than `"none"`, logs are named according to the `suffix` attribute.

- `suffix`: Specifies timestamp information to append to the base file name of the logs (as specified in the `path` attribute) if splitting is used, to make a unique name for each file. The format used is that of `java.text.SimpleDateFormat`, and symbols used in `suffix` settings are according to the symbology of that class. For information about `SimpleDateFormat` and the format symbols it uses, refer to the Sun Microsystems Javadoc at the following location:

      http://java.sun.com/j2se/1.4.2/docs/api/

  The default `suffix` setting is `"-yyyy-MM-dd"`. These characters are case-sensitive, as described in the `SimpleDateFormat` documentation.

  As an example, assume the following `<access-log>` element (using the default `suffix` value):

      <access-log path="c:\foo\web-site.log" split="day" />

  Log files are named such as in the following example:

      c:\foo\web-site-2001-11-17.log

<odl-access-log ... >

Use this element to enable ODL-based access logging for the Web site and to specify information about the access logs, including the path, and maximum values for the size of each file and the total size of all files in the log directory. The log files are where incoming requests (each access of the Web site) are logged.

Alternatively, use the `<access-log>` element (described immediately preceding) for text-based logging.

See "Oracle Diagnostic Logging Versus Text-Based Logging" for information about ODL.

Notes: For any particular Web application, the `<odl-access-log>` element can be overridden and access logging disabled through a setting of `access-log="false"` in the `<web-app>` element for that Web application in the Web site XML file. Do not use both `<access-log>` and `<odl-access-log>`; you can use only one type of logging. (The last element in the Web site XML file would take precedence, but do not count on this behavior.)

Attributes of `<odl-access-log>`:

- `path`: Specifies the path to the access log directory. This can be an absolute path or a path relative to the `j2ee/home/config` directory. For example:

      path="../log/default-web-access"

  The initial log file name in this directory is `log1.xml`. As the maximum file size (specified by the `max-file-size` attribute) is reached, subsequent log files are named `log2.xml`, `log3.xml`, and so on.

  Note: Note the difference between the `path` attribute of `<access-log>`, which specifies a path and file name, and the `path` attribute of `<odl-access-log>`, which specifies a path only. (ODL log file names are fixed.)

- `max-file-size`: Specifies the maximum size of each log file, in kilobytes.

- `max-directory-size`: Specifies the maximum total size, in kilobytes, of all log files in the directory specified in the `path` attribute.

<ssl-config ... >

This element specifies SSL configuration settings, if applicable. You must use it whenever you set the `secure` attribute of the `<web-site>` element to `"true"`.

See "Servlet Security" for related information.

Subelement of `<ssl-config>`:

    <property>

Attributes of `<ssl-config>`:

- `keystore`: A relative or absolute path to the keystore database (a binary file) used by this Web site to store certificates and keys for the user base in this installation. The path value includes the file name. A relative path is relative to the location of the Web site XML file.

  A keystore is a `java.security.KeyStore` instance and can be created and maintained using the `keytool` utility, provided with the Sun Microsystems JDK.

- `keystore-password`: The required password to open the keystore.

- `needs-client-auth`: Indicates whether the entity that is a client to OC4J, such as Oracle HTTP Server, must submit a certificate for authorization so it can communicate with OC4J. Supported values are `"true"` for "client authentication" (certificate required), and `"false"` (default, no certificate required).

- `provider`: You can use this attribute to specify a provider if you are using JSSE (Java Secure Socket Extension). By default, OC4J usually employs the Sun Microsystems implementation of SSL, using an instance of the following for the provider:

      com.sun.net.ssl.internal.ssl.Provider

  However, OC4J employs the Oracle SSL implementation in some cases, such as for SOAP and `http_client`.

- `factory`: If you are not using JSSE, use the `factory` attribute to specify an implementation of `SSLServerSocketFactory`. The default setting is:

      "JSSE: com.evermind.ssl.JSSESSLServerSocketFactory"

  If you use a third-party `SSLServerSocketFactory` implementation, you can use `<property>` subelements of the `<ssl-config>` element to send parameters to the factory.

<property ... >

Use `<property>` subelements of the `<ssl-config>` element to pass parameters to a third-party `SSLServerSocketFactory` implementation, if applicable.

Attributes of `<property>`:

- `name`: The name of a parameter to pass to the factory.

- `value`: The value of the specified parameter.

### DTD for We b Site XML Files

This section provides the DTD for Web site XML configuration files, including `default-web-site.xml` and `http-web-site.xml`, in the OC4J 10.1.2 implementation.

    <!ENTITY % WEBPATH "CDATA">

    <!ENTITY % NUMBER "CDATA">

    <!ENTITY % HOST "CDATA">

    <!ENTITY % BOOLEAN "true|false">

    <!ENTITY % PATH "CDATA">

    <!-- When enabled user dirs/apps will be supported. Each user has his own
     private web-application (and connected web-application.xml file).
     The user apps are reached at /~username/ from the server root. -->
    <!ELEMENT user-web-apps (#PCDATA)>
    <!ATTLIST user-web-apps max-inactivity-time CDATA "no shutdown"
    path %PATH; #IMPLIED
    >

    <!-- Reference to the default <a class="link"
     href="web.xml.html">web-application</a> of this site. This application will be
     bound to the root of the site. -->
    <!ELEMENT default-web-app (#PCDATA)>
    <!ATTLIST default-web-app application CDATA #IMPLIED
    load-on-startup (true|false) "true"
    max-inactivity-time %NUMBER; #IMPLIED
    name CDATA #IMPLIED
    root %WEBPATH; #IMPLIED
    shared (true|false) "false"
    >

    <!-- A short description of this web-site. -->
    <!ELEMENT description (#PCDATA)>

    <!-- Relative/absolute path to the access-log for this site, this is where
     incoming requests will be logged. -->
    <!ELEMENT access-log (#PCDATA)>
    <!ATTLIST access-log format CDATA "$ip - $user - [$time] '$request' $status
     $size"
    path CDATA #IMPLIED
    split (none|hour|day|week|month) "none"
    suffix CDATA #IMPLIED
    >

    <!-- An ODL formated log file. The max-file-size is the maximum number of
     kilobytes a single log file is allowed to grow to. The max-directory-size is
     the maximum number of kilobytes that the directory is allowed to contain. -->
    <!ELEMENT odl-access-log (#PCDATA)>
    <!ATTLIST odl-access-log path CDATA #REQUIRED max-file-size CDATA #IMPLIED
     max-directory-size CDATA #IMPLIED>

    <!-- Reference to a <a class="link" href="web.xml.html">web-application</a>.
     This application will be bound at the location specified by the 'root'
     attribute. -->
    <!ELEMENT web-app (#PCDATA)>
    <!ATTLIST web-app application CDATA #IMPLIED
    load-on-startup (true|false) "false"
    access-log (true|false) "true"
    max-inactivity-time %NUMBER; "no shutdown"
    name CDATA #IMPLIED
    root %WEBPATH; #IMPLIED
    shared (true|false) "false"
    >

    <!-- A configuration parameter. -->
    <!ELEMENT property (#PCDATA)>
    <!ATTLIST property name CDATA #IMPLIED
    value CDATA #IMPLIED
    >

    <!-- Specifies SSL-configuration settings. These settings are used if
    secure="true" is specified on the site.
    If a 3rd party SSLServerSocketFactory implementation is used then x property
    tags can be defined to send arbitary arguments to the factory. -->
    <!ELEMENT ssl-config (property*)>
    <!ATTLIST ssl-config factory CDATA
     "com.evermind.server.JSSESSLServerSocketFactory"
    keystore CDATA #IMPLIED
    keystore-password CDATA #IMPLIED
    needs-client-auth (true|false) "false"
    provider CDATA #IMPLIED
    >

    <!-- The frontend tag describes which IP, port, and so on that HTTP clients
     perceive this site to be. This is needed when acting behind a load balancer or
     firewall in order to provide the correct info to web-app code when rewriting
     URLs -->
    <!ELEMENT frontend (#PCDATA)>
    <!ATTLIST frontend host CDATA #IMPLIED
    port CDATA #IMPLIED
    >

    <!-- This file contains the configuration for a web-site. -->
    <!ELEMENT web-site (description?, frontend?, default-web-app, web-app*,
     user-web-apps?, access-log?, odl-access-log?, ssl-config?)>
    <!ATTLIST web-site cluster-island CDATA #IMPLIED
    display-name CDATA #IMPLIED
    protocol CDATA #IMPLIED
    host %HOST; "[ALL]"
    log-request-info (true|false) "false"
    max-request-size CDATA #IMPLIED
    port %NUMBER; "80"
    secure (true|false) "false"
    use-keep-alives CDATA #IMPLIED
    virtual-hosts CDATA #IMPLIED
    >

### Hierarchical Rep resentation of Web Site XML Files

This section contains a representation of the hierarchy of Web site XML configuration files, including `default-web-site.xml` and `http-web-site.xml`.

Note: For simplicity of presentation, end-tags are omitted.

    <web-site cluster-island="..." display-name="..." host="..."
              log-request-info="..." max-request-size="..." secure="..."
              protocol="..." port="..." use-keep-alives="..."
              virtual-hosts="...">
         <description>
         <frontend host="..." port="...">
         <web-app application="..." load-on-startup="..." access-log="..."
                  max-inactivity-time="..." name="..." root="..." shared="...">
         <default-web-app application="..." load-on-startup="..."
                  max-inactivity-time="..." name="..." root="..." shared="...">
         <user-web-apps max-inactivity-time="..." path="...">
         <access-log format="..." path="..." split="..." suffix="...">
         <odl-access-log path="..." max-file-size="..." max-directory-size="...">
         <ssl-config keystore="..." keystore-password="..."
                     needs-client-auth="..." provider="..." factory="...">
              <property name="..." value="...">

### Sample default-web-site.xml File

This is a sample `default-web-site.xml` file, similar to the default file provided with OC4J for an Oracle Application Server environment:

    <?xml version="1.0" standalone='yes'?>
    <!DOCTYPE web-site PUBLIC "Oracle Application Server XML Web-site"
     "http://xmlns.oracle.com/ias/dtds/web-site.dtd">

    <web-site host="myhost" port="0"  protocol="ajp13"
              display-name="Default Oracle Application Server Java WebSite"
              cluster-island="1" >

       <!-- Uncomment the following line when using clustering -->
       <!-- <frontend host="your_host_name" port="80" /> -->
       <!-- The default web-app for this site, bound to the root -->
       <default-web-app application="default" name="defaultWebApp" root="/j2ee" />
       <web-app application="default" name="dms" root="/dmsoc4j" />
       <web-app application="default" name="admin_web" root="/adminoc4j" />

       <!-- Access Log, where requests are logged to -->
       <access-log path="../log/default-web-access.log" />

       <!-- Uncomment this if you want to use ODL logging capabilities
       <odl-access-log path="../log/default-web-access" max-file-size="1000"
                       max-directory-size="10000"/>
       -->

    </web-site>