Skip Headers

Oracle® HTTP Server Administrator's Guide 10g Release 3 (10.1.3) B25211-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# C Using Oracle Containers for J2EE Plug-in

This appendix explains how the Oracle Containers for J2EE Plug-in (OC4J Plug-in) enables you to use third party HTTP listeners to access servlets running in OC4J J2EE within Oracle Application Server. OC4J Plug-in works with Sun ONE Web Server for UNIX, and Microsoft Internet Information Server (IIS) for Windows.

See Also: `http://www.oracle.com/technology/products/ias/ohs/htdocs/plugincerts.html` for complete certification information.

It also contains information about using `mod_oc4j` in a non-Oracle Apache.

Topics discussed are:

- Overview

- Downloading OC4J Plug-in

- Installing OC4J Plug-in

- Configuring OC4J Plug-in on Sun ONE

- Configuring OC4J Plug-in for IIS

- OC4J Plug-in Configuration File

- Integrating Generic Apache with Oracle Application Server

## 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 AJP or AJP over SSL protocols.

Note: OracleAS Proxy Plug-in and OracleAS SSO Plug-in are certified to work with the entire Oracle Application Server stack, such as Oracle Application Server Portal and Oracle Application Server Wireless. However, OC4J Plug-in is only certified to run customer applications. For example, you cannot route requests from Sun ONE using OC4J Plug-in to an OC4J container where Oracle Application Server Wireless is running.

See Also: Appendix A, "Using Oracle Application Server Proxy Plug-in" Appendix B, "Using Oracle Application Server SSO Plug-in" "mod_oc4j"

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 directory structure is as follows:

    plugins/linux/apache
                 /apache2
                 /sunone

    plugins/win32/apache
                 /apache2
                 /iis
                 /sunone

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

Table C-1 OC4J Plug-in Shared Libraries

Platform | File Name | Location and Description | Instructions
--- | --- | --- | ---
UNIX | `opii.so` | `opii.so` is the OC4J plug-in for Sun ONE Web listener. It is located in the `/plugins/solaris/sunone` directory | To install the plug-in into the listener, place `opii.so` in a directory to which the listener has read and execute privileges.
Windows | `opii.dll` | `opii.dll` is the OC4J plug-in file for the IIS Web listener. It is located in the `/plugins/win32/iis` directory. | To install the plug-in into the listener, copy `opii.dll` to a directory the listener can access.
`opii_sunone.dll` | `opii_sunone.dll` is the OC4J plug-in for SUN ONE Web listener. It is located in the `/plugins/win32/sunone` directory | To install the plug-in into the listener, copy `opii_sunone.dll` to a directory the listener can access.

Note: In order to use the OracleAS SSO Plug-in or to turn on SSL with the OC4J Plug-in when using the plug-ins within IIS 6.0 on Microsoft Windows 2003, the permissions on the .dll files in the `%ORACLE_HOME%\bin` location must be changed. The .dll files must have execution permissions for the user `NETWORK SERVICE` added. Do not complete this operation during normal installation. Because IIS 6.0 is run as the user `NETWORK SYSTEM`, the plug-ins will not function correctly unless the necessary permissions are granted.

## 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 in`obj.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.5.1 Configuring Anonymous Access for IIS

Perform the following steps if you want OC4J to perform the authentication:

1. In the IIS Management GUI, right click the default Web site and select Properties.

2. Select the Directory Security tab and click the Edit button under Anonymous Access and Authentication Control. Be sure that the Anonymous access is checked and that basic authentication and integrated Windows Authentication are both unchecked.

Note: If you want IIS to perform authentication and simply pass the user name to OC4J, then do not disable authentication in IIS.

## 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.

See Also: "mod_oc4j Configuration File and Directives"

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.

See Also: "Running Oracle HTTP Server as Root"

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.

See Also: "Understanding Port Tunneling"

## C.7 Integrating Generic Apache with Oracle Application Server

In Oracle Application Server, 10g Release 3 (10.1.3), 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 or Apache 2.x.

See Also: Administering a Standalone Deployment Based On Apache 1.3 Administering a Standalone Deployment Based On Apache 2.0

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.

See Also: "mod_onsint"

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

### C.7.1 Integration Requirements

This section applies to Apache 1.3.x only. `mod_oc4j` and `mod_onsint` require the following open source software packages to be included in generic Apache builds that will be integrated with Oracle Application Server:

- Enhanced API (EAPI) provided as part of `mod_ssl`. EAPI provides a context mechanism that is used extensively by `mod_onsint` and `mod_oc4j` to share information and function callbacks between modules without introducing link time dependencies. EAPI is provided by configuring Apache with `mod_ssl`.

  Note: `mod_ssl` does not need to be loaded at runtime as it is the integration of EAPI provided by `mod_ssl` that is important.

  See Also: `http://www.modssl.org`

- (UNIX only) mm shared memory library. The mm library is used on UNIX platforms to share routing information between all of the child processes that make up an Apache instance on UNIX. This library is not necessary on Windows platforms since the Apache architecture on Windows uses a single multi-threaded process instead of many single-threaded processes.

  See Also: `http://www.ossp.org/pkg/lib/mm/`

