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 Files (*-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 role and function for 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 J2EE application 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 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. 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 EJB JAR file. Defines the specific structural characteristics and dependencies of the Enterprise JavaBeans 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 deployment descriptor. Defines OC4J-specific configuration data for all EJBs 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'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 endpoint addresses and data specific to EJBs 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, as 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

Below is an example server.xml, with <!-- comments --> 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|noneDefault: 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 into 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	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

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	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.1.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 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 OC4J standalone, the default context path 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 filename 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	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 filename 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 filename 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 EJBs. 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 filename 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 filename 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	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
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
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.1.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 Files (*-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 OC4J standalone), 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. The http setting is for OC4J standalone. To use either an ajp13 or http setting in secure mode (SSL), you must set the secure flag to true and use the <ssl-config> subelement to specify the keystore path and password. This element is documented later in this section.
port	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 OC4J standalone, a port setting of 8888 is used by default for direct access to the OC4J listener, but you can change this as desired. In an Oracle Application Server environment, this port setting is overridden by OPMN, the Oracle Process Management and Notification system. Oracle Application Server uses port 7777 by default for access through Oracle HTTP Server with Oracle Web Cache enabled. On a UNIX system, 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.
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.

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

Note: It is possible to deploy a WAR file by itself, instead of within an EAR file. In OC4J standalone, such Web applications are added to the OC4J default application. (In OC4J, there must always be a parent application of some sort.) See "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 OC4J standalone, using the OC4J default application as the parent, then the application attribute instead reflects the name of the default application, according to the <global-application> element in the server.xml file.
load-on-startup	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/application is deployed through Oracle Enterprise Manager 10g Application Server Control Console.
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, which defines the context path portion of the URL used to invoke the module. For example, if the Web module CatalogApp at Web site www.example.com is bound to the root setting /catalog, then 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. Even though the <context-root> element is mandatory in an application.xml file, its value is not used by OC4J. Specifying a root setting of "/" will override the OC4J default Web application. This setting or a null setting is not allowed by the admin.jar utility when binding a Web application to the Web site.
shared	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 OC4J standalone. If an HTTPS Web application is marked as shared, its session tracking strategy reverts from SSL session tracking to session tracking through cookies or URL rewriting. This could possibly make the Web application less secure but may be necessary to work around issues such as SSL session timeouts not being properly supported in some browsers.

<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 Console, specify the application within this element.

For users, this element is relevant only in an OC4J standalone 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 has his or her own 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
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 on a UNIX system, 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.1.0).