Skip Headers
Oracle® Containers for J2EE Servlet Developer's Guide
10g Release 3 (10.1.3)
B14426-01
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

B Web Module Configuration Files

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

Overview of Web Application Configuration Files

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

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

Standard web.xml Configuration File

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

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

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

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

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

Oracle global-web-application.xml Configuration File

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

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

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

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


Note:

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

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

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

Oracle orion-web.xml Configuration File

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

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

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

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


Note:

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

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

Summary of Relationship Between Web Application Configuration Files

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

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

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

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

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

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

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

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

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


Notes:

  • Where attributes are discussed, note that attribute values are always set inside quotes: attribute="value".

  • Most attributes of interest can be set through the Application Server Control deployment plan editor. See the Oracle Containers for J2EE Deployment Guide for information.


<access-mask>

Parent element: <orion-web-app>

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

Required? Optional; zero or one

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

Table B-1 <access-mask> Attributes

Name Description
default Values: allow|deny

Default: allow

Specifies whether to allow requests from clients not identified through a <host-access> or <ip-access> subelement. Use separate mode attributes for the <host-access> and <ip-access> subelements to specify whether to allow requests from clients that are identified through those subelements.


<classpath>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

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

Table B-2 <classpath> Attributes

Name Description
path Values: String

Default: n/a (required)

You can specify one or more locations, separated by commas or semicolons, where a location can be either of the following:

  • The complete path to a JAR or ZIP file, including the file name

  • A directory path

In either case, you can use an absolute path or a path that is relative to the configuration file location (global-web-application.xml or orion-web.xml, as applicable).

If you specify a directory path, the classloader recognizes only individual class files in the specified directory, not JAR or ZIP files (unless those are specified separately).

For example, assume the following setting in orion-web.xml:

<classpath path=
      /abc/def/lib1.jar,
      /abc/def/zip1.jar,
      /abc/def,mydir
/>

The classloader recognizes the following:

  • The lib1.jar and zip1.jar libraries (but no other libraries in /abc/def)

  • Any class files in /abc/def

  • Any class files in mydir, relative to the location of orion-web.xml


<context-attribute>

Parent element: <lookup-context>

Child elements: None

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

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

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

Table B-3 <context-attribute> Attributes

Name Description
name Values: String

Default: n/a (required)

Specifies the name of the attribute.

value Values: String

Default: n/a (required)

Specifies the desired value of the attribute.


<context-param-mapping>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

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

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

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

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

Name Description
name Values: String

Default: n/a (required)

The name of the parameter for which you are specifying a new value.


<ejb-ref-mapping>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

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

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

Name Description
name Values: String

Default: n/a (required)

Specifies the EJB reference name, from an <ejb-ref-name> element in web.xml.

location Values: String

Default: n/a (required)

Specifies a JNDI location from which to look up the EJB home.


<env-entry-mapping>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

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

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

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

Name Description
name Values: String

Default: n/a (required)

The name of the environment entry for which you are specifying a new value.


<expiration-setting>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

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

Table B-7 <expiration-setting> Attributes

Name Description
expires Values: String (integer, seconds)

Default: 0

Specifies the number of seconds before expiration, or "never" for no expiration. The default setting calls for immediate expiration.

url-pattern Values: String

Default: n/a (required)

Specifies the URL pattern that the expiration applies to. This could be as in the following example:

url-pattern="*.gif"

<group>

Parent element: <security-role-mapping>

Child elements: None

Required? Optional; zero or more

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

Table B-8 <group> Attributes

Name Description
name Values: String

Default: n/a (required)

Specifies the name of the group.


<host-access>

Parent element: <access-mask>

Child elements: None

Required? Optional; zero or more

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

Table B-9 <host-access> Attributes

Name Description
domain Values: String

Default: n/a (required)

Specifies the host or domain.

mode Values: allow|deny

Default: n/a (required)

Specifies whether to allow or deny access from the specified host or domain.


<ip-access>

