Oracle8i Oracle Servlet Engine User's Guide Release 3 (8.1.7) A83720-01 |
Library | Service | Contents | Index

# 5
Apache Module for Oracle OSE

This chapter contains instructions on how to configure and use OSE, a servlet server, with Apache, an HTTP Web server. You will see how this arrangement delegates the dynamic content through `mod_ose` to the OSE running in Oracle8i.

The topics we cover are the following:

- Requirements for OSE with Apache

- Overview of mod_ose in Apache for OSE

- Configuring mod_ose in Apache for OSE

- Configuring Apache for OSE Applications

- Topology of a Site Using mod_ose

- mod_ose Installation for Pre-Installed Apache Systems

- Forwarding a URL

## Requirements for OSE with Apache

`mod_ose` requires the following Apache capabilities:

- Oracle HTTP server (powered by Apache)

- `mod_so` must be installed in Apache (or other support for Dynamic Shared Objects)

- `mod_mime` must be installed in Apache

- machine executing Apache must be configured as an Oracle client-side configuration

- Oracle client-side libraries must be available on LD_LIBRARY_PATH or equivalent

## Overview of mod_ose in Apache for OSE

`mod_ose` is a module in the Oracle HTTP server (Apache), which serves as a conduit from Apache to OSE. In conjunction with `mod_ose`, OSE is the servlet engine for Apache, where only static pages are served by Apache and the dynamic pages are served by OSE.

You can create multi-node, in-tandem configurations. With these types of configurations, you can make a more scalable service than you can with simple stand-alone OSE or Apache components.

Specifically, with a multi-node arrangement there is:

- no single point of failure

- fail-over configuration

- load balancing functionality

`mod_ose` works in a network in conjunction with Net8. The Oracle8 Net8 Administrator's Guide describes, in detail load balancing, using Oracle Listener, and the fail-over configuration.

Before determining how many and which type of server your network requires, you must understand the basic configuration of the two servers, Web and servlet. Figure 5-1 depicts a simple representation of the base network arrangement, in this order: browser, Apache, `mod_ose` inside Apache, Net8 (represented by the connection between `mod_ose` and the database), the database, and OSE.

#### Figure 5-1 Simple Topology of the Apache Web Server and Oracle's Servlet Engine (OSE), Using mod_ose

## Configuring mod_ose in Apache for OSE

This section introduces `mod_ose` configuration steps needed to use Apache as the HTTP server and OSE as the servlet server.

The following steps define the database connection descriptors for use with `mod_ose` and set the Apache configuration so that the requests are sent to the appropriate database.

1. Name the Oracle Net8 connection descriptor in `tnsnames.ora` as a pointer to the OSE service (see Example 5-1).

2. Generate a Web domain configuration file using the session shell command, `exportwebdomain` (see Example 5-2).

3. Include this generated configuration file in the Apache configuration file, `httpd.conf` (see Example 5-3).

4. If Apache was previously installed, define which connection to use (see Example 5-4).

### Connection Descriptors and Syntax of tnsnames.ora

`mod_ose` uses the same configuration mechanism for finding connection descriptors that other Oracle clients, such as OCI clients, do.

Depending on the `sqlnet.ora` configuration, connections are defined by either:

- `tnsnames.ora` file located in the directory pointed to by the environment variable TNS`_ADMIN`

or

- another Oracle name service, such as LDAP service, to retrieve the connection address

