6 Configuration File Descriptions

Element Descriptions 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.

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: Specifies 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.

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.

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-application.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 Representation 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.

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

Element Descriptions 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.

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.

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.

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 Web 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 Representation 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.

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