4 OC4J Runtime Configuration

This chapter provides details on runtime options and system properties that can be set at OC4J startup. It includes the following topics:

Specifying the JDK Version
Setting OC4J Runtime Options at Startup
Setting System Properties at Startup

Specifying the JDK Version

OC4J requires the Java 2 Platform, Standard Edition (J2SE) Development Kit (JDK) release 1.4.2 or 5.0. You can specify the JDK version to use for a standalone OC4J configuration, as well as for each OC4J instance in an Oracle Application Server installation.

Specifying the JDK in a Standalone Configuration

In a standalone OC4J configuration, set the JAVA_HOME environment variable to the location of the JDK you wish to be used by OC4J. Note that the JDK that will be used must be added to the host machine's PATH.

Alternatively, you can specify the JDK to use at OC4J startup. For example:

C:\ORACLE_HOME\j2ee\home\C:\jdk\bin\java -jar oc4j.jar

Specifying the JDK in a Managed Configuration

An OPMN-managed OC4J instance installed as a component of Oracle Application Server will use the JDK 5.0 by default. This new version of the JDK is required to utilize EJB 3.0 and offers numerous performance improvements. However, if applications that will be deployed to OC4J require a JDK 1.4.2 release, it may be necessary to "downgrade" to the earlier version.

Before switching from JDK 5.0 to JDK 1.4.2, you must remove all compiled application files from the OC4J instance. To do this:

Stop the OC4J instance.
Delete the ORACLE_HOME/j2ee/instance/application-deployments directory.

Deleting this directory will cause the application files to be re-compiled when OC4J is re-started with the JDK 1.4.2.

You can specify the JDK to use for each OC4J instance through manual edits to the opmn.xml configuration file.

Set Java system properties in the <data> element where the id attribute is "java-bin". This <data> element is enclosed within the <category id="start-parameters"> subelement of the <ias-component id="OC4J"> element in the XML structure. For example:

<ias-component id="OC4J">
  <process-type id="home" module-id="OC4J" status="enabled">
    <module-data>
      <category id="start-parameters">
        <data id="java-bin" value="c:/myhost/jdk/bin/java"/>
      </category>
      ...
    </module-data>
  </process-type>
</ias-component>

Setting OC4J Runtime Options at Startup

A number of OC4J runtime options can be set on OC4J instances at OC4J startup, most providing options for managing standard output messages. How these options are set differs for standalone OC4J and managed Oracle Application Server configurations.

Setting Runtime Options in a Standalone OC4J Configuration
Setting Runtime Options in a Managed OC4J Configuration
Overview of OC4J Runtime Options

Setting Runtime Options in a Standalone OC4J Configuration

OC4J runtime options can be set by passing arguments on the oc4j.jar command line at OC4J startup. The syntax for oc4j.jar is as follows:

java [props] -jar oc4j.jar [args]

Note that runtime options ([args]) are specified after oc4j.jar in the syntax. For example:

java -jar oc4j.jar -validateXML -verbosity 10

Setting Runtime Options in a Managed OC4J Configuration

When OC4J is installed as a component of Oracle Application Server, OC4J runtime options must be manually added to the opmn.xml configuration file. Options will be passed to managed OC4J instances at startup.

Set Java system properties in the <data> element where the id attribute is "oc4j-options". This <data> element is enclosed within the <category id="start-parameters"> subelement of the <ias-component id="OC4J"> element in the XML structure. Preface all system properties with a -D. For example:

<ias-component id="OC4J">
  <process-type id="home" module-id="OC4J" status="enabled">
    <module-data>
      <category id="start-parameters">
        <data id="oc4j-options" value="-validateXML -verbosity 10"/>
        ...
      </category>
      ...
    </module-data>
  </process-type>
</ias-component>

Overview of OC4J Runtime Options

Table 4-1 describes the OC4J runtime options.

Table 4-1 OC4J Startup Options