Parent element: <access-mask>

Child elements: None

Required? Optional; zero or more

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

Table B-10 <ip-access> Attributes

Name Description
ip Values: String

Default: n/a (required)

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

netmask Values: String

Default: No default

Specifies the relevant subnet mask, if any (example: "255.255.255.0").

mode Values: allow|deny

Default: n/a (required)

Specifies whether to allow or deny access from the specified IP address and subnet mask.


<jazn-web-app>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or one

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

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

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

Or you can set the property to "false".

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

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

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

Name Description
auth-method Values: BASIC|SSO|COREIDSSO

Default: BASIC

This is the method of HTTP client authentication. "BASIC" is for basic J2EE authentication; "SSO" is for Oracle Application Server Single Sign-On. "COREIDSSO" is for using Oracle COREid Access and Identity as the security provider, with single sign-on

Another value for auth-method, "DIGEST", is deprecated in the OC4J 10.1.3 implementation, but still supported for backward compatibility. Instead, you can use the standard DIGEST setting for auth-method in the web.xml file.

Note: Use "BASIC" if your application uses a custom LoginModule instance.

runas-mode Values: Boolean

Default: false

This mode is deprecated in the OC4J 10.1.3 implementation, but still supported for backward compatibility. A new, consolidated JAAS mode replaces the runas-mode and doasprivileged-mode for servlets.

Set runas-mode to "true" to invoke the servlet using the privileges of a particular subject. A subject is defined by an instance of the javax.security.auth.Subject class and includes a set of facts regarding a single entity, such as a person. Such facts include identities and security-related attributes, such as passwords and cryptographic keys.

With the default runas-mode="false" setting, doasprivileged-mode is ignored.

doasprivileged-mode Values: Boolean

Default: true

This mode is deprecated in the OC4J 10.1.3 implementation, but still supported for backward compatibility. A new, consolidated JAAS mode replaces the runas-mode and doasprivileged-mode for servlets.

Assuming runas-mode="true", use the default "true" setting of doasprivileged-mode to use privileges of a particular subject without being limited by the access-control restrictions of the server. Values of runas-mode="true" and doasprivileged-mode="true" result in use of the static Subject.doAsPrivileged() method when the servlet is invoked. Values of runas-mode="true" and doasprivileged-mode="false" result in use of the static Subject.doAs() method. In either case, the JAAS Provider passes in the Subject instance in the method call.

When the doAsPrivileged() method is used, the JAAS Provider invokes the method with a null java.security.AccessControlContext instance. This is to start the action freshly and execute the servlet without the restrictions of the current server AccessControlContext instance. When the doAs() method is used, an AccessControlContext instance is retrieved from the current thread (from the server).


<lookup-context>

Parent element: <resource-ref-mapping>

Child elements: <context-attribute>

Required? Optional; zero or one

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

Table B-12 <lookup-context> Attributes

Name Description
location Values: String

Default: n/a (required)

Specifies the name of a nondefault (such as third-party) JNDI context.


<mime-mappings>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

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

Table B-13 <mime-mappings> Attributes

Name Description
path Values: String

Default: n/a (required)

Specifies the path or URL for the file, either absolute or relative to the location of the orion-web.xml file.


<orion-web-app>

Parent element: n/a (root)

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

Required? Required; one only

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


Note:

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

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

Name Description
autojoin-session Values: Boolean

Default: true

Specifies whether users should be assigned a session as soon as they log in to the application.

default-buffer-size Values: Non-negative integer (bytes)

Default: 2048

Specifies the default size of the output buffer for servlet responses, in bytes.

default-charset Values: String

Default: iso-8859-1

For JSP pages only, this attribute specifies the ISO character set to use by default. In general, for JSP 2.0 users, we instead recommend standard <page-encoding> functionality (under the web.xml <jsp-config> element, according to the JSP 2.0 specification), to specify character sets according to URL patterns. However, default-charset may be useful if you have large numbers of JSP pages, particularly across multiple applications, to avoid the necessity of making numerous changes in your EAR files. Also, you can use default-charset to set a base default, then use <page-encoding> functionality to override the default for particular URL patterns. See the JSP and servlet specifications for more information about the <jsp-config> and <page-encoding> elements.

