B Configuration Files Used in OC4J

This chapter provides detailed documentation on the XML files used to store configuration data for the OC4J server and J2EE applications and modules deployed into it.

Overview of the XML Configuration Files Used by OC4J
Elements of the OC4J Server Configuration File (server.xml)
Overview of the Web Site Configuration File (*-web-site.xml)

Overview of the XML Configuration Files Used by OC4J

The configuration data for an OC4J instance and the applications and modules deployed into it is persisted in a number of XML files. Figure B-1 provides an overview of these XML files and their respective roles.

Schemas defining the Oracle-proprietary XML files used by OC4J can be viewed at the following link:

http://www.oracle.com/technology/oracleas/schema/index.html

Figure B-1 XML Files Used By OC4J

Description of "Figure B-1 XML Files Used By OC4J"

Table B-1 describes the role and function for each OC4J server-level XML file as well as the global configuration files displayed in the preceding figure.

Unless otherwise indicated, all of these files are installed in the ORACLE_HOME/j2ee/instance/config directory by default.

Table B-1 Server-Level and Global Configuration Files

XML Configuration File	Features/Components
`server.xml`	The OC4J server configuration file. Configures the server and points to the XML files that add to this file, such as `jms.xml` for JMS support. The listing of other XML files enables the services to be configured in separate files, but the `server.xml` file denotes that they be used for the OC4J configuration.
`data-sources.xml`	Contains the OC4J data source configuration for all databases used by applications within OC4J.
`rmi.xml`	Contains OC4J RMI port configuration and RMI tunneling over HTTP.
`jms.xml`	Contains the OC4J JMS configuration for `Destination` topics and queues that are used by JMS and MDBs in OC4J.
`system-application.xml`	Contains the configuration for the `system` application, which is the parent of all other applications installed in the OC4J instance. The file provides configuration data used at OC4J startup, such as data needed to load required shared libraries.
`application.xml`	Contains the configuration for the `default` application. All user-deployed applications and standalone modules that do not have a designated parent are deployed to this application by default. This file includes common settings that serve as default configuration values applied to deployed applications. This file is completely unrelated to `application.xml`, the J2EE standard deployment descriptor.
`global-web-application.xml`	An Oracle-specific file for configuring the servlet and JSP containers within OC4J.
`oc4j-connectors.xml`	Contains global OC4J-specific configuration data for all standalone resource adapters installed in the OC4J instance.
`*-web-site.xml`	An OC4J-specific file that contains configuration data for a Web site created within the OC4J instance. It is typically installed in the `ORACLE_HOME/j2ee/instance/config` directory, but can be installed in a different location. The configuration for the `default` Web site created within each OC4J instance is defined in `default-web-site.xml`.

Table B-2 describes the roles and functions of the various application-level XML files displayed in the preceding figure.

Unless otherwise indicated, all of these files are installed in the ORACLE_HOME/j2ee/instance/config directory by default.

Table B-2 Application-Level Configuration Files

