Skip Headers
Oracle® Containers for J2EE Configuration and Administration Guide
10g (10.1.3.1.0)

Part Number B28950-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

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

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 want OC4J to use. The JDK that will be used must be added to the host machine's PATH environment variable.

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

  1. Stop the OC4J instance.

  2. Delete the ORACLE_HOME/j2ee/instance/application-deployments directory.

    Deleting this directory will cause the application files to be recompiled when OC4J is restarted with JDK 1.4.2.

You can specify the JDK to use for each OC4J instance through manual edits to the opmn.xml configuration file. If you want to use the javac compiler installed with the JDK defined in the JAVA_HOME environment variable, also remove the <java-compiler> element from the server.xml file and let OC4J rediscover the default settings.

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="default_group"> element in the XML structure. For example:

<ias-component id="default_group">
  <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

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]

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

java -jar oc4j.jar -userthreads

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 OC4J runtime options 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="default_group"> element in the XML structure. For example:

<ias-component id="default_group">
  <process-type id="home" module-id="OC4J" status="enabled">
    <module-data>
      <category id="start-parameters">
        <data id="oc4j-options" value="-userthreads"/>
        ...
      </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/instance/config directory.

-validateXML

Validates XML configuration files defined by an XSD at the time they are read.

If you add the tx-retry-wait attribute to the <entity-deployment> or <session-deployment> element in your orion-ejb-jar.xml file, do not use the -validateXML option on the OC4J startup command line.

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

In an OPMN-managed configuration, the file will be generated within an instance_default_group_1 directory appended to the path specified.

For example, suppose you specify the following element in opmn.xml:

<data id="oc4j-options" value="...-out /mypath/mylog.log"/>

The mylog.log file will actually be generated in this file:

/mypath/instance_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.

-http.sessionInvalidatingThreads

Specifies the maximum number of threads to invalidate HTTP sessions. The default value is 3.

-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

-sequential

Starts each OC4J instance within an Oracle Application Server cluster sequentially.

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


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]

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

java -Doc4j.formauth.redirect=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="default_group"> element in the XML structure. Preface all system properties with a -D. For example:

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

Overview of General System Properties

Table 4-2 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 temporary 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 temporary 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.

java.awt.headless=<true|false>

If true, specifies checking on whether or not a display, keyboard, and mouse are supported in an environment. If false, this check is not performed. The default is true.

oracle.home

Sets the root directory into which you will install the OC4J distribution.

Instead of using the oracle.home system property, you can set the value of the ORACLE_HOME environment variable to the root directory.

oracle.j2ee.home

Sets the J2EE home directory to the installed directory of the oc4j.jar and admin.jar files, ORACLE_HOME/j2ee/instance. The value of ORACLE_HOME is the root directory into which you will install the OC4J distribution.

Setting this system property or the J2EE_HOME environment variable to the J2EE home directory enables you to invoke oc4j.jar and admin.jar from any 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 replaced the deprecated dedicated.connection property. 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.

You can also set this in the JNDI properties.

The oracle.j2ee.rmi.loadBalance property replaces the dedicated.rmicontext, dedicated.connection, and LoadBalanceOnLookup properties, which are deprecated in OC4J 10g (10.1.3.1.0).

oracle.j2ee.rmi.loadBalance

Configures replication-based load balancing, with one of these settings:

  • client: The client interacts with the OC4J process that was initially chosen at the first lookup for the entire conversation.

  • context: The client goes to a new server when a separate context is used (similar to the deprecated dedicated.rmicontext property).

  • lookup: The client goes to a new server for every lookup.

The default setting is client.

The oracle.j2ee.rmi.loadBalance property replaces the deprecated dedicated.rmicontext, dedicated.connection, and LoadBalanceOnLookup 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 on a Windows system or when the back-end database is running on a Windows system.

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 on a Windows system, 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 shut down OC4J using CTRL-C, then the OC4J process will hang for at least 2.5 hours.

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.

This property has been deprecated and works only with OrionCMP .

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 valid only 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 optionally the 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.

The value set for servlet-webdir in orion-web.xml overrides the default value set for this attribute in ORACLE_HOME/j2ee/instance/config/global-web-application, which is servlet-webdir="/servlet".


Overview of Debug Properties