Command-Line Argument	Description
`-quiet`	Suppresses standard output to the console.
`-config` `path`	Specifies the path to the `server.xml` descriptor file. The default location is the `ORACLE_HOME/j2ee/home/config` directory.
`-validateXML`	Validates XML configuration files defined by an XSD at the time they are read.
`-out [file]`	Specifies a file to route the standard output to. The file contains messages that are printed to `System.out`, as well as the messages sent to output through the servlet logging interface. If not specified, all output is written to standard out. See "Managing stdout/stderr Log Files" for additional system properties that can be set to manage `stdout` files. Note that in an OPMN-managed configuration, the file will be generated within an instance_default_group_1 directory appended to the path specified. For example, if you specify the following in `opmn.xml`: <data id="oc4j-options" value=" ... -out /mypath/mylog.log" /> The `mylog.log` file will actually be generated in: /mypath/instanceName_default_group_1/mylog.log
`-err [file]`	Specifies a file to route standard error output to. The file contains messages that are printed to `System.err`. If not specified, all errors are written to standard error. See "Managing stdout/stderr Log Files" for additional system properties that can be set to manage `stderr` files. Note that in an OPMN-managed configuration, the file will be generated within an instance_default_group_1 directory appended to the path specified. See the `-out` description above for details.
`-verbosity` `int`	Define an integer between `1` and `10` to set the verbosity level of the message output. A value of `10` will produce the most verbose output. For example: java -jar oc4j.jar -verbosity 10
`-monitorResourceThreads`	Enables backup debugging of thread resources. Enable only if you have problems with threads getting stuck in critical sections of code.
`-userThreads`	Enables context lookup support from user-created threads.
`-listProperties`	Outputs a list of all of the OC4J-specific system properties that can be set on the JVM at OC4J startup, then exits. The following example will redirect the output to a text file in the working directory: java -jar oc4j.jar -listProperties > props.txt
`-version`	Returns the installed version of OC4J and exits
`-? \|-help`	Prints the help text for these options to the console.

Setting System Properties at Startup

You can set a number of OC4J-specific system properties on the JVM at OC4J startup.

Setting System Properties in a Standalone OC4J Configuration
Setting System Properties in an OPMN-Managed OC4J Configuration
Overview of General System Properties
Overview of Debug Properties
Managing stdout/stderr Log Files

Note:

You can output a list of all of the OC4J-specific system properties that can be set on the JVM at OC4J startup using the oc4j.jar -listProperties option. The following example will redirect the output to a text file in the working directory:

java -jar oc4j.jar -listProperties > props.txt

Setting System Properties in a Standalone OC4J Configuration

You can set system properties on the JVM through the OC4J command line at startup. If OC4J is running, you must restart the instance for new property settings to take effect.

The syntax is as follows:

java [props] -jar oc4j.jar [args]

Note that all system properties ([props]) are specified before oc4j.jar in the syntax. All system properties must be prefaced on the command line with a -D. For example:

java -DGenerateIIOP=true -Dhttp.session.debug=true -jar oc4j.jar

Setting System Properties in an OPMN-Managed OC4J Configuration

When OC4J is installed as a component of Oracle Application Server, OC4J system properties must be manually added to the opmn.xml configuration file. Options will be passed to managed OC4J instances at startup.

Set Java system properties in the <data> element where the id attribute is "java-options". This <data> element is enclosed within the <category id="start-parameters"> subelement of the <ias-component id="OC4J"> element in the XML structure. Preface all system properties with a -D. For example:

<ias-component id="OC4J">
  <process-type id="home" module-id="OC4J" status="enabled">
    <module-data>
      <category id="start-parameters">
        <data id="java-options" value="-DGenerateIIOP=true
         -Dhttp.session.debug=true"/>
      </category>
      ...
    </module-data>
  </process-type>
</ias-component>

Overview of General System Properties

The following table describes the general system properties that can be set for OC4J.

Table 4-2 -D General System Properties for OC4J