XML Configuration File	Features/Components
`application.xml`	The standard J2EE application descriptor file. The local `application.xml` file defines the J2EE EAR file, which contains the J2EE application modules. This file exists within the J2EE application EAR file.
`orion-application.xml`	The OC4J-specific deployment descriptor, which contains configuration data for a specific deployed application. In this file, you can use the `<jazn-web-app>` element to configure the OracleAS JAAS Provider and Oracle Single Sign-On 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 Oracle Single Sign-On for authentication, you can synchronize a servlet session with the Oracle Java Authentication and Authorization Service (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. You can do this 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`. To take effect, changes to orion-application.xml require an application restart (if the changes were made through Application Server Control or the security provider MBean) or an OC4J restart (if the changes were made manually). 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
`web.xml`	The J2EE Web application deployment descriptor, used to define the Web application deployment parameters that are included in the WAR file. In addition, you can specify the URL pattern for servlets and JSPs in this file. For example, a servlet is defined in the `<servlet>` element, and its URL pattern is defined in the `<servlet-mapping>` element.
`orion-web.xml`	Extends the standard J2EE descriptor with application-level, OC4J-specific configuration data, such as whether or not OC4J features like developer mode and auto-reload of JSPs are enabled.
`ejb-jar.xml`	The J2EE EJB module deployment descriptor, included in the Enterprise JavaBeans (EJB) JAR file. Defines the specific structural characteristics and dependencies of the EJB modules within a JAR and provides instructions for the EJB container about how the beans expect to interact with the container.
`orion-ejb-jar.xml`	The OC4J-specific EJB deployment descriptor. Defines OC4J-specific configuration data for all EJB modules within an archive, including EJB pool settings, timeout and retry settings, JNDI mappings, and finder method specifications. Also includes properties for the TopLink persistence manager.
`application-client.xml`	The J2EE application client configuration file. Describes the EJB modules and other resources used by a J2EE application client packaged in an archive.
`orion-application-client.xml`	Contains OC4J deployment data, including JNDI mappings to an EJB module's home interface or to external resources such as a data source, JMS queue, or mail session.
`ra.xml`	The J2EE standard deployment descriptor. Contains information on implementation code, configuration properties, and security settings for a resource adapter packaged within a RAR file.
`oc4j-ra.xml`	Contains OC4J-specific deployment configuration data for a single resource adapter. This data includes EIS connection information, JNDI name to be used, connection pooling parameters, and resource principal mappings.
`webservices.xml`	The J2EE standard Web services deployment descriptor. Describes a Web service, including WSDL information and JAX-RPC mapping data, for a Web service application packaged within a WAR file.
`oracle-webservices.xml`	Defines properties used by the OC4J Web services container, such as whether to expose the WSDL file. It also defines end-point addresses and data specific to EJB modules implemented as Web services. The file can be packaged in either a WAR or an EJB JAR containing a Web service.

Elements of the OC4J Server Configuration File (server.xml)

The OC4J configuration file, server.xml, is located in the ORACLE_HOME/j2ee/instance/config directory. It is the starting point for configuration of the OC4J server and all J2EE applications, Web applications, and Web sites enabled within the server.

Unless specifically instructed to do so in the OC4J documentation, you should not have to edit server.xml manually because notations are added and updated as needed by OC4J.

The server.xml file includes references to the application descriptor of each application within the OC4J instance, either directly or indirectly. In the case of a typical J2EE application, this reference points to the extracted EAR top-level directory and, therefore, to the application.xml file that the EAR file contains. In the case of the OC4J global application, the server.xml file points directly to the OC4J global application descriptor.

The server.xml file also points to other XML configuration files. For each XML file, the location can be the full path or a path relative to the location of where the server.xml file exists. In addition, the name of the XML file can be any name, as long as the contents of the file conform to the appropriate DTD.

The <rmi-config> element denotes the name and location of the rmi.xml file.
The <jms-config> element denotes the name and location of the jms.xml file.
The <global-application> element denotes the name and location of the global application.xml file.
The <global-web-app-config> element denotes the name and location of the global-web-application.xml file.
The <web-site> element denotes the name and location of one *-web-site.xml file. Since you can have multiple Web sites, you can have multiple <web-site> entries.

The server.xml file format is described by application-server-10_1.xsd, which can be viewed at the following link:

http://www.oracle.com/technology/oracleas/schema/index.html

Example of a server.xml File

An example of the server.xml configuration file for OC4J follows, with  to describe the various sections:

<application-server  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/
  application-server-10_1.xsd"  application-directory="../applications"
  deployment-directory="../application-deployments"
  connector-directory="../connectors"
  schema-major-version="10" schema-minor-version="0" >
  <!-- Shared library definitions -->
          <shared-library name="global.libraries" version="1.0" library-compatible="true">
    <code-source path="../applib"/>
                    <code-source path="../../../sqlj/lib"/>
                    <code-source path="../../../lib/dsv2.jar"/>
          </shared-library>
          <shared-library name="global.tag.libraries" version="1.0"
   library-compatible="true">
                    <code-source path="../jsp/lib/taglib/standard.jar"/>
          </shared-library>
          <!-- J2EE services -->
  <rmi-config path="./rmi.xml" />
          <sep-config path="./internal-settings.xml" />
          <jms-config path="./jms.xml" />
          <javacache-config path="../../../javacache/admin/javacache.xml" />
  <!-- Logging -->
        <j2ee-logging-config path="./j2ee-logging.xml" />
          <log>              <file path="../log/server.log" />
          </log>
          <java-compiler name="javac" in-process="false" encoding="ISO8859_1"
   extdirs="c:\sdk\jdk\jre\lib\ext" />
  <!--  Default application configuration -->
        <global-application name="default" path="application.xml" />
  <!-- Deployed application configuration -->
          <application name="petstore" path="../applications\petstore.ear" start="true" />
        <application name="ascontrol" path="../applications\ascontrol.ear" 
   start="true" />
  <!-- Default Web application configuration file -->
        <global-web-app-config path="global-web-application.xml" />
  <!-- Transaction Manager configuration file -->
          <transaction-manager-config path="transaction-manager.xml" />
  <!-- Configuration files for enabled Web sites -->
        <web-site path="./default-web-site.xml" />
</application-server>

<application-server>

Required? Required; one only

Child elements:

This is the root element of the OC4J configuration file.

Table B-3 <application-server> Attributes

Name	Description
`application-directory`	Values: string Default: `../applications` The target directory for deployed archives.
`application-auto- deploy-directory`	Values: string Default: n/a The directory into which EAR files can be copied, triggering automatic deployment/redeployment of the application.
`connector-directory`	Values: string Default: `../connectors` The target directory for standalone resource adapters.
`deployment-directory`	Values: string Default: `../application-deployments` The directory containing the OC4J-specific deployment descriptors and generated files, such as compiled JSP classes and EJB wrapper classes.
`check-for-updates`	Values: `all\|adminClientOnly\|none`Default: `adminClientOnly` Enables OC4J polling, which automatically checks for changes made to currently deployed applications and modules and redeploys any components that have been modified. See the Oracle Containers for J2EE Deployment Guide for an explanation of supported values and the impact of each.
`localhostIsAdmin`	Values: Boolean Default: `true` If `true`, allows easier access if the process initiating the administrative operation is a process local to the OC4J host machine.
taskmanager-granularity	Values: int Default: `1000` The interval at which the task manager performs its duties, specified in milliseconds. The default is every second (1000 milliseconds).

<application>

Parent element: <application-server>

Required? Optional; multiple allowed

Child elements:

Defines a J2EE application deployed to the OC4J instance. The <application> element defining an application is added to server.xml by OC4J at the time the application is deployed. As such, there is generally no need to manually modify this element.

Table B-4 <application> Attributes

Name Description

Name	Description
`name`	Values: string Default: n/a The application name; typically the same as the EAR file name without the `.ear` extension.
path	Values: string Default: n/a The location of the EAR file or the extracted EAR top-level directory. As such, the path indirectly points to the J2EE standard `application.xml` descriptor packaged with the application.
`start`	Values: Boolean Default: `true` If `true`, the application is started with OC4J and is available to serve requests or for configuration through JMX MBeans. If `false`, the application is not started with OC4J, meaning it is not available to serve requests. However, it is available for configuration through JMX.

name

Values: string Default: n/a

The application name; typically the same as the EAR file name without the .ear extension.

path

Values: string Default: n/a

The location of the EAR file or the extracted EAR top-level directory. As such, the path indirectly points to the J2EE standard application.xml descriptor packaged with the application.

start

Values: Boolean Default: true

If true, the application is started with OC4J and is available to serve requests or for configuration through JMX MBeans. If false, the application is not started with OC4J, meaning it is not available to serve requests. However, it is available for configuration through JMX.

<code-source>

Parent element: <shared-library>

Required? Required; multiple allowed

Specifies the path to a JAR or ZIP file included in the shared library definition.

Table B-5 <code-source> Attributes

Name Description

Name	Description
path	Values: string Default: n/a The path to a JAR or ZIP file included in a shared library. Paths may be absolute if outside of the `/shared-lib` directory, or can be relative to the subdirectory containing the JAR files within the `/shared-lib/library_name` directory. If relative, only the archive file name needs to be supplied as the value of the `path` attribute. You can optionally set `path="*"` to force OC4J to consume all of the archives within the shared library subdirectory.

path

Values: string Default: n/a

The path to a JAR or ZIP file included in a shared library.

Paths may be absolute if outside of the /shared-lib directory, or can be relative to the subdirectory containing the JAR files within the /shared-lib/library_name directory. If relative, only the archive file name needs to be supplied as the value of the path attribute.

You can optionally set path="*" to force OC4J to consume all of the archives within the shared library subdirectory.

<custom-thread-pool>

Parent element: <application-server>

Required? Optional; multiple allowed

Child elements:

Contains the configuration for a single thread pool with the specified name within an OC4J process. One or more applications can be configured to use the thread pool. See "Configuring OC4J Thread Pools" for details.

Table B-6 <custom-thread-pool> Attributes

Name	Description
`name`	Values: string Default: required The thread pool name.
`min`	Values: string Default: `0` The minimum number of threads that OC4J can simultaneously execute.
`max`	Values: string Default: `1024` The maximum number of threads that OC4J can simultaneously execute.
queue	Values: string Default: `0` The maximum number of requests that can be kept in the queue.
`keepAlive`	Values: string Default: `600000` The length of time, in milliseconds, to keep a thread alive (idle) while waiting for a new request. This timeout designates how long an idle thread remains alive. If the timeout is reached, the thread is destroyed. To never destroy threads, set to `-1`. The default value, `600000` milliseconds (10 minutes), is also the minimum value allowed if not `-1`.
`stackSize`	Values: string Default: `0` The size of the thread pool stack.
debug	Values: Boolean Default: `false` If `true`, prints thread pool information to the console at startup. If `false`, the thread pool information is not printed.

<execution-order>

Parent element: <startup-class>, <shutdown-class>

Required? Optional; one only

Child elements:

Specifies the order of execution for each startup class. Specify an integer that designates the order in which the classes are executed.

<global-application>

Parent element: <application-server>

Required? Required; one only

Child elements:

Specifies the OC4J global application, known as the default application. The name attribute defines its name; the path attribute specifies what to use as the OC4J global application descriptor.

Table B-7 <global-application> Attributes

Name Description

Name	Description
`name`	Values: string Default: `default` The global application name.
`path`	Values: string Default: `application.xml` The file name and path for the global application descriptor file. The default descriptor is `ORACLE_HOME/j2ee/instance/config/application.xml`.

name

Values: string Default: default

The global application name.

path

Values: string Default: application.xml

The file name and path for the global application descriptor file. The default descriptor is ORACLE_HOME/j2ee/instance/config/application.xml.

<global-thread-pool>

Parent element: <application-server>

Required? Optional; one only

Child elements:

Contains the old configuration format for thread pools within an OC4J process. If the server.xml file contains the <global-thread-pool> element, the min, max, keep-alive, and queue attribute values apply to the http thread pool, which is created at OC4J startup. The cx-* attributes apply to the rmi connection thread pool, and the rmiRequest-* attributes apply to the rmi request thread pool. See "Configuring OC4J Thread Pools" for details.

The <global-thread-pool> element is deprecated in OC4J 10g (10.1.3.4.0). If the server.xml file contains this element, OC4J changes it to equivalent <thread-pool> elements that define thread pools in the new configuration format.

Table B-8 <global-thread-pool> Attributes

Name	Description
`min`	Values: string Default: n/a The minimum number of threads that OC4J can simultaneously execute.
`max`	Values: string Default: n/a The maximum number of threads that OC4J can simultaneously execute.
`queue`	Values: string Default: n/a The maximum number of requests that can be kept in the queue.
`debug`	Values: Boolean Default: false If `true`, prints thread pool information to the console at startup. If `debug` is `false`, the thread pool information is not printed.
`keep-alive`	Values: string Default: `600000` The length of time, in milliseconds, to keep a thread alive (idle) while waiting for a new request. This timeout designates how long an idle thread remains alive. If the timeout is reached, the thread is destroyed. A value of `-1` specifies never to destroy the thread. The default value, `600000` milliseconds (10 minutes), is also the minimum value allowed if not `-1`.
`cx-max`	Values: string Default: n/a The minimum number of connection threads that OC4J can simultaneously execute.
cx-min	Values: string Default: n/a The maximum number of connection threads that OC4J can simultaneously execute.
cx-queue	Values: string Default: n/a The maximum number of requests that can be kept in the queue.
`cx-debug`	Values: Boolean Default: false If `true`, prints thread pool information to the console at startup. If `cx-debug` is `false`, the thread pool information is not printed.
`cx-keep-alive`	Values: string Default: `600000` The length of time, in milliseconds, to keep a thread alive (idle) while waiting for a new request. This timeout designates how long an idle thread remains alive. If the timeout is reached, the thread is destroyed. A value of `-1` specifies never to destroy the thread. The default value, `600000` milliseconds (10 minutes), is also the minimum value allowed if not `-1`.
`rmiRequest-max`	Values: string Default: n/a The minimum number of connection threads that OC4J can simultaneously execute.
rmiRequest-min	Values: string Default: n/a The maximum number of connection threads that OC4J can simultaneously execute.
rmiRequest-queue	Values: string Default: n/a The maximum number of requests that can be kept in the queue.
`rmiRequest-debug`	Values: Boolean Default: false If `true`, prints thread pool information to the console at startup. If `rmiRequest-debug` is `false`, the thread pool information is not printed.
`rmiRequest-keep-alive`	Values: string Default: `600000` The length of time, in milliseconds, to keep a thread alive (idle) while waiting for a new request. This timeout designates how long an idle thread remains alive. If the timeout is reached, the thread is destroyed. A value of `-1` specifies never to destroy the thread. The default value, `600000` milliseconds (10 minutes), is also the minimum value allowed if not `-1`.

<global-web-app-config>

Parent element: <application-server>

Required? Required; one only

Child elements:

Identifies the configuration file for the OC4J global web application, which by default is the parent of all other Web applications.

The name and root directory path, or context root, of the default Web application are specified in the global application descriptor, and the default Web application is bound to a Web site through the default-web-site.xml file. In standalone OC4J, the default context root for the default Web application is "/".

Table B-9 <global-web-app-config> Attributes

Name	Description
path	Values: string Default: `global-web-application.xml` The file name and path of the global Web application descriptor file. The default descriptor is `ORACLE_HOME/j2ee/instance/config/global-web-application.xml`.

<import-shared-library>

Parent element: <shared-library>

Required? Optional; multiple allowed

Identifies a shared library to be imported by a shared library defined in the enclosing <shared-library> element. For additional information on configuring and using shared libraries, see the Oracle Containers for J2EE Developer's Guide.

Table B-10 <import-shared-library> Attributes

Name Description

Name	Description
`name`	Values: string Default: required The name of the shared library to import.
version	Values: string Default: required The version number to import.

name

Values: string Default: required

The name of the shared library to import.

version

Values: string Default: required

The version number to import.

<init-param>

Parent element: <startup-class>, <shutdown-class>

Required? Optional; multiple allowed

Child elements: <param-name>, <param-value>

Specifies initialization parameters within a <startup-class> or <shutdown-class> element. Contains key and value pairs, of type String, which OC4J takes, which are provided within the input Hashtable argument. The names for the key-value pairs must be unique, as JNDI is used to bind each value to its name.

Table B-11 <init-param> Attributes

Name	Description
path	Values: string Default: `global-web-application.xml` The file name and path of the global Web application descriptor file. The default descriptor is `ORACLE_HOME/j2ee/instance/config/global-web-application.xml`.

<j2ee-logging-config>

Parent element: <application-server>

Required? Optional; only one allowed

Child elements:

Defines the file to use as the J2EE logging configuration file.

Table B-12 <j2ee-logging-config> Attributes

Name	Description
path	Values: string Default: `../j2ee-logging.xml` The file name and path of the logger configuration file.

<java-compiler>

Parent element: <application-server>

Required? Optional; one only

Child elements:

Specifies configuration parameters for the Java compiler to use to compile EJB modules. By default, the javac compiler installed with the JDK defined in the JAVA_HOME environment variable will be used.

Table B-13 <java-compiler> Attributes

Name	Description
name	Values: string Default: `javac` `modern\|classic\|javac\|ojc\|jikes` The name of the Java compiler to use.
in-process	Values: Boolean Default: `false` Specifies whether to run the compiler in-process or out-of-process. If set to `false`, a separate JVM process is spawned for the compiler to execute within. This is the default compiler execution mode used by OC4J, as it offers better management of memory resources. If set to `true`, the compiler executes within the same JVM process as OC4J.
`encoding`	Values: string Default: `ISO-8859-1` The source file encoding to use.
bindir	Values: string Default: n/a The absolute path to the directory containing the compiler executable. This attribute does not need to be specified to use the default `javac` compiler.
`extdir`	Values: string Default: n/a The compiler extension library location, if applicable.
`debug`	Values: Boolean Default: `false` Set to `true` to generate compilation-time debugging output.

<javacache-config>

Parent element: <application-server>

Required? Optional; only one allowed

Child elements: None

Specifies the path to javacache.xml, the Java Object Cache configuration file.

Table B-14 <javacache-config> Attributes

Name	Description
path	Values: string Default: `../../../javacache/admin/javacache.xml` The path to the `javacache.xml` file.

<jms-config>

Parent element: <application-server>

Required? Optional; only one allowed

Child elements:

Specifies the file to use as the OC4J JMS configuration file.

Table B-15 <jms-config> Attributes

Name	Description
path	Values: string Default: `jms.xml` The file name and path of the OC4J JMS configuration file.

<log>

Parent element: <application-server>

Required? Optional; only one allowed

Child elements: <file>

The enclosed <file> element points to the location of the OC4J server log file.

<rmi-config>

Parent element: <application-server>

Required? Optional; only one allowed

Child elements:

Defines the file to use as the OC4J RMI configuration file.

Table B-16 <rmi-config> Attributes

Name	Description
path	Values: string Default: `rmi.xml` The file name and path of the OC4J RMI configuration file.

<shared-library>

Parent element: <application-server>

Required? Optional; multiple allowed

Child elements: <code-source>, <import-shared-library>

Declares a shared library installed within the OC4J instance. For additional information on configuring and using shared libraries, see the Oracle Containers for J2EE Developer's Guide.

Table B-17 <shared-library> Attributes

Name Description

Name	Description
`name`	Values: string Default: required The name of the shared library directory created within the `/shared-lib` directory.
version	Values: string Default: required The version number that serves as the name of the subdirectory containing the shared library's archive files in the `/shared-lib/library_name` directory.
`library-compatible`	Values: Boolean Default: `false` This attribute is intended for internal use only.

name

Values: string Default: required

The name of the shared library directory created within the /shared-lib directory.

version

Values: string Default: required

The version number that serves as the name of the subdirectory containing the shared library's archive files in the /shared-lib/library_name directory.

library-compatible

Values: Boolean Default: false

This attribute is intended for internal use only.

<shutdown-class>

Parent element: <shutdown-classes>

Required? Optional; multiple allowed

Child elements: <execution-order>, <init-param>

Defines a shutdown class to execute before OC4J terminates, within the <shutdown-classes> element.

Table B-18 <shutdown-class> Attributes

Name Description

Name	Description
`classname`	Values: string Default: required The name of the class that implements the `oracle.j2ee.server.OC4JShutdown` interface.

classname

Values: string Default: required

The name of the class that implements the oracle.j2ee.server.OC4JShutdown interface.

<startup-class>

Parent element: <startup-classes>

Required? Optional; multiple allowed

Child elements: <execution-order>, <init-param>

Defines a startup class to execute on OC4J initialization, within the <startup-classes> element.

Table B-19 <startup-class> Attributes

Name Description

Name	Description
`classname`	Values: string Default: required The name of the class that implements the `oracle.j2ee.server.OC4JStartup` interface.
failure-is-fatal	Values: Boolean Default: `false` If `true`, OC4J logs an exception and exits when an exception is thrown. If `false`, OC4J logs the exception and continues.

classname

Values: string Default: required

The name of the class that implements the oracle.j2ee.server.OC4JStartup interface.

failure-is-fatal

Values: Boolean Default: false

If true, OC4J logs an exception and exits when an exception is thrown. If false, OC4J logs the exception and continues.

<thread-pool>

Parent element: <application-server>

Required? Optional; multiple allowed

Child elements:

Contains the configuration for a single system, http, jca, rmi request, or rmi connection thread pool within an OC4J process. See "Configuring OC4J Thread Pools" for details.

Table B-20 <thread-pool> Attributes

Name	Description
`name`	Values: string Default: required `system\|rmi request\|rmi connection\|http\|jca` The thread pool name, which must be one of these values: `system` A hidden thread pool that was not exposed in the older format. `rmi request` A thread pool that serves RMI requests. `rmi connection` A thread pool whose threads block-read on the RMI connection. `http` A thread pool serving HTTP and AJP requests and possibly RMI requests (if an `rmi request` thread pool is not configured) and RMI connections (if an `rmi connection` thread pool is not configured). `jca` The work management thread pool, for the J2CA work manager. The names of the threads in these pools are prefixed with `SystemThreadGroup_`, `RMIRequestThreadGroup_`, `RMIConnectionThreadGroup_`, `HTTPThreadGroup_`, and `WorkManager_`, respectively, and suffixed with an incrementing counter.
`min`	Values: string Default: `0` The minimum number of threads that OC4J can simultaneously execute.
`max`	Values: string Default: `1024` The maximum number of threads that OC4J can simultaneously execute.
queue	Values: string Default: `0` The maximum number of requests that can be kept in the queue.
`keepAlive`	Values: string Default: `600000` The length of time, in milliseconds, to keep a thread alive (idle) while waiting for a new request. This timeout designates how long an idle thread remains alive. If the timeout is reached, the thread is destroyed. To never destroy threads, set to `-1`. The default value, `600000` milliseconds (10 minutes), is also the minimum value allowed if not `-1`.
`stackSize`	Values: string Default: `0` The size of the thread pool stack.
debug	Values: Boolean Default: `false` If `true`, prints the application server thread pool information to the console at startup. If `false`, the thread pool information is not printed.

<transaction-manager-config>

Parent element: <application-server>

Required? Optional; only one allowed

Child elements:

Specifies the transaction manager configuration file.

Table B-21 <transaction-manager-config> Attributes

Name	Description
path	Values: string Default: `transaction-manager.xml` The file name and path of the transaction manager configuration file. The default file is `ORACLE_HOME/j2ee/instance/config/transaction-manager.xml`.

<web-site>

Parent element: <application-server>

Required? Optional; multiple allowed

Child elements:

References the configuration file for a single Web site defined within OC4J. A <web-site> element must be created for each Web site; otherwise, the site will not be enabled within OC4J. See Chapter 13, "Managing Web Sites in OC4J," for details.

Table B-22 <web-site> Attributes

Name	Description
path	Values: string Default: n/a The file name and path of the `*-web-site.xml` configuration file defining the Web site.

<work-manager-thread-pool>

Parent element: <application-server>

Required? Optional; one only

Child elements:

Contains the configuration for a work management thread pool for resource adapters within an OC4J process. See "Configuring OC4J Thread Pools" for details.

This element is deprecated in OC4J 10g (10.1.3.4.0). If the server.xml file contains this element, OC4J changes it to an equivalent <thread-pool> element that defines a jca thread pool.

Table B-23 <work-manager-thread-pool> Attributes

Attribute	Description
`min`	Values: string Default: n/a The minimum number of threads to create in the work management thread pool. To disable the thread pool, set this value to `0`.
`max`	Values: string Default: `40` The maximum number of threads that can be created in the work management thread pool. The work management thread pool uses three worker threads for internal use. For example, if you specify `max="16"`, then only 13 worker threads are available to service requests. Similarly, if the `max` value is `20`, then only 17 threads are available. So you need to set this value to your required maximum number of threads plus 3.
`queue`	Values: string Default: `0` The maximum number of threads that can be kept in the queue in the work management thread pool. If you use the default, `0`, no queue is maintained to handle a sudden burst of work requests.
`keepAlive`	Values: string Default: `600000` The length of time, in milliseconds, to keep a thread alive (idle) while waiting for a new request. After the timeout is reached, the thread is destroyed. To never destroy threads, set to `-1`. The default value, `600000` milliseconds (10 minutes), is also the minimum value allowed if not `-1`.
`debug`	Values: Boolean Default: `false` If `true`, prints the application server work management thread pool information to the console at startup. If `false`, the thread pool information is not printed.

Overview of the Web Site Configuration File (*-web-site.xml)

The element descriptions in this section apply to any OC4J Web site configuration file, including default-web-site.xml.

<web-site>

Required? Required; one only

Child elements:

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

This is the root element for a Web site configuration file.

Table B-24 Web Site Configuration File Attributes

Name	Description
`custom-thread-pool`	Values: string Default: n/a Optionally specifies a custom thread pool to be used by each application bound to this Web site by a <web-app> element in this configuration file.
`display-name`	Values: string Default: n/a Optionally defines a user-friendly or informal Web site name.
`host`	Values: string Default: n/a Specifies the host for this Web site, as either a DNS host name or an IP address. If a server is a multihome machine (having multiple IP addresses), you can use the `ALL` setting to listen to all IP addresses.
`log-request-info`	Values: Boolean Default: `false` Specifies whether to write information about the incoming request into the Web site log if an error occurs. The Web site log is enabled through either the `<access-log>` or `<odl-access-log>` element, described later in this section. ("Enabling or Disabling Access Logging for a Web Module or Application" provides additional information about enabling the Web site log.)
`max-request-size`	Values: string Default: `15000` Sets a maximum size, in bytes, for incoming HTTP 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`	Values: Boolean Default: `false` Specifies whether to support Secure Socket Layer (SSL) functionality. 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 standalone OC4J), a `true` setting results in HTTPS protocol between the client and OC4J. Also, 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. 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`	Values: string Default: n/a 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`. Each protocol must have a corresponding port, and each port must have a corresponding protocol. 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. Changing the value of the `protocol` attribute does not reset the port range to the default range for the protocol you specify. To change the port range, you can use the `range` attribute.
`port`	Values: string Default: n/a Specifies the port number for this Web site. Each port must have a corresponding protocol, and each protocol must have a corresponding port. In standalone OC4J, 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 Web Cache enabled. In a UNIX environment, port numbers less than `1024` require root privileges for access. Also, if there is no port specification from the client browser, port `80` is assumed for HTTP protocol and port `443` for HTTPS. Changing the value of the `protocol` attribute does not reset the port range to the default range for the protocol you specify. To change the port range, you can use the `range` attribute.
`use-keep-alive`	Values: Boolean Default: `true` Typical behavior for a servlet container is to close a connection once a request has been completed. With a `use-keep-alive` 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`	Values: string Default: n/a This optional attribute 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>

Contains an optional, brief description of the Web site.

<frontend>

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, a technique for encoding a session ID into the URL.

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.

Table B-25 describes the attributes of <frontend>.

Table B-25 <frontend> Attributes

Name Description

Name	Description
`host`	Values: string Default: n/a 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`.