Note:

The debug properties listed in this section are deprecated in OC4J 10g (10.1.3.1.0).

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


You can use the following properties for debugging 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.


Enabling Remote Debugging from an Integrated Development Environment

You can debug applications on OC4J remotely, from an Integrated Development Environment (IDE), if you start the OC4J instance or instances with JVM debug commands, specified as start parameters, so that a remote debugger can connect. The following topics describe how to specify these parameters:

Enabling Remote Debugging for an OC4J Instance Through Application Server Control Console

To enable remote debugging for a single OC4J instance through the Application Server Control Console:

  1. Navigate to the OC4J Home page.

  2. Click Administration to display the OC4J Administration page.

  3. Under Properties in the table of administration tasks, click the task icon in the Server Properties row.

    Enterprise Manager displays the Server Properties page.

  4. In the Start-parameters: Java Options section under Command Line Options, click Add Another Row to add each of the following debug start parameters:

    • -Xdebug

    • -Xnoagent

    • -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=4000

  5. Click Apply to apply your changes to the OC4J configuration.

When you make changes on to the server properties, you must restart the OC4J instance before the changes take effect.

Specifying Debug Start Parameters in the opmn.xml File

For OPMN-managed OC4J instances, you can put the debug parameters in the opmn.xml file, as the value of a <data> subelement where the id attribute is java-options, within a <category> element where the id attribute is start-parameters, and then restart the instance. The entry in opmn.xml should look like this one:

<module-data> 
  <category id="start-parameters"> 
     <data id="java-options" value="-server -Xdebug -Xnoagent 
      -Djava.compiler=NONE 
      -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=4000 
      -Djava.security.policy=$ORACLE_HOME/j2ee/home/config/java2.policy 
      -Djava.awt.headless=true"/>

Make sure you never use suspend=y, which specifies not to start OC4J until the debugger is attached. If you used this debug parameter, OPMN would attempt to restart the OC4J instance or instances continuously because OPMN would not get a response from its query pings.

Attach to the server the port to which you set address, such as port 4000.


Note:

The port value of 4000 is arbitrary. You should set a value suitable for your connection. The specified port is the port that must be set in the remote debugging client to connect to the server.

Specifying Debug Start Parameters on a Startup Command Line

For a standalone OC4J instance, you can specify the debug start parameters on a startup command line, as follows:

java -Xdebug -Xnoagent -Djava.compiler=NONE 
-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=4000 -jar oc4j.jar

Debugging Web Applications Remotely

For debugging Web applications from an IDE, you need to set up for servlet and JSP debugging, as the following topics describe:

Setting Up for Remote Debugging of Servlets

To set up remote debugging for a servlet:

  1. Mark your project run or debug configuration to do remote debugging.

  2. Set the attach to JPDA in the remote-debug specific runtime configuration node.

  3. Start your OC4J instance with the debug parameters, as the example in "Specifying Debug Start Parameters on a Startup Command Line" shows.

  4. Set a breakpoint in your servlet.

  5. Run a remote debugger.

    After you invoke the servlet from a Web browser, the servlet should reach the breakpoint.

Setting Up for Remote Debugging of JSPs

For JSPs, you can set up as described in the preceding topic,"Setting Up for Remote Debugging of Servlets" , but one more step is needed. You need to edit the global-web-application.xml file, which is installed in ORACLE_HOME/j2ee/instance/config by default, and have at least the following parameters set for the JSP part:

<init-param> 
   <param-name>debug</param-name> 
   <param-value>true</param-value> 
</init-param> 
<init-param> 
   <param-name>developer_mode</param-name> 
   <param-value>true</param-value> 
</init-param> 
<init-param> 
   <param-name>encode_to_java</param-name> 
   <param-value>true</param-value> 
</init-param> 
<init-param> 
   <param-name>reduce_tag_code</param-name> 
   <param-value>false</param-value> 
</init-param> 
<init-param> 
   <param-name>extra_imports</param-name> 
   <param-value></param-value> 
</init-param> 
<init-param> 
   <param-name>main_mode</param-name> 
   <param-value>recompile</param-value> 
</init-param> 
<init-param> 
   <param-name>debug_mode</param-name> 
   <param-value>true</param-value> 
</init-param>