Property	Description
`java.ext.dirs`	Sets the external directories to be searched for classes when compiling.
`java.io.tmpdir=new_tmpdir`	Sets the temporary directory for the deployment wizard. The default is `/tmp/var`. The deployment wizard uses 20 MB in swap space of the temp directory for storing information during the deployment process. At completion, the deployment wizard cleans up the temp directory. However, if the wizard is interrupted, it may not have the time or opportunity to clean up the temp directory. In this case, you must clean up any additional deployment files from this directory yourself. If not, the directory may fill up, which will disable any further deployment. If you receive an `Out` `of` `Memory` error, check for space available in the temp directory.
`GenerateIIOP=<true\|false>`	Enables IIOP stub generation. The default is `false`.
`KeepIIOPCode=<true\|false>`	Set whether the generated IIOP stub/tie code is kept. The default is `false`.
`oracle.arraylist.deepCopy=<true\|false>`	If `true`, then while cloning an array list, a deep copy is performed. If `false`, a shallow copy is performed for the array list. The default is `true`.
`dedicated.rmicontext=<true\|false>`	This property replaces the deprecated `dedicated.connection` setting. The default is `false`. When two or more clients in the same process retrieve an `InitialContext`, OC4J returns a cached context. Thus, each client receives the same `InitialContext`, which is assigned to the process. Server lookup, which results in server load balancing, happens only if the client retrieves its own `InitialContext`. If you set `dedicated.rmicontext=true`, then each client receives its own `InitialContext` instead of a shared context. When each client has its own `InitialContext`, then the clients can be load balanced. Note that you can also set this in the JNDI properties.
`oracle.mdb.fastUndeploy=int`	Sets the interval at which OC4J polls the underlying database to check if an MDB session is shut down, in seconds. This property enables you to shut down OC4J cleanly when you are running MDBs in a Windows environment or when the back-end database is running on a Windows environment. Normally when you use an MDB, it is blocked in a receive state waiting for incoming messages. However, if you shut down OC4J while the MDB is in a wait state in a Windows environment, the OC4J instance cannot be stopped and the applications are not undeployed since the MDB is blocked. Setting this property enables OC4J to poll the database to see if the session is shut down when the MDB is not processing incoming messages and in a wait state. If you do not set this property and you try to shutdown OC4J using CTRL-C, then the OC4J process will hang for at least 2.5 hours. Note that this polling process can be expensive for performance, and should not be set to start too frequently.
`oracle.dms.sensors=<none\|normal\|heavy\|all>`	You can set the value for Oracle built-in performance metrics to the following: `none`: Disables metrics `normal`: Medium number of metrics (default) `heavy`: High number of metrics `all`: Every possible metric This parameter should be set on the OC4J server. The previous method for turning on these performance metrics, `oracle.dms.gate=<true\|false>`, is replaced by the `oracle.dms.sensors` variable. However, if you still use `oracle.dms.gate`, then setting this variable to false is equivalent to setting `oracle.dms.sensors=none`.
`associateUsingThirdTable=<true\|false>`	For container-managed relationships in entity beans, you can designate whether a third database table is used to manage the relationship. Set to `false` if you do not want a third association table. The default is `false`.
`DefineColumnType=<true\|false>`	Set this to `true` if you are using a pre-9.2.0 Oracle JDBC driver. For these drivers, setting this variable to true avoids a round-trip when executing a select over the Oracle JDBC driver. This parameter should be set on the OC4J server. The default is `false`. When you change the value of this option and restart OC4J, it is only valid for applications deployed after the change. Any applications deployed before the change are not affected. When true, the `DefineColumnType` extension saves a round trip to the database that would otherwise be necessary to describe the table. When the Oracle JDBC driver performs a query, it first uses a round trip to a database to determine the types that it should use for the columns of the result set. Then, when JDBC receives data from the query, it converts the data, as necessary, as it populates the result set. When you specify column types for a query with the `DefineColumnType` extension set to true, you avoid the first round trip to the Oracle database. The server, which is optimized to do so, performs any necessary type conversions.
`oc4j.formauth.redirect=<true\|false>`	This property is applicable when form-based authentication is used by a Web application. If set to `true`, OC4J will perform a client side redirect back to the request URL after a user enters valid credentials when accessing a resource. If the user does not have valid credentials, the Web browser will be redirected to the form authentication error page defined for the Web application. If set to `false`, the`/j-security-check` URL will be displayed in the browser after the user enters valid credentials. The default is `false`.
`http.proxyHost=proxy_hosthttp.proxyPort=proxy_port`	If your HTTP traffic goes through a proxy Web server, specify the proxy host and optionallythe proxy port in the command line. If proxy_port is omitted, the default is port 80.
`http.webdir.enable=<true\|false>`	This property enables or disables servlet class name invocation for all servlets within the OC4J instance. If set to `true`, any servlet running in the OC4J instance can be invoked by class name by default. If set to `false`, servlets cannot be invoked by class name. The default is `false`. To disable this functionality on a per-Web-application basis, set this property to `true`, then set `<orion-web-app servlet-webdir="" ... />` in the `orion-web.xml` descriptor for each Web application that should not allow servlet class name invocation. Note that the value set for `servlet-webdir` in `orion-web.xml` overrides the default value set for this attribute in `ORACLE_HOME/j2ee/home/config/global-web-application`, which is `servlet-webdir="/servlet"`.