### C.7.2 Generic Apache Files

Four libraries need to be accessible by the generic Apache instance that is going to be integrated with Oracle Application Server. If `mod_oc4j` is used in a static configuration and `mod_onsint` is not used, then you need only two libraries.

For Apache 1.3.x

On UNIX, the four files and their locations within an `ORACLE_HOME` are:

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

On Windows, the four files and their locations within an `ORACLE_HOME` are:

    %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

Note: These files are also available on the Oracle Application Server 10g Companion CD. On the CD, they are located in the following directories: `/plugins/linux/apache` for UNIX `/plugins/win32/apache` for Windows

For Apache 2.0.x

On UNIX, the four files and their locations within an `ORACLE_HOME` are:

    $ORACLE_HOME/ohs/modules/mod_oc4j.so
    $ORACLE_HOME/ohs/modules/mod_onsint.so
    $ORACLE_HOME/lib/libons.so
    $ORACLE_HOME/lib/libdms2.so

On Windows, the four files and their locations within an `ORACLE_HOME` are:

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

Note: These files are also available on the Oracle Application Server 10g Companion CD. On the CD, they are located in the following directories: `/plugins/linux/apache2` for UNIX `/plugins/win32/apache2` for Windows

It is easiest if the binaries for the two modules are copied into the same location as the other modules in the generic Apache installation, although this is not a requirement. Full paths can be used if you want to place the binaries elsewhere. The `dms` and `ons` libraries do not need to be in any specific location, but they must be in the your `LD_LIBRARY_PATH` on UNIX, and the `PATH` on Windows. On UNIX, this is most easily accomplished by editing the `apachectl` script used to start the generic Apache instance to set the `LD_LIBRARY_PATH` appropriately. On Windows, this is most easily accomplished by placing the appropriate directory into the System environment variable `PATH`. However, if more than one generic Apache instance is running on the same machine, then some other mechanism might be needed.

### C.7.3 Setting Up a Static Configuration with mod_oc4j

A simple configuration can be constructed using generic Apache and only `mod_oc4j`.

In this configuration, the host and port of all OC4J instances must be statically configured. There is no automatic registration of new JVMs, nor are failed JVMs ever removed from the routing table used by `mod_oc4j`. The advantage of this configuration is its simplicity, including the fact that it does not require the availability of other Oracle Application Server infrastructure components, such as ONS. The following is an example of such a configuration. This configuration loads `mod_oc4j` and provides routing of all requests starting with `/j2ee/` to two different JVMs, both located on the same machine, one at port 3001, and the other at port 3002:

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

On Windows, change the line used to load `mod_oc4j` to the following:

    LoadModule oc4j_module modules/ApacheOc4jModule.dll

On UNIX, this assumes that the `mod_oc4j.so` file will be copied into the `libexec` directory within the Apache installation. On Windows, it means that the `ApacheOc4jModule.dll` file will be copied to the modules directory within the Apache installation.

### C.7.4 Setting Up a Dynamic Configuration with mod_oc4j and mod_onsint

In order to provide full `mod_oc4j` functionality including dynamic detection of new JVMs and Oracle Application Server installations, `mod_oc4j` must be combined with `mod_onsint`.

In order to utilize `mod_onsint` and `mod_oc4j`, `ORACLE_HOME` must be set to point to an Oracle Application Server instance where OPMN is running. On UNIX, this can be accomplished by adding the setting of `ORACLE_HOME` to the `apachectl` script used to start the generic Apache instance. On Windows, this is most easily accomplished by setting `ORACLE_HOME` as a System environment variable.

The following configuration shows how to load the modules and mount `/j2ee` to the OC4J instance, `myinstance`, running within the Oracle Application Server cluster, `mycluster`.

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

Any allowable `Oc4jMount` syntax available from within Oracle HTTP Server is available when used with generic Apache. This configuration supports all of the same routing and availability features that `mod_oc4j` offers when running within Oracle HTTP Server, including dynamic discovery of new OC4J processes and instances as they are added and failover of both stateless and session based requests.

### C.7.5 Integrating with Oracle Process Manager and Notification Server

Oracle Process Manager and Notification Server (OPMN) can be configured to provide process management, such as starting, stopping, and restart capability for a generic Apache installation. To do this, the Apache instance must have `mod_onsint` configured. It should have the standard Apache directory layout, that is, the directory structure created by doing a standard Apache 1.3 installation.

Note: When generic Apache is started using OPMN, you have to set `OpmnHostPort` directive in `httpd.conf` or Apache will fail to start. For more information on `OpmnHostPort`, refer to "mod_onsint"

To configure OPMN to manage this Apache instance, the following changes must be made to `opmn.xml`:

In the module section add the `GENERIC_APACHE` module-id to the configuration for `libopmnohs`, such as:

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

In the `HTTP_Server` section, you must set the module to `GENERIC_APACHE` and set an `apache-home`, such as:

    </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>

You can configure either an Oracle HTTP Server instance or a generic Apache instance into any `opmn.xml`. Configuring both in the same `opmn.xml` is currently not supported.

See Also: "opmn.xml"