C Using Oracle Application Server Containers for J2EE Plug-in

C.1 Overview

OC4J Plug-in is a shared library that can be loaded into IIS, or Sun ONE HTTP listener. It provides functionality to route requests directly from a third party listener to OC4J in the same manner mod_oc4j routes requests from Oracle HTTP Server to OC4J. Thus, requests for OC4J can be directly routed from IIS or Sun ONE to one or more OC4J JVMs using the AJP or AJP over SSL protocol.

Figure C-1 illustrates how the OC4J Plug-in routes requests directly from a third party listener to OC4J.

Figure C-1 OC4J Plug-in for IIS and Sun ONE

Description of "Figure C-1 OC4J Plug-in for IIS and Sun ONE"

C.2 Downloading OC4J Plug-in

OC4J Plug-in is available on the Oracle Application Server 10g Companion CD, which is included in your Oracle Application Server CD Pack.

C.3 Installing OC4J Plug-in

On the Oracle Application Server 10g Companion CD, the files are located at /plugins/solaris/ for UNIX and /plugins/win32/ for Windows.

Table C-1 contains information about the shared libraries for OC4J Plug-in.

C.4 Configuring OC4J Plug-in on Sun ONE

Place the opii.so file in a directory such as /sunone/opii.so, where it is readable by the Sun ONE listener. The following examples assume that Sun ONE is installed in a directory called /sunone, and that the instance being configured exists under /sunone/https-mymachine.

1. Add the following lines at the end of /sunone/https-mymachine/magnus.conf:

   Init fn="load-modules" shlib="/sunone/opii.so" funcs=opii_init,opii_objecttype,opii_service,opii_child_init
   
   Init fn="opii_init" log_file="/sunone/https-mymachine/logs/opii.log"
     log_level=error server_defs="/sunone/https-machine/config/opii.conf"
   Init fn="opii_child_init" LateInit=yes
   
   

   where, log_file points to a file where OC4J Plug-in messages will be logged and server_defs points to an OC4J configuration file.

   
   

   See Also: "OC4J Plug-in Configuration File"

   
   

2. Make the following modifications to /sunone/https-mymachine/obj.conf:

   1. Add the following line before any ObjectType line:

      ObjectType fn=opii_objecttype
      
      

   2. Add the following line before all other lines that begin with the word "Service":

      Service type="oracle/opii" fn="opii_service" UseOutStreamSize=8192
      
      

      
      

      Note: Not all versions of Sun ONE support UseOutputStreamSize. Refer to Sun ONE documentation for details.

      
      

3. If you want to enable the OC4J status page, which is equivalent to the URL /oc4j-service in mod_oc4j for Oracle HTTP Server, then make the following two changes to obj.conf:

   1. Add the following line above the other NameTrans entries inobj.conf:

      NameTrans fn=assign-name from="/oc4j-service" name="opii-status"
      
      

   2. Add the following section at the end of obj.conf:

      <Object name="opii-status">
      

         Service fn="opii_status_service"
   

         </Object>

C.5 Configuring OC4J Plug-in for IIS

Perform the following steps to configure OC4J Plug-in for IIS:

1. Edit your registry to create a new registry key named HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\OPII

2. Specify the exact location of your configuration file with the name server_defs, and a value pointing to the location of your configuration file, for example d:\opii\opii.conf.

   
   

   See Also: "OC4J Plug-in Configuration File"

   
   

3. (Optional) Specify a log_file and log_level:

   1. Add a string value with the name log_file, and the desired location of the log file, for example, d:\opii\plugin.log.

   2. Add a string value with the name log_level, and a value for the desired log level. Valid values are debug, inform, error, and emerg.

   3. If you want to enable the OC4J Plug-in status page, a page equivalent to mod_oc4j /oc4j-service URL, add a string value with the name status_uri and a value like /oc4j-service.

4. Using the IIS management console, add a new virtual directory to your IIS Web site with the same physical path as that of opii.dll. Name the directory opii and give it execute access.

5. Using the IIS management console, configure the plugin as an allowed Web Service Extension.

6. Using the IIS management console, add opii.dll as a filter in your IIS Web site. The name of the filter should be opii and its executable must point to the directory contain opii.dll, for example, d:\opii\opii.dll.

7. If you want to use dynamic routing, ensure that ORACLE_HOME is set in the system environment or plugin config file using the Oc4jOracleHome directive. Using the IIS management console, set the Identity of the Application Pool containing the plugin to "Local System" so that the plugin can communicate with OPMN.

