5 Configuring OC4J

This chapter describes OC4J configuration in the OPMN opmn.xml file.

It features the following topics:

Section 5.1, "OC4J Process Module Configuration"
Section 5.2, "OC4J Minimum Configuration"
Section 5.3, "OC4J Complete Configuration"
Section 5.4, "OC4J Attribute Descriptions"

5.1 OC4J Process Module Configuration

The following lines load and identify the OC4J process module. Management of OC4J processes by the process module are identified by the module id.

<module path="$ORACLE_HOME/opmn/lib/libopmnoc4j.so">
   <module-id id="OC4J" />
</module>

5.2 OC4J Minimum Configuration

The following lines represent the minimum configuration for OC4J. Default values are assigned to all other configuration elements and attributes for OC4J.

<ias-component id="OC4J">
   <process-type id="home" module-id="OC4J">
      <port id="ajp" range="3301-3400" />
      <port id="rmi" range="3101-3200" />
      <port id="jms" range="3201-3300" />
      <process-set id="default-island" numprocs="1"/>
   </process-type>
</ias-component>

5.3 OC4J Complete Configuration

The complete configuration example in this section showcases the attributes of OC4J configuration that you can control. It contains all possible configuration elements and attributes that can be used with this component.

<ias-component id="OC4J" status="enabled" id-matching="false">
   <environment>
      <variable id="LD_LIBRARY_PATH" value="$ORACLE_HOME/lib" 
      append="true" />
   </environment>
      <process-type id="home" module-id="OC4J">
         <port id="ajp" range="3301-3400" />
         <port id="rmi" range="3101-3200" />
         <port id="jms" range="3201-3300" /> 
      <process-set id="default-island" restart-on-death="true" numprocs="1">
      <module-data>
         <category id="start-parameters">
            <data id="java-options" value="-DTestVar=TestVal"/>
            <data id="oc4j-options" value=" "/>
            <data id="config-file" value="/my/config/dir/server.xml"/>
            <data id="java-bin" value="/my/javalocation/jdk/bin/java"/>
         </category>
         <category id="stop-parameters">
            <data id="java-options" value="-DTestVar=TestVal"/>
         </category>
         <category id="restart-parameters">
            <data id="reverseping-timeout" value="345"/>
            <data id="no-reverseping-failed-ping-limit" value="3"/>
            <data id="reverseping-failed-ping-limit" value="6"/>
         </category>
         <category id="urlping-parameters">
            <data id="/j2ee/servlet/Spy" value="200"/>
         </category>
         <category id="security-parameters">
            <data id="wallet-file" value="file:/private/user/ssl_cert/client_cert"/>
            <data id="wallet-password" value ="welcome1"/>
         </category>
      </module-data>
         <start timeout="300" retry="3"/>
         <stop timeout="300"/>
         <restart timeout="300"/>
         <ping timeout="30" interval="30"/>
      </process-set>
   </process-type>
</ias-component>

5.4 OC4J Attribute Descriptions

This section describes the attributes that are specific for OC4J. This section also provides attribute descriptions of the attributes.

The OC4J attributes are described with the following format:

Title: This is the attribute name and value being defined. For example, id="OC4J".
Required: This field defines whether or not the attribute is required in the component definition.
Default: This defines the default value assigned to the attribute. The default value appears in the installed version of the opmn.xml file or is assigned internally if the attribute is not present.
Valid values: If applicable, this field defines the valid values for the attribute. For example, OC4J.
Path: This field defines in which elements the attribute can appear. For example, ias-component.

id="OC4J"

Required: true
Default: none
Valid values: OC4J
Path: ias-component

The id name is required and cannot be changed. The id must match the entry in the targets.xml file or Application Server Control Console will not work.

environment

Required: false
Default: none
Path: ias-component

The environment element can be specified at multiple levels within the Oracle Application Server component. This concept is important for the OC4J module because OC4J processes can be part of other Oracle Application Server components. In those cases, the required environment may have to be specified at the ias-component/process-type level.

process-type

Required: true
Default: none
Path: ias-component

For OC4J processes, the process-type element is administratively equivalent to an OC4J instance.

module-id="OC4J"

Required: true
Default: none
Path: ias-component/process-type

The module-id associates the process with a module. For OC4J processes, this id has to match the module-id specified in the process module configuration for the OC4J module.

port

Required: true
Default: none
Path: ias-component/process-type

The OC4J processes will not be started up unless port elements for ajp and rmi ports are configured. An OC4J process can be pinged at the ajp ports; therefore one of the ports has to be configured. If both type of ports are configured, then the ajp port is used for pinging. In addition to the ajp and rmi ports, you can also configure other port types that will be passed in to the OC4J process at the command line during process startup.

id="ajp"

Required: true
Default: none
Path: ias-component/process-type/port

A port element defining ajp port values is required.

id="rmi"

Required: true
Default: none
Path: ias-component/process-type/port

A port element defining rmi port values is required.

id="jms"

Required: true
Default: none
Path: ias-component/process-type/port

A port element defining jms port values is required.

range

Required: true
Default: none
Valid values: range of ports, individual port numbers or 0
Path: ias-component/process-type/port

This attribute is used to specify valid port ranges, comma separated list of ports or a mix of both. For port selection by the operating system to select ports, specify 0 and the OC4J process will use a port provided by the system.

<process-set>

Required: true
Default: none
Path: ias-component/process-type

For OC4J processes, the process-set element is administratively equivalent to an OC4J island.

id="start-parameters"

Required: false
Default: none
Path: ias-component/process-type/process-set/module-data/
category