default-mime-type Values: String

Default: No default

This specifies a default content type for servlet responses, for situations where the setContentType() method is not called from the servlet implementation. If default-mime-type is not specified, then there is no default content type.

development Values: Boolean

Default: false

This attribute is a convenience flag to use during development. If development is set to "true", then the OC4J server checks a particular directory for updates to servlet source files. If a source file has changed since the last request, then OC4J will, upon the next request, recompile the servlet, redeploy the Web application, and reload the servlet and any dependency classes.

The directory is determined by the setting of the source-directory attribute.

Note that the OC4J JSP container does not take any special action for the development flag. Any related functionality is handled by the OC4J servlet container.

directory-browsing Values: allow|deny

Default: deny

Specifies whether to allow directory browsing for a URL that ends in "/". Assume the following circumstances:

  • There is no index.html file in the application root directory.

  • There is no welcome file defined in the web.xml file.

If directory-browsing is set to "allow" under these circumstances, then a URL ending in "/" results in the contents of the corresponding directory being displayed in the user's browser. If directory-browsing is set to "deny" under these circumstances, then a URL ending in "/" results in an error indicating that the directory contents cannot be displayed.

If there is a defined welcome file or there is an index.html file in the application root directory, then the contents of that file are displayed, regardless of the directory-browsing setting.

enable-jsp-dispatcher-shortcut Values: Boolean

Default: true

A "true" setting results in significant performance improvements by the OC4J JSP container, especially in conjunction with a "true" setting for the simple-jsp-mapping attribute. This is particularly true for JSP pages with numerous jsp:include statements. Use of the "true" setting assumes, however, that if you define JSP files with <jsp-file> elements in web.xml, then you have corresponding <url-pattern> specifications for those files.

file-modification-check-interval Values: String (integer, milliseconds)

Default: 1000

This attribute determines when to check a static file, such as an HTML file, to see whether its timestamp has changed and it should therefore be reloaded from the file system. When a static file is first accessed, it is loaded from the file system and also cached. For each subsequent access, there is the following logic:

  • If the elapsed time since the last check of the file timestamp is less than the specified file-check interval, then the timestamp is not checked and the file is loaded from cache.

  • If the elapsed time since the last check of the file timestamp is greater than the specified file-check interval, then the timestamp is checked. If the timestamp has changed since the last check, the file is loaded from the file system, otherwise it is loaded from cache.

Specify this value in milliseconds. Zero or a negative number specifies that the file timestamp is always checked. For performance reasons, a very large value ("1000000", for example) is recommended in a production environment.

jsp-cache-directory Values: String

Default: ./persistence (relative to the deployment directory of the application)

This attribute specifies the JSP cache directory, which is used as a base directory for output files from the JSP translator. It is also used as a base directory for application-level TLD caching.

jsp-cache-tlds Values: on|off|standard

Default: standard

This flag indicates whether persistent TLD caching is enabled for JSP pages. The "standard" or "on" setting enables caching, and in either case .tld files are inherited from the global TLD locations according to the jsp-taglib-locations attribute of <orion-web-app>.

The "standard" setting also results in a search for .tld files in the application /WEB-INF directory, and these are added to the files inherited from the global level. Note that the /WEB-INF/lib and /WEB-INF/classes subdirectories are not searched.

The "on" setting also results in a search for .tld files among all files within the application, and these are added to the files inherited from the global level.

The "off" setting disables persistent TLD caching.

jsp-print-null Values: Boolean

Default: true

Set this flag to "false" to print an empty string instead of the default "null" string for null output from a JSP page.

jsp-taglib-locations Values: String

Default: See below

