Skip Headers
Oracle® Process Manager and Notification Server Administrator's Guide
10g Release 2 (10.1.2)
B13996-02
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

15 Configuring Custom Process

This chapter describes custom process configuration in the OPMN opmn.xml file.

It features the following topics:

15.1 Custom Process Module Configuration

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

<module path="$ORACLE_HOME/opmn/lib/libopmncustom.so">
   <module-id id="CUSTOM" />
</module>

15.2 Custom Process Minimum Configuration

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

<ias-component id="Custom">
   <process-type id="Custom" module-id="CUSTOM">
   <process-set id="Custom" numprocs="1">
      <module-data>
         <category id="start-parameters">
            <data id="start-executable" value="Your start executable here" />
         </category>
      </module-data>
   </process-set>
   </process-type>
</ias-component>

15.3 Custom Process Complete Configuration

Example 15-1 show a complete configuration for a custom process. It contains all possible configuration elements and attributes for a custom process.

A custom process can be part of any other Oracle Application Server component. In such cases, the process-type element in Example 15-1 must be part of the component configuration.

15.3.1 Ping

The custom module provides the framework for pinging a custom process in one of two ways:

  • HTTP ping

  • script ping

The type of ping can be configured by specifying the appropriate data in the ping-parameters category. The sample Oracle Application Server configuration example Example 15-1 shows a custom process using HTTP ping. Example 15-2 is an example of script ping that you can substitute into the component configuration.

Example 15-1 Custom Process Complete Configuration

<ias-component id="Custom" status="enabled" id-matching="false">
   <environment>
      <variable id="TEST_ENV_VARIABLE" value="/your/test/value" 
      append="false"/>
   </environment>
   <process-type id="Custom" module-id="CUSTOM">
   <process-set id="Custom" restart-on-death="true" numprocs="1">
      <module-data>
         <category id="start-parameters">
            <data id="start-executable" value="Your start executable here" />
            <data id="start-args" value="Your start args here" />
         </category>
         <category id="stop-parameters">
            <data id="stop-executable" value="Your stop executable here" />
            <data id="stop-args" value="Your stop args here" />
         </category>
         <category id="restart-parameters">
            <data id="restart-executable" value="Your restart executable here"/>
            <data id="restart-args" value="Your restart args here" />
         </category>
         <category id="ping-parameters">
            <data id="ping-type" value="http" />
            <data id="ping-url" value="/your/ping/url" />
            <data id="ping-host" value="abc.company.com" />
            <data id="ping-port" value="7777" />
            <data id="ping-limit" value="3" />
            <data id="ping-timeout" value="300" />
         </category>
         <category id="ready-parameters">
            <data id="use-ping-for-ready" value="false" />
         </category>
      </module-data>
   </process-set>
   </process-type>
</ias-component>

Pinging with a script can be configured as shown in Example 15-2.

Example 15-2 Ping Type Script

<category id="ping-parameters">
   <data id="ping-type" value="script" />
   <data id="script-executable" value="Ping executable here" />
   <data id="script-args" value="Ping arguments here " />
</category>

You can use pinging (when available) for determining the readiness of a process. This indicates that OPMN needs confirmation that a managed process has started successfully after creation. Processes can inform OPMN of their ready status in various ways. The custom module enables these processes to communicate readiness through pinging. If you configure pinging for a custom process, you can also use this mechanism to determine if the process is ready. You can choose not to configure any mechanism for determining readiness in which case the custom module just assumes that the process started successfully.


Note:

The ready ping, if configured, is created soon after the process is created. If the process takes a while to initialize and respond to pings, then using pinging for determining readiness is not appropriate. This is because if the process does not respond to the "ready ping", OPMN will determine that the process did not start correctly and stop it.

15.4 Custom Process Attribute Descriptions

This section describes the attributes that are specific for a custom process. This section also provides attribute descriptions of the attributes.

The custom process attributes are described with the following format:

id="Custom"


Required: true
Default: none
Valid values: Any id of your choice
Path: ias-component
Path: ias-component/process-type
Path: ias-component/process-type/process-set

This id is required and can be any name you choose. The id cannot be a duplicate of existing names.

module-id="CUSTOM"


Required: true
Default: none
Valid values: The same as the module-id specified in Section 15.1, "Custom Process Module Configuration".
Path: ias-component/process-type