8. Restart IIS (stop and then start the IIS server), ensuring that the filter is marked with a green arrow pointing up.

   
   

   Note: To restart IIS, you must stop all of the IIS services through the control panel, or restart the computer. This is the only way to ensure that the .dll is reloaded. Restarting IIS through the management console is not sufficient.

   
   

C.6 OC4J Plug-in Configuration File

When you set up the OC4J Plug-in in the third party listener, the configuration file points at a server_defs file, or the OC4J Plug-in configuration file. This file defines the OC4J instances that the OC4J Plug-in communicates with. It has the same syntax as the mod_oc4j file for Oracle HTTP Server. For example, a configuration file that contains only the following line

Oc4jMount /j2ee/* ajp13://localhost:3000

routes any requests to URLs that begin with/j2ee/ to the OC4J instance that has an AJP listener on the localhost interface on port 3000.

All of the Oc4j* directives defined for mod_oc4j also work for OC4J Plug-in. In additional to these directives, the OC4J Plug-in-specific directives Oc4jOracleHome can be used in place of setting the ORACLE_HOME directive in the environment for the third party listener. An ORACLE_HOME value is required if you want to use the dynamic functionality of the OC4J Plug-in.

The dynamic routing functionality of the OC4J Plug-in provides the same Oc4jMount syntax as mod_oc4j for routing to OC4J instances that are managed by OPMN. Accordingly, you can mount OC4J instances or clusters instead of just pointing at the host and port of a single JVM. In order to accomplish this, the OC4J Plug-in must be able to communicate with an ONS daemon on the same machine. If Oracle Application Server is installed on the same machine as the OC4J Plug-in, then this can be accomplished simply by setting either ORACLE_HOME in the environment, or setting the Oc4jOracleHome directive to point to the location of the ORACLE_HOME, and ensuring that the third party listener is running as the same user as Oracle Application Server, or root on UNIX.

If Oracle Application Server is not installed on the same machine, then the standalone ONS daemon must be installed. OC4J Plug-in supports all the mod_oc4j functionality, including AJP over SSL and use of port tunneling.

C.7 Integrating Generic Apache with Oracle Application Server

In Oracle Application Server, 10g Release 2 (10.1.2), you can integrate generic Apache with Oracle Application Server. In doing so, you can route requests from generic Apache to OC4J in the same manner as routing requests using Oracle HTTP Server and mod_oc4j. Generic Apache is Apache version 1.3.xx, and not Apache 2.x.

Using Oracle Notification Service (ONS), the communication method utilized between mod_oc4j and OC4J, you can load mod_oc4j into a generic Apache instance and use it in a static routing configuration without requiring any other Oracle infrastructure. In combination with mod_onsint and ONS, mod_oc4j can utilize the same dynamic configuration and failover options that are available when using Oracle HTTP Server.

This section discusses the following topics:

• Integration Requirements

• Generic Apache Files

• Setting Up a Static Configuration with mod_oc4j

• Setting Up a Dynamic Configuration with mod_oc4j and mod_onsint

• Integrating with Oracle Process Manager and Notification Server

$ORACLE_HOME/Apache/Apache/libexec/mod_oc4j.so
$ORACLE_HOME/Apache/Apache/libexec/mod_onsint.so
$ORACLE_HOME/opmn/lib/libons.so
$ORACLE_HOME/lib/libdms2.so

%ORACLE_HOME%\Apache\Apache\modules\ApacheModuleOc4j.dll
%ORACLE_HOME%\Apache\Apache\modules\ApacheModuleOnsint.dll
%ORACLE_HOME%\opmn\bin\onsclient.dll
%ORACLE_HOME%\bin\yod.dll

LoadModule oc4j_module libexec/mod_oc4j.so
Oc4jMount /j2ee/* ajp13://localhost:3001,ajp13://localhost:3002

LoadModule oc4j_module modules/ApacheOc4jModule.dll

LoadModule onsint_module libexec/mod_onsint.so
LoadModule oc4j_module libexec/mod_oc4j.so
Oc4jMount /j2ee/* cluster://mycluster:myinstance

<module path="$ORACLE_HOME/opmn/lib/libopmnohs"> 
  <module-id id="OHS"/> 
  <module-id id="GENERIC_APACHE"/> 
</module> 

</ias-component>
  <ias-component id="HTTP_Server"> 
    <process-type id="HTTP_Server" module-id="GENERIC_APACHE"> 
      <module-data> 
        <category id="start-parameters"> 
          <data id="apache-home" value="/private/my/path/to/APACHE"/> 
        </category> 
      </module-data> 
    <process-set id="HTTP_Server" numprocs="1"/> 
  </process-type> 
</ias-component>