If persistent TLD caching is enabled for JSP pages (through the jsp-cache-tlds attribute), you can use jsp-taglib-locations to specify a semicolon-delimited list of one or more directories to use as "well-known" locations. Tag library JAR files can be placed in these locations for sharing across multiple JSP pages and Web applications, and for TLD caching

You can specify any combination of absolute directory paths or relative directory paths. Relative paths would be under ORACLE_HOME if ORACLE_HOME is defined, or under the current directory (from which the OC4J process was started) if ORACLE_HOME is not defined. The default value is as follows:

  • ORACLE_HOME/j2ee/home/jsp/lib/taglib/ if ORACLE_HOME is defined

  • ./jsp/lib/taglib if ORACLE_HOME is not defined.

Important: Use the jsp-taglib-locations attribute only in global-web-application.xml, not in orion-web.xml.

jsp-timeout Values: Non-negative integer (seconds)

Default: 0 (no timeout)

Specifies a period of time after which any JSP page will be removed from memory if it has not been requested. This frees up resources in situations in which some pages are called infrequently.

persistence-path Values: String

Default: No default (by default, no persistence)

Indicates where to store servlet HttpSession objects for persistence across server restarts or application redeployments. Specify a relative path, which will be relative to an OC4J temporary storage area under the application-deployments directory. If no value is specified, then there is no persistence of session objects across restarts or redeployments.

Session objects must be serializable (directly or indirectly implementing the java.io.Serializable interface) or remoteable (directly or indirectly implementing the java.rmi.Remote interface) for this feature to work.

Note: This attribute is ignored if OC4J clustering is enabled.

schema-major-version Values: String

Default: No default

The major version number of the orion-web.xml XSD. If you create orion-web.xml manually, set this attribute to 10 for use with the OC4J 10.1.3 implementation.

Note: This attribute does not appear directly in the XSD for orion-web.xml. It is according to the attributeGroup specification in the top-level OC4J XSD.

schema-minor-version Values: String

Default: No default

The minor version number of the orion-web.xml XSD. If you create orion-web.xml manually, set this attribute to 0 for use with the OC4J 10.1.3 implementation.

Note: This attribute does not appear directly in the XSD for orion-web.xml. It is according to the attributeGroup specification in the top-level OC4J XSD.

servlet-webdir Values: String

Default: /servlet/ (see note below)

Use this attribute, in conjunction with a true setting for the OC4J system property http.webdir.enable, to enable servlet invocation by class name in standalone OC4J. Once the system property is set, any servlet-webdir setting that starts with a slash ("/") enables this feature and specifies a special URL portion to insert after the context path to instruct OC4J to invoke a servlet by class name. Anything appearing after this path in a URL is assumed to be a class name, including the package. See "Invoking a Servlet by Class Name During OC4J Development" for additional information.

This feature is typically for use in an OC4J standalone environment during development and testing; it presents a significant security risk and should not be used in a production environment. (For production deployment, use the standard web.xml mechanisms to define the context path and servlet path.)

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

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

Invocation by class name is disabled by a setting of servlet-webdir="" (empty quotes) or by the OC4J system property setting http.webdir.enable=false.

Note: Any servlet-webdir setting, including the default, is overridden by the default false setting of http.webdir.enable. See the Oracle Containers for J2EE Configuration and Administration Guide for general information about OC4J system properties.

simple-jsp-mapping Values: Boolean

Default: false

Set this to "true" if "*.jsp" is mapped to only the oracle.jsp.runtimev2.JspServlet front-end JSP servlet. This would be specified in the <servlet> elements of any Web descriptors affecting your application (global-web-application.xml, web.xml, and orion-web.xml). A "true" setting allows performance improvements for JSP pages.

source-directory Values: String

Default: /WEB-INF/src (if it exists), or /WEB-INF/classes

For situations in which the development attribute is set to "true", the source-directory setting specifies where to look for servlet source files to auto-compile. If you use the default location, OC4J keeps track of the location of the /WEB-INF directory of your application after deployment. Note that modified source files will be found anywhere under the source-directory directory, according to package name.