host

Values: string Default: n/a

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's root attribute.

Note:

It is possible to deploy a WAR file by itself, instead of within an EAR file. In standalone OC4J, such Web applications are added to the OC4J default application. (In OC4J, there must always be a parent application of some sort.) See "Overview of the Application Hierarchy in OC4J" for more information.

In this scenario, the Web site XML file <web-app> element specifies the name of the default application rather than the name of a J2EE application archive. More details are provided in the attribute descriptions and examples that follow.

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

Table B-26 describes the attributes of <web-app>.

Table B-26 <web-app> Attributes

Name	Description
access-log	Values: string Default: false Specifies whether OC4J access logging, which logs requests to the Web site, is enabled for the Web module. If you want to enable access logging, set to `true`. If log file management becomes an issue, set to `false` to disable access logging for the module. For more on access log configuration, see the descriptions of the `<access-log>` and `<odl-access-log>` elements within this section.
application	Values: string Default: n/a 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. If you deploy a WAR file by itself in standalone OC4J, 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	Values: Boolean Default: `false` Optional. Specifies whether the Web module should be preloaded on application startup. Otherwise, it is loaded upon the first request for it. Supported values are `true` and `false`. The default is `false`; however, this value is explicitly set to `true` when the module or application is deployed with Oracle Enterprise Manager 10g Application Server Control.
max-inactivity-time	Values: string Default: `0` Optional. Specifies 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	Values: Boolean Default: n/a 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.
`root`	Values: string Default: n/a Specifies the path to which the Web module is to be bound. This attribute defines the context root 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 context root, `/catalog`, then the module can be invoked as follows: http://www.example.com/catalog The `root` attribute overrides the `<context-root>` value of the corresponding `<web>` element in the J2EE `application.xml` file. Specifying a slash (`/`) as the context root will override the OC4J default Web application. You can use `/` as the context root when you deploy an application. The following example uses `admin_client.jar` to deploy a WAR file and bind it to `/`: % java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 \ -deploy -file d:my-web-store.war -deploymentName mws_2 \ -bindAllWebApps -contextRoot "/" If an EAR file includes an `application.xml` file that has the context root set to `/`, such as in the following example, then `/` will be the default context root when the application is deployed. <application> <display-name>Web-Store</display-name> <module> <web> <web-uri>my-web-store.war</web-uri> <context-root>/</context-root> </web> </module> </application> Because the default ping URL for Oracle HTTP Server is also a slash (`/)`, using `/` as the context root when you deploy an application might result in either or both of the following problems: Pings intended for Oracle HTTP Server go directly to OC4J instead. Extraneous `HEAD` requests appear in the `*-web-access.log` file. You can avoid these problems by placing an `Oc4jMountCopy off` directive in the ORACLE_HOME`/Apache/Apache/conf/dms.conf` file.
shared	Values: string Default: `false` 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). Use `shared="true"` only in standalone OC4J. 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 make the Web application less secure but might be necessary to work around issues such as SSL session timeouts not being properly supported in some browsers.