Overview of Debug Properties

Note:

The debug properties listed in this section are deprecated in Oracle Containers for J2EE 10g Release 3 (10.1.3).

See "Using and Configuring the OC4J Component Loggers" for details on using the component loggers provided with OC4J.

Use the following properties to better debug applications running within OC4J. Debug messages are printed to the console. All properties take a Boolean value.

Preface all properties with a -D.

Table 4-3 OC4J Debug Properties

Debug Property	Description
http.session.debug= <true\|false>	Provides information about HTTP session events to the console.
http.request.debug= <true\|false>	Provides information about each HTTP request to the console.
http.cluster.debug= <true\|false>	Provides information about HTTP clustering events to the console.
http.error.debug= <true\|false>	Prints all HTTP errors to the console.
http.method.trace.allow= <true\|false>	Enables the `trace` HTTP method.
datasource.verbose= <true\|false>	Provides verbose information on creation of data source and connections using data sources and connections released to the pool.
jdbc.debug= <true\|false>	Provides verbose information when JDBC calls are made.
ejb.cluster.debug= <true\|false>	Enables EJB clustering debug messages.
rmi.debug= <true\|false>	Prints RMI debug information to the console.
rmi.verbose= <true\|false>	Provides verbose information on RMI calls.
`jca.connection.debug=<true\|false>`	Provides extra diagnostic information for J2CA connections.
ws.debug= <true\|false>	Enables Web Services debugging.

Managing stdout/stderr Log Files

The following properties are used to manage standard stderr and stdout log files.

The type of log file(s) that the properties pertain to are specified with the -out and/or -err command line options. You can also set a location to output these log files to in these options.

For example, set the following to rotate stdout/stderr files when the file size reaches 2.5 MB. Log files will be output to the D:\logs directory.

java -Dstdstream.filesize=2.5 -jar oc4j.jar -out d:\logs\oc4j.out -err d:\logs\oc4j.err

This example will rotate stdout logs at 2:30 p.m. every day and limit the archive to a maximum of 10 files:

java -Dstdstream.rotatetime=14:30 -Dstdstream.filenumber=10 -jar oc4j.jar -out d:\logs\oc4j.out

Table 4-4 stdout/stderr Archive Management Properties

Debug Property	Description
stdstream.filesize=max_file_size	The maximum size any file in the archive will be allowed to grow to, in megabytes. Files are rotated when this maximum is reached.
`stdstream.filenumber=max_files`	The maximum number of files to keep as archives. The oldest file will be automatically deleted when the limit is exceeded.
stdstream.rotatetime=HH:mm	The time at which the log file will be rotated each day.