temporary-directory Values: String

Default: ./temp

This is the path to a temporary directory that can be used by servlets and JSP pages for scratch files. The path can be either absolute, or relative to the deployment directory.

A servlet may use a temporary directory, for example, to write information to disk as a user is entering data in a form (perhaps for interim or short-term storage before the information is written to a database).

The specified directory can then be recalled from the servlet context, where it is available through the attribute javax.servlet.context.tempdir, as in the following example.

File file = (File)application.getAttribute
                  ("javax.servlet.context.tempdir");

A java.io.File object is returned, from which you can obtain directory information and contents.



Note:

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

<request-tracker>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

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

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

Table B-15 <request-tracker> Attributes

Name Description
servlet-name Values: String

Default: n/a (required)

Specifies the servlet to invoke. You can specify either the designated servlet name or the class name, according to the corresponding <servlet-name> or <servlet-class> element (both of which are subelements of a <servlet> element) in the web.xml file.


<resource-env-ref-mapping>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

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

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

Name Description
name Values: String

Default: n/a (required)

Specifies the resource name, from web.xml.

location Values: String

Default: n/a (required)

Specifies the JNDI location from which to look up the resource.


<resource-ref-mapping>

Parent element: <orion-web-app>

Child elements: <lookup-context>

Required? Optional; zero or more

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

Following is an example using this element and its subelements:

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

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

Name Description
name Values: String

Default: n/a (required)

Specifies the resource name, from web.xml. For example:

name="jdbc/TheDSVar"
location Values: String

Default: n/a (required)

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

location="jdbc/TheDS"

<security-role-mapping>

Parent element: <orion-web-app>

Child elements: <group>, <user>

Required? Optional; zero or more

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

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


Important:

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

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

Name Description
impliesAll Values: Boolean

Default: false

Specifies whether this mapping applies to all users.

name Values: String

Default: n/a (required)

Specifies the name of the security role, matching a name specified in a <role-name> subelement of a <security-role> element in web.xml.


<service-ref-mapping>

Parent element: <orion-web-app>

Child elements: According to its own schema definition

Required? Optional; zero or more

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

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

<servlet-chaining>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

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


Important:

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

Table B-19 <servlet-chaining> Attributes

Name Description
mime-type Values: String

Default: n/a (required)

Specifies the MIME type to trigger the chaining (for example, "text/html").

servlet-name Values: String

Default: n/a (required)

Specifies the servlet to call when the specified MIME type is encountered. The servlet name is tied to a servlet class through its definition in the <web-app> element of global-web-application.xml, web.xml, or orion-web.xml.


<session-tracker>

Parent element: <session-tracking>

Child elements: None

Required? Optional; zero or more

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

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

Table B-20 <session-tracker> Attributes

Name Description
servlet-name Values: String

Default: n/a (required)

Specifies the servlet to invoke. You can specify either the designated servlet name or the class name, according to the corresponding <servlet-name> or <servlet-class> element under the relevant <servlet> element in the web.xml file.

set-secure Values: Boolean

Default: false

Specifies whether all session cookies generated by OC4J for an application will be returned by the client only when the HTTPS protocol is being used. If set-secure="true", all session cookies will include the secure attribute, which instructs the browser to return the cookies only over the secure HTTPS protocol. If set-secure="false", the browser will return cookies over any protocol.


<session-tracking>

Parent element: <orion-web-app>

Child elements: <session-tracker>

Required? Optional; zero or one

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


Notes:

  • If cookies are disabled, session tracking can be achieved only if your servlet explicitly calls the encodeURL() method of the response object, or the encodeRedirectURL() method for redirects.

  • OC4J does not support auto-encoding, in which session IDs are automatically encoded into the URL by the servlet container. This process is nonstandard and expensive.


Table B-21 <session-tracking> Attributes

Name Description
cookies Values: enabled|disabled

