Oracle® Containers for J2EE Configuration and Administration Guide 10g (10.1.3.1.0) Part Number B28950-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 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.
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. 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:
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 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 stdout/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 stdout/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.
Setting System Properties in a Standalone OC4J Configuration
Setting System Properties in an OPMN-Managed OC4J Configuration
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 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
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>
Table 4-2 describes the general system properties that can be set for OC4J.
Table 4-2 -D General System Properties for OC4J
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
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
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 through the Application Server Control Console:
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 on 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 in "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>