Entries for the connection used by Apache must be in `tnsnames.ora` and be defined by the following lines:

    <your_defined_http_connection_name> = (DESCRIPTION=

                                                 listenerAddress
                                                 (CONNECT_DATA=

                                                      serviceSpec
                                                      presentationSpec

                                                         )
                                                    )
          where the syntax is defined as,
           listenerAddress := (PORT=...)(ADDRESS=(HOST=...)(PROTOCOL=...)...)
           serviceSpec := (SERVICE_NAME=...) [ (INSTANCE_NAME=...) ]
           presentationSpec := (PRESENTATION=http://<JndiServiceName>)

##### Table 5-1 tnsnames.ora Connection Information Key Words

Key Words | Definitions
--- | ---
`listenerAddress` | An ADDRESS_LIST (host, port, protocol) in the case of multiple Oracle Listeners on the back end (multiple nodes). This allows for load balancing and fail-over configurations, as well as the use of CMAN for connection concentration. Read the Oracle8 Net8 Administrator's Guide for details on how to set this parameters.
`serviceSpec` | group of database instances: specify SERVICE_NAME Defines a group of instances that can be used interchangeably. When there are multiple database instances, `mod_ose` load balances the connections between the different instances. `mod_ose` guarantees stateful requests from a client are sent to the same database instance so they can be associated with the same database session.
| single database instance: specify INSTANCE_NAME Indicates an specific instance within the service group should be used.
`presentationSpec` | indicates which HTTP service should be used for this connection. <JndiServiceName> is a place holder for the name of a service in the JNDI namespace (for example,`/service/ServiceName`) that understands HTTP and has a `Net8` end-point associated with it. See the session shell command, `createwebservice`.

Connection(s) are named in the `tnsnames.ora` file, as shown in the following example.

#### Example 5-1 tnsnames.ora Defines Entry, inst1_http, as the Apache Connection in This Scenario

           inst1_http = (DESCRIPTION=
                                   (ADDRESS=(PORT=5521)(host=dlsun1609)(PROTOCOL=tcp))
                                   (CONNECT_DATA=
                                         (SERVICE_NAME=<WebServerName>)
                                         (PRESENTATION=http://admin)
                                       )
                                     )

Note: <WebServerName> is the place-holder for your Web server name, such as `foo.us.oracle.com`.

## Configuring Apache for OSE Applications

OSE was design for stateful Web applications. For these types of applications, each browser client is assigned a database session that keeps track of all stateful applications the user is executing in the domain. By default, all applications are considered stateful.

### Stateful and Stateless Applications in Apache

You can configure Apache to use a stateless connection to OSE. There are certain applications for which a database session does not keep state information, with respect to the client. For these requests, each Apache process has a semi-persistent connection to a session used to process stateless connections to any client. Because each Apache worker handles only one request at a time, the stateless connection is used sequentially by different incoming clients. Stateless servlet contexts and stateless servlets must be indicated as such when published to the JNDI namespace.

The commands `ServletContext` entry and `Servlet` (see Oracle Java Tools Reference for each entry) in the session shell tool have a -stateless option that you can use to declare which application contexts or particular servlets are stateless. This information, used in conjunction with the `Export` command, simplifies management of the configuration.

Several Oracle APPS use the stateless model. It is advantageous in such cases to declare them as stateless when installed in OSE.

### Stateful and Stateless Handlers in Apache

We specify whether a request uses the stateful or the stateless connection by specifying the particular variant of the handler to use:

           SetHandler aurora-stateless-server
           SetHandler aurora-statefull-server
           SetHandler aurora-server

- The first handler (specifying the stateless connection) considers a request served through this channel attempting to start an HttpSession as an error.

- The second handler (specifying the stateful connection) allows an HTTPSession and requires Apache to define a separate session to serve the requests.

- The third handler uses the default mode (stateful).

#### Figure 5-2 Stateful Vs. Stateless Sessions

### Extracting Configuration Information for Apache

A unique place specifying the configuration of Web applications running on OSE is the JNDI name space in JServer. A tool, exportwebdomain, extracts the information about the applications installed in a Web domain and generates the corresponding `Apache.conf` file. Include this file in the Apache main configuration file (see Example 5-2, "Export the Web Domain Structure to an Apache CFG File").

1. Use the exportwebdomain command to generate the structure of a `webdomain` in a configuration file for mod_ose. The export utility works in two stages:

- Generates in XML format the structure of a `webdomain` or `contexts` within a domain.

- Applies transformations to the XML, producing configuration files specific to `mod_ose`. Generate a configuration file at the shell level.

      sess_sh -s <ose-url> -u <user> -p <passwd>

      exportwebdomain -format Apache -netservice <name in tnsname.ora> <Web domain> & > <file.conf>

The command connects to the server and generates the `webdomain` information in the format required by Apache and saves it into <file.conf>.

The parameters are defined as:

  `<`Web domain`>` - The JNDI location of the Web domain to export (defaulted to service root for the single-domain).

  `<`file.conf`>` - The name of the file to store the generated configuration, in this case, `Apache.conf`.

The options are defined as:

  format type: produces output in a defined format. Use the text string Apache or `apache` to generate the configuration file for `mod_ose`.

  See the `export` command, in the Oracle Java Tools Reference, for details of all the options available. In particular, you can select to export particular contexts, or for whether doc_root (static pages) should be requested to OSE or will be served locally.

#### Example 5-2 Export the Web Domain Structure to an Apache CFG File

1. Enter:

       exportwebdomain -format apache -netservice inst1_http /webdomains & >
       /apache/config/webdomains.cfg

The output file `webdomains.cfg` holds the Web domain configuration.

1. Include this generated file, shown in the following example, at the bottom of the Apache configuration file, `httpd.conf`.

#### Example 5-3 exportwebdomain Command Output Results, webdomains.cfg

## Topology of a Site Using mod_ose

When using `mod_ose`, you can configure different network topologies with the system in your Web environment. Specifically, you can define configurations that do not have a single point of failure. In such configurations, when a node failure occurs, any available Oracle Listener can redirect requests to some other database instance if the one being used for the client state has failed. For this to work, the application must have been replicated in all nodes, and it must be able to handle the recovery from an expired database session.

#### Figure 5-3 Listeners and Load Balancing Through mod_ose, Using Net8

## mod_ose Installation for Pre-Installed Apache Systems

If Apache is already installed on your system, you must set the configure as required by OSE. If Apache is installed by Oracle with the OSE, the installation is complete.

From the `bin` directory of your Apache installation, execute the command:

    apxs -i -a -n mod_ose $APACHE_HOME/Apache/libexec/libjipa8i.so

This command copies the module to your Apache installation and makes it available by adding the corresponding `LoadModule` directive to `httpd.config`. The next time Apache is restarted, the new module will be available.

Note:: The installer should make the library available in `$`APACHE`_HOME/Apache/libexec.` `libjip.so,` on which `libjipa8i.so` depends, is copied to `$ORACLE_HOME/lib` by the installer.

### Apache Configuration

The Apache configuration is divided in two parts:

- Specification of OSE Service (for requests)

- Specification of Dynamic Requests (URLs)

#### Specification of OSE Service

In this step, we configure which connection to use when communicating with OSE in the database. You can configure the OSE service in Apache only at the virtual host level. Paths in a virtual host can be routed to only one OSE server.

Use the `mod_ose` command `AuroraService,` to specify which connection description should be used to contact OSE. The syntax is:

    <IfModule mod_ose.c>
           AuroraService connection-name
    </IfModule>

The following configuration example define which connection to use, pointing to the `inst1_http` connection, as defined in Example 5-1:

#### Example 5-4 Defining the Connection Description Contacting OSE

    <IfModule mod_ose.c>
           AuroraService inst1_http
    </IfModule>

If the virtual host does not define its own `AuroraService` configuration, then the default Host configuration will be used.

#### Specification of Dynamic Requests

The `AddHandler` and `SetHandler` commands, defined as part of `mod_mime`, specify which requests are sent to Aurora. (See "Requirements for OSE with Apache" , regarding `mod_mime`.)

- `AddHandler` specifies file extensions

- `SetHandler` specifies the address segment sent to OSE

#### Example 5-5 AddHandler Specifies File Extensions Served by OSE

    AddHandler aurora-server .jsp .snoop

This sends stateful requests for a file with a .`jsp` or .`snoop` extension to OSE.

#### Example 5-6 SetHandler Specifies All Connection Requests, Parsing the Address Segment Sent to OSE

    SetHandler aurora-server

This command must be used in conjunction with the Location directive, parsing the components of the virtual path served by OSE:

    <Location /examples/>
           SetHandler aurora-server
    </Location>

The virtual path of the request used in Apache are forwarded as is to the OSE. The OSE generates the passed segment of the Apache configuration string from the JNDI namespace information.

## Forwarding a URL

When an HTTP request comes through Apache to `mod_ose`, the initial path information, `http://<``web-domain:port``>` is discarded. The remaining path is sent to OSE. After the servlet is executed, the result is returned to the client. In general, the request path initiates Apache routing a request through `mod_ose` to the servlet server.

#### Example 5-7 Apache Routing a Request Through mod_ose to OSE

If 3000 is the port on which Apache is listening and the following directive is included in the `httpd.conf` file:

     <Location /MyContexts>
        SetHandler aurora-server
     </Location>

The client asks for `http://apacheserver:3000/MyContexts/Counte`r. `mod_ose` forwards the request as, `/MyContexts/Counter`, to OSE. If `/Counte`r is found as a published servlet in the `/MyContexts` servlet context directory, then OSE sends a response. If not found, the default servlet returns Error 404 (Not Found) by default. You can change this behavior with the servlet management tools.

The same logic applies when processing static files.

#### Example 5-8 Apache and mod_ose Processing Static Files

If the client asks for, `http://apacheserver:3000/MyContexts/index.html`

Then the `/MyContexts/index.html` file must exist under the root directory, as specified in the URL., showing how you can send a path and a file name and the entire path is read.

Note: Example 5-8 highlights a specific request operation detail for those who use `mod_jserv`.

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index