The start-parameters id is a category that collects all of the parameters that are relevant for the startup of an OC4J process.

id="java-options"

Required: false
Default: none
Valid values: any options acceptable to Java
Path: ias-component/process-type/process-set/module-data/
category/data

OC4J requires that some java-options be passed to start and stop commands. These options are derived internally by OPMN, are not part of the opmn.xml configuration, and cannot be overridden. Additional java-options may be specified using this module data element.

id="oc4j-options"

Required: false
Default: none
Valid values: any options acceptable to the OC4J executable
Path: ias-component/process-type/process-set/module-data/
category/data

OC4J processes require options to be passed in as part of the start or stop commands to function correctly. These options cannot be overridden. In addition to these options, other options can be passed in through this module data element. There is no default value for this data element.

id="config-file"

Required: false
Default: $ORACLE_HOME/j2ee/<process-type id>/config/server.xml
Valid values: any full path to an existing configuration file
Path: ias-component/process-type/process-set/module-data/
category/data

The configuration file is an OC4J option in the start command. The default value for this data element is built from the $ORACLE_HOME variable and OC4J instance name (process-type id).

id="java-bin"

Required: false
Default: $ORACLE_HOME/jdk/bin/java
Valid values: Full path to java.exe
Path: ias-component/process-type/process-set/module-data/
category/data

The default value is the complete path to Java that is available in the installation. You can specify alternate paths to the Java executable. However, a valid version of Java will have to be used for the process to start up and work correctly.

id="stop-parameters"

Required: false
Default: none
Path: ias-component/process-type/process-set/module-data/
category

The stop-parameters id is a category that includes all the parameters that are relevant for stopping an OC4J process.

id="restart-parameters"

Required: false
Default: none
Path: ias-component/process-type/process-set/module-data/
category

The restart-parameters category is used for defining parameters that will be used in death-detection.

id="reverseping-timeout"

Required: false
Default: 300 seconds
Valid values: Any reasonable timeout value
Path: ias-component/process-type/process-set/module-data/
category/data

The reverseping-timeout value is the maximum allowable time between two notifications arriving from an OC4J process. As part of death-detection, the OC4J module performs forward pings on the process also. In the event that forward pings start failing, the reverse pings are taken into account in death-detection and restart.

id="no-reverseping-failed-ping-limit"

Required: false
Default: 1
Valid values: Any value that reflects the tolerance that OPMN should have for failed forward pings when reverse pings are also failing. This tolerance is used by OPMN to determine when the process should be declared as unresponsive and replaced.
Path: ias-component/process-type/process-set/module-data/
category/data

This module data element defines the tolerance for failed forward pings in the event that reverse pings are also not being received (within the timeout period specified by reverseping-timeout data element). After the number of ping failures equals this limit, the process is deemed unresponsive and restarted by OPMN.

id="reverseping-failed-ping-limit"

Required: false
Default: 3
Valid values: Any reasonable value that reflects the tolerance that OPMN should have for failed forward pings when reverse pings are being received. This tolerance is used by OPMN to determine when the process should be declared as unresponsive and replaced.
Path: ias-component/process-type/process-set/module-data/
category/data

This module data element defines the tolerance for failed forward pings when reverse pings are succeeding. After the number of ping failures equals this limit, the process is deemed unresponsive and restarted by OPMN.

id="urlping-parameters"

Required: false
Default: Not Applicable
Valid values: Not Applicable
Path: ias-component/process-type/process-set/module-data/
category

The "urlping-parameters" id enables users to specify URLs for ping operations as part of OC4J process ping operations. The data under this category consists of the URL and a valid HTTP return code. AJP13 protocol is used to directly connect to the OC4J process and the HTTP return code is validated against the configured code. If there are multiple URLs configured, failure in pinging any one of them will be considered a ping failure and the process will be restarted after the ping failures limit is exceeded.

id="/j2ee/servlet/Spy"

Required: false
Default: Not Applicable
Valid values: Any valid URL on the OC4J process.
Path: ias-component/process-type/process-set/module-data/
category/data

This is the URL in the OC4J process that will be pinged.

value="200"

Required: false
Default: Not Applicable
Valid values: Any valid HTTP return code.
Path: ias-component/process-type/process-set/module-data/
category/data

The following is the HTTP code that results from ping operations to the configured URL.

<category id="security-parameters">
   <data id="wallet-file"value="file:/private/user/ssl_cert/client_cert"/>
   <data id="wallet-password"value="welcome1"/>
</category>

id="security-parameters"

Required: false
Default: Not Applicable
Valid values: Not Applicable
Path: ias-component/process-type/process-set/module-data/
category/

The OC4J process module can perform pings over SSL. The "security-parameters" id is a category that enables users to specify the wallet file and password for such communication.

id="wallet-file"

Required: false
Default: Not Applicable
Valid values: Not Applicable
Path: ias-component/process-type/process-set/module-data/
category/data

The data id whose value is the path to the wallet file (not including the filename).

value="file:/private/user/ssl_cert/client_cert"

Required: false
Default: Not applicable
Valid values: Path to a wallet file (not including the filename).
Path: ias-component/process-type/process-set/module-data/
category/data

The path to the wallet file (not including the filename). The data in the wallet file is used in SSL authentication during pinging.

id="wallet-password"

Required: false
Default: Not applicable
Valid values: Not applicable
Path: ias-component/process-type/process-set/module-data/
category/data

The data id that specifies the wallet password.

value ="welcome1"

Required: false
Default: Not applicable
Valid values: The valid wallet password.
Path: ias-component/process-type/process-set/module-data/
category/data

This value specifies the password for the wallet.