| Oracle® Containers for J2EE Configuration and Administration Guide 10g (10.1.3.4.0) Part Number E12288-01 |
|
|
View PDF |
This chapter provides details on runtime options and system properties that can be set at OC4J startup. It includes the following topics:
OC4J requires one of the following JDK releases:
Java Platform, Standard Edition (Java SE) Development Kit (JDK) 6
Java Platform 2, Standard Edition (J2SE) Development Kit (JDK) 5.0 (also known as JDK 1.5)
Java Platform 2, Standard Edition (J2SE) Development Kit (JDK) 1.4
You must specify the JDK version to use for a standalone OC4J configuration. You can specify the JDK version for each OC4J instance, which uses JDK 5.0 by default in an Oracle Application Server installation.
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
An OPMN-managed OC4J instance installed as a component of Oracle Application Server will use JDK 5.0 by default. JDK 5.0 or JDK 6 is required to utilize EJB 3.0. If applications that will be deployed to OC4J require a JDK 6 or JDK 1.4.2 release, you need to switch to the other version.
Before switching from JDK 5.0 to JDK 6 or JDK 1.4.2, you must remove all compiled application files from the OC4J instance:
Stop the OC4J instance.
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 6 or 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>
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.
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
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>
Table 4-1 describes the OC4J runtime options.
Table 4-1 OC4J Startup Options
| Command-Line Argument | Description |
|---|---|
|
|
Suppresses standard output to the console. |
|
|
Specifies the path to the |
|
|
Validates XML configuration files defined by an XSD at the time they are read. If you add the |
|
|
Specifies a file to route the standard output to. The file contains messages that are printed to See "Managing the stdout and stderr Log Files" for additional system properties that can be set to manage 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 <data id="oc4j-options" value="...-out /mypath/mylog.log"/> The /mypath/instance_default_group_1/mylog.log
|
|
|
Specifies a file to route standard error output to. The file contains messages that are printed to See "Managing the stdout and stderr Log Files" for additional system properties that can be set to manage 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 |
|
|
Define an integer between java -jar oc4j.jar -verbosity 10 |
|
|
Enables backup debugging of thread resources. Enable only if you have problems with threads getting stuck in critical sections of code. |
|
|
Enables context lookup support from user-created threads. |
|
|
Specifies the maximum number of threads to invalidate HTTP sessions. The default value is |
|
|
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 |
|
|
Starts each OC4J instance within an Oracle Application Server cluster sequentially. |
|
|
Returns the installed version of OC4J and exits. |
|
|
Prints the help text for these options to the console. |
You can set a number of OC4J-specific system properties on the JVM at OC4J startup, as the following topics describe:
Setting System Properties in a Standalone OC4J Configuration
Setting System Properties in an OPMN-Managed OC4J Configuration
Allowing Different Dependencies on a Shared Library with manifest.dependencies.warn.only
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 theoc4j.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
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 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
When OC4J is installed as a component of Oracle Application Server, you can add OC4J system properties manually to the opmn.xml configuration file. Options will be passed to a managed OC4J instance 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>
When OC4J initializes, it validates the dependencies of the shared libraries defined in the container-level configurations by verifying the versions specified in the MANIFEST.MF file. The default behavior for a dependency check failure is to issue an error and stop the initialization process. If you want to use different versions of the same shared library, you can set the mainifest.dependencies.warn.only property to true at startup to have OC4J issue a warning and continue initializing when a dependency check fails.
This property is useful if you have a methodology of performing simultaneous project releases and builds that have different dependencies on the same application library.
When mainifest.dependencies.warn.only is set to true, OC4J issues a warning message by default. The logged message goes to the locations specified in ORACLE_HOMEj2ee/instance/config/j2ee-logging.xml configuration file for the oracle logger. This logger has two output locations, the console and an ODL-formatted XML file in j2ee/instance/log/oc4j/log.xml. In standalone OC4J, the instance name is home. In an OPMN-managed, Oracle Application Server environment, all console output gets redirected to the ORACLE_HOME/opmn/logs/instance_default_group_1 file (or some variant of this name).
By default, OC4J10g (10.1.3.4.0) ships with the http.file.allowAlias property set to false. This setting prevents the use of symbolic links. Oracle strongly recommends that this setting not be changed to true, which might allow JSP source code to be visible to end users in some circumstances.
Instead of changing the property setting, you can use one of the following work-arounds:
Temporarily switch from using the OC4J lightweight HTTP listener to front ending the OC4J application through Oracle HTTP Server, so that browsers access the pages indirectly through mod_oc4j and Apache JServ Protocol (AJP), rather than directly through HTTP.
Replace all symbolic links in an application with the names of the real files they represent.
You can use a shell script to automate the replacement of symbolic links. For example:
#!/bin/ksh
PROGNAME="${0##*/}"
LN_EXTN="ln"
function displaySyntax
{
echo "${PROGNAME}! SYNTAX: ${PROGNAME} some_dir_path"
exit 1
}
if [[ $# < 0 ]]
then
displaySyntax
fi
DIR="$1"
if [[ ! -d ${DIR}
then
displaySyntax
fi
find ${DIR} -type l|while read filepath
do
echo "FIXING: ${filepath} (=> ${filepath}.${LN_EXTN})"
mv ${filepath} ${filepath}.${LN_EXTN}
cp -L ${filepath}.${LN_EXTN} ${filepath}
done
This example KSH script would be invoked in a UNIX environment as follows:
$ fixLinks web_module_root
The script will go through any directory recursively and rename every file it finds that is a symbolic link with an additional .ln extension. Then the script will place a copy of the link target in the original location where the link was found.
The following properties are used to manage standard stderr and stdout log files. You can specify the types and locations of the log files to which the properties pertain with the -out and -err options of the oc4j.jar command.
For example, the following command specifies rotation of the stdout and 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
The next example specifies rotation of the stdout log file at 2:30 p.m. every day and limits the log 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-2 Archive Management Properties for stdout and stderr Files
Table 4-3 describes the general system properties that can be set for OC4J.
Table 4-3 -D General System Properties for OC4J
| Property | Description |
|---|---|
|
Sets the external directories to be searched for classes when compiling. |
|
|
Sets the temporary directory for the deployment wizard. The default is 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 |
|
|
If |
|
|
|
Sets the root directory into which you will install the OC4J distribution. Instead of using the |
|
|
Sets the J2EE home directory to the installed directory of the Setting this system property or the |
|
Enables IIOP stub generation. The default is |
|
|
Set whether the generated IIOP stub/tie code is kept. The default is |
|
|
|
If |
|
This property replaced the deprecated When two or more clients in the same process retrieve an If you set You can also set this in the JNDI properties. The |
|
|
|
This property can override the default behavior of halting OC4J initialization when JAR dependencies in its system libraries are not satisfied. The default property value is When OC4J initializes, it validates the dependencies of the libraries defined in the container-level configurations by verifying their versions specified in the MANIFEST.MF file. When this property is set to |
|
This property configures replication-based load balancing, with one of these settings:
The default setting is The |
|
|
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 in 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 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. |
|
|
|
This parameter should be set on the OC4J server. The previous method for turning on these performance metrics, |
|
For container-managed relationships in entity beans, you can designate whether a third database table is used to manage the relationship. Set to This property has been deprecated and works only with OrionCMP. |
|
|
Set this to 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 When you specify column types for a query with the |
|
|
|
This property is applicable when form-based authentication is used by a Web application. If set to If set to |
|
|
This property specifies the default character set for file encoding. If an encoding is not specified, OC4J uses ISO-8859-1 as the default character set. In a Windows environment, the default character set for file encoding should be Windows-1252, which is a superset of the ISO 8859-1 character set. To use the Windows-1252 character set as the default, specify |
|
|
This property controls the use of symbolic links. The default value is Oracle strongly recommends that this setting not be changed to For more information, see "Preventing the Use of Symbolic Links". |
|
|
This property controls the cache in which OC4J stores file information it collects when a client accesses an application using path information. The following settings enable you to control the cache:
The default value is |
|
|
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. |
|
|
This property enables or disables servlet class name invocation for all servlets within the OC4J instance. If set to To disable this functionality on a per-Web-application basis, set this property to The value set for |
|
|
This property enables logging for the Oracle CONFIGFINEFINERFINESTALL
To disable HTTPClient logging, set this property to HTTPClient logs messages only at trace levels ( For more information about setting log levels and enabling HTTPClient logging, see Chapter 4, "Logging Implementation Guidelines," in Oracle Containers for J2EE Developer's Guide. |
Note:
The debug properties listed in this section are deprecated in OC4J 10g (10.1.3.4.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-4 OC4J Debug Properties
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:
To enable remote debugging for a single OC4J instance with Application Server Control:
Navigate to the OC4J Home page.
Click Administration to display the OC4J Administration page.
Under Properties in the table of administration tasks, click the task icon in the Server Properties row.
Enterprise Manager displays the Server Properties page.
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
Click Apply to apply your changes to the OC4J configuration.
When you make changes to the server properties, you must restart the OC4J instance before the changes take effect.
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 of4000 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.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
For debugging Web applications from an IDE, you need to set up for servlet and JSP debugging, as the following topics describe:
To set up remote debugging for a servlet:
Mark your project run or debug configuration to do remote debugging.
Set the attach to JPDA in the remote-debug specific runtime configuration node.
Start your OC4J instance with the debug parameters, as the example under "Specifying Debug Start Parameters on a Startup Command Line" shows.
Set a breakpoint in your servlet.
Run a remote debugger.
After you invoke the servlet from a Web browser, the servlet should reach the breakpoint.
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>