Default: enabled

Specifies whether to send session cookies. The name of a session cookie is JSESSIONID. (See "How OC4J Can Use Cookies for Session Tracking" for information about the JSESSIONID cookie.)

cookie-domain Values: String

Default: No default

Specifies the desired domain for JSESSIONID session cookies. This overrides any domain setting in applicable Set-Cookie HTTP response headers. You can use this attribute to track a single client or user over multiple Web sites. The setting must start with a period ("."). For example:

<session-tracking cookie-domain=".us.oracle.com" />

In this case, the same session cookie is used and reused when the user visits any site that matches the ".us.oracle.com" domain pattern, such as webserv1.us.oracle.com or webserv2.us.oracle.com.

The domain specification must consist of at least two elements, such as ".us.oracle.com" or ".oracle.com". A setting of ".com", for example, is illegal.

Here are two scenarios in which cookie domain functionality is useful:

  • You can use it to share session state between nodes of a Web application running on different hosts.

  • In an OC4J standalone environment, you can use it for a shared application, where shared="true" in a <web-app> element in the Web site XML file. In such an application, some requests go through a secure port and some go through a nonsecure port, with each port denoting a separate Web site. You would want the same cookie used regardless of which port is being used. (In this scenario, using cookie-domain is unnecessary, however, if you use the default ports of 80 for HTTP and 443 for HTTPS. The client would already recognize these as different ports of the same Web site, and only a single cookie would be used.)

cookie-path Values: String

Default: No default

You can use this to optionally specify the URL path value that applies to JSESSIONID session cookies. This specifies the subset of URLs for which session cookies are valid within any applicable domain (which depends on the cookie domain setting). If specified, it overrides any path setting in applicable Set-Cookie HTTP response headers. If not specified, and if there is no path setting in the Set-Cookie headers, the default cookie path is the Web application context path.

cookie-max-age Values: Non-negative integer (seconds)

Default: No default

This number is sent with JSESSIONID session cookies and specifies a maximum interval (in seconds) for the browser to save the cookie. By default, the cookie is kept in memory during the browser session and discarded afterward.


<user>

Parent element: <security-role-mapping>

Child elements: None

Required? Optional; zero or more

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

Table B-22 <user> Attributes

Name Description
name Values: String

Default: n/a (required)

Specifies the name of the user.


<virtual-directory>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or more

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

Table B-23 <virtual-directory> Attributes

Name Description
real-path Values: String

Default: n/a (required)

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

virtual-path Values: String

Default: n/a (required)

This is a virtual path to map to the specified real path.


<web-app>

Parent element: <orion-web-app>

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

Required? Optional; zero or one

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

<web-app-class-loader>

Parent element: <orion-web-app>

Child elements: None

Required? Optional; zero or one

Use this element for class-loading instructions.

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

Name Description
search-local-classes-first Values: Boolean

Default: false

Set this to "true" to search and load WAR file classes before system classes. By default, system classes are searched and loaded first.

include-war-manifest-class-path Values: Boolean

Default: true

Set this to "false" to not include the classpath specified in the WAR file manifest Class-Path attribute when searching and loading classes from the WAR file (regardless of the search-local-classes-first setting). Otherwise, the classplath from the WAR file manifest is included.



Notes:

  • If both attributes are set to "true", the overall classpath is constructed so that classes physically residing in the WAR file are loaded prior to any classes from the WAR file manifest classpath. So you can assume that in the event of any conflict, classes physically residing in the WAR file will take precedence.

  • To comply with the servlet specification, search-local-classes-first functionality cannot be used in loading classes in java.* or javax.* packages.

  • If you want to use an XML parser or JDBC driver packaged with your application in place of the Oracle XML parser or JDBC driver, set the search-local-classes-first attribute to "true". You also need to specify the default inherited Oracle library in the <remove-inherited> tag in orion-application.xml. For complete instructions, see Oracle Containers for J2EE Developer's Guide.