<default-web-app>

This element creates a reference to the default Web application bound to this Web site. When a single application is bound to the Web site, such as Application Server Control, specify the application within this element.

For users, this element is relevant only in a standalone OC4J environment. In an Oracle Application Server environment, the OC4J default Web application has system-level functionality but is not otherwise meaningful.

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

<user-web-apps>

Use this element to support user directories and applications. Each user can have a Web module and associated web-application.xml file. User applications are reached at /username/ from the server root.

Table B-27 describes the attributes of <user-web-apps>.

Table B-27 <user-web-apps> Attributes

Name Description

Name	Description
max-inactivity-time	Values: int Default: n/a 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 a UNIX environment, for example, is `/home/username`, in which `username` is replaced by the particular user name.

max-inactivity-time

Values: int Default: n/a

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 a UNIX environment, for example, is /home/username, in which 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.

See "Configuring Text-Based Access Logging" for configuration details.

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

See "Configuring ODL Access Logging" for configuration details.

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

Subelement of <ssl-config>:

<property>

Table B-28 describes the attributes of <ssl-config>.

Table B-28 <ssl-config> Attributes

Name	Description
keystore	Values: string Default: n/a 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`	Values: string Default: n/a The password required to open the keystore.
`needs-client-auth`	Values: string Default: `false` 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`, the default (no certificate required).
`provider`	Values: string Default: `com.sun.net.ssl.internal.ssl.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. However, OC4J employs the Oracle SSL implementation in some cases, such as for SOAP and `http_client`.
`factory`	Values: string If you are not using JSSE, use the `factory` attribute to specify an implementation of `SSLServerSocketFactory`. If you use a third-party `SSLServerSocketFactory` implementation, you can use `<property>` subelements of the `<ssl-config>` element to send parameters to the factory. The factory attribute and its parameters are deprecated in OC4J 10g (10.1.3.4.0).