The module-id associates the process with a module. For Custom processes, this id has to match the module-id specified in Process Module Configuration for the Custom module.

id="start-parameters"


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

The start-parameters category contains child elements specifying the start executable and start arguments.

id="start-executable"


Required: true
Default: none
Valid values: a valid executable to run
Path: ias-component/process-type/process-set/module-data/category/
data

This data element specifies the name of the executable to be started.

id="start-args"


Required: false
Default: none
Valid values: Valid arguments to the executable specified by start-executable data element.
Path: ias-component/process-type/process-set/module-data/category/
data

The value of this data element should be a string containing all the arguments for the start executable. Multiple data elements with this id should not be specified.

id="stop-parameters"


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

The stop-parameters category contains child elements specifying the stop executable and stop arguments. If this category is not configured, OPMN stops the process with the kill command.

id="stop-executable"


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

This data element specifies the name of the executable to be used for stopping the process.

id="stop-args"


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

The value of this data element should be a string containing all the arguments to the stop executable. Multiple data elements with this id should not be specified.

id="restart-parameters"


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

The restart-parameters category contains child elements specifying the restart executable and restart arguments. This category needs to be configured if the process has an explicit restart command. In the absence of a restart command, a stop followed by the start command will be executed whenever the process needs to be restarted.

When restart data is specified, OPMN assumes that the process ID of the process remains the same after a restart. If there is no explicit restart command available for the process, a stop followed by a start is issued. In this scenario, a process ID change is acceptable.

id="restart-executable"


Required: false
Default: none
Valid values: A valid restart executable name
Path: ias-component/process-type/process-set/module-data/category/
data

This data element specifies the name of the executable to be used for restarting the process.

id="restart-args"


Required: false
Default: none
Valid values: valid arguments to the restart executable
Path: ias-component/process-type/process-set/module-data/category/
data

The value of this data element should be a string containing all the arguments to the restart executable. Multiple data elements with this id should not be specified.

id="ping-parameters"


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

Custom processes that are pinged through the HTTP protocol must specify this category. This module data category consists of all the data required to perform such a ping.

id="ping-type"


Required: false
Default: none
Valid values: http, script
Path: ias-component/process-type/process-set/module-data/category/
data

Custom processes that wish to be pinged have to specify this module data.

id="ping-url"


Required: false
Default: /
Valid values: Any valid URL
Path: ias-component/process-type/process-set/module-data/category/
data

This data element is used to specify the URL at which the process will be pinged. The listed parameters are used for HTTP pings.

id="ping-host"


Required: false
Default: none
Valid values: A valid hostname to which a custom process is bound.
Path: ias-component/process-type/process-set/module-data/category/
data

This data element is used to specify the host name to which a custom process is bound. If this data is not specified, pinging will not be performed. If an invalid hostname is specified, the process-set will be disabled.

id="ping-port"


Required: false
Default: none
Valid values: A valid port at which a custom process is listening for HTTP requests
Path: ias-component/process-type/process-set/module-data/category/
data

The port at which a custom process is listening. If this data is not specified, pinging will not be performed. If an invalid port is specified, the process-set will be disabled.

id="ping-limit"


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

This module data element defines the tolerance for failed pings. After the number of ping failures reaches this limit, the process is deemed unresponsive and restarted by OPMN.

id="ping-timeout"


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

The timeout value specified with this data element is used as the maximum time OPMN will wait for a ping response. If a response is not obtained within the timeout period, the ping attempt will be considered a failure.

id="script-executable"


Required: false
Default: none
Valid values: A valid script executable
Path: ias-component/process-type/process-set/module-data/
category/data

This data element specifies the name of the executable to be used for pinging the process. An exit value of 0 from this executable is considered success. All other values indicate a ping failure.

id="script-args"


Required: false
Default: none
Valid values: valid arguments to the ping executable
Path: ias-component/process-type/process-set/module-data/
category/data

The value of this data element should be a string containing all the arguments to the ping executable. Multiple data elements with this id should not be specified.

id="ready-parameters"


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

The module data category to indicate if pinging should be used to determine that a custom process started successfully.

id="use-ping-for-ready"


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

The value of this data element determines if pinging should be used to determine if a process is available.