Oracle9i Servlet Engine Developer's Guide
Release 1 (9.0.1)

Part Number A90213-02
Go To Documentation Library
Go To Product List
Book List
Go To Table Of Contents
Go To Index

Master Index


Go to previous page Go to next page

An Apache Module for OSE

This chapter describes mod_ose, the module that you use to connect to the OSE/OJVM from the Oracle HTTP Server. The Oracle HTTP Server (powered by Apache) is the Web server that runs in the middle tier, listens to HTTP requests, serves static pages to HTTP clients, and can forward HTTP requests to be handled by servlets or JSPs to the Oracle Servlet Engine running in the data tier.

This chapter describes the basic concepts and use of mod_ose. For specific information about configuring mod_ose to use with your applications, see Chapter 5, "Configuring mod_ose".

For additional Apache Web server documentation navigate to the Apache Web site at or read one or more of the trade books that cover the Apache server.

Here are the topics covered in this chapter


The Oracle HTTP Server, available with the Oracle Internet Application Server (iAS) Release 1 and to be available with Release 2, is a Web server powered by the Apache server engine. The Oracle HTTP Server is used with the OSE/OJVM for Web applications that serve many static Web pages, or that deploy stateless servlets to the Oracle9i server.

Why Use mod_ose?

When you combine Apache with the OSE/OJVM, you get an efficient applications solution that can serve static HTML pages directly from the file system of the server on which Apache is running, and can serve dynamic content from Java servlets and JSP pages. The servlets and JSP pages run under the OSE/OJVM, on the database server, and can benefit from the OSE's fast and efficient access to SQL data.

If you are using the OSE/OJVM and your application makes use of stateless servlets, you should always use mod_ose. Not using mod_ose, and connecting directly to the OSE/OJVM, could cause each HTTP request to start up a new database session and a new OJVM. This can be very expensive, both in the time involved and the resources required on the OSE/OJVM server. When you use Apache and mod_ose, a stateless connection is kept open to the Oracle instance that is running an OSE/OJVM session for each httpd process running on the Apache server system. A new client request, or a new stateless HTTP request from a previous client, can thus re-use existing connections. This avoids the overhead of opening a new OSE/OJVM session on the data tier server for each stateless HTTP request, and enables new HTTP requests to use any static information cached on the server by previous stateless requests.

Apache Architecture

An Apache Web server consists of the server, with its basic listening functionality, and a number of plug-ins or modules, which customize the Apache server and add functionality to it for specific applications. For example, the mod_perl module allows the Perl language interpreter to run inside each Apache httpd process, providing better efficiency for CGI or other scripts that use Perl. And the Oracle HTTP Server offers the mod_plsql module, that lets Apache access PL/SQL code running in an Oracle9i server.

mod_ose is the Oracle HTTP Server module that serves as a conduit from Apache to the OSE/OJVM. When mod_ose is configured into Apache, each httpd process that is started by the Apache listener incorporates mod_ose. Note that each httpd/mod_ose process is independent of the others. These processes cannot share data.

mod_ose forwards HTTP requests that invoke servlets and JSP pages to the Oracle server, using a standard Oracle Net connection. This is the same type of connection that an OCI or a Forms application uses.


The communications protocol for the mod_ose connection uses HTTP tunnelling over the Oracle Net connection. The Oracle listener strips off the Oracle Net headers before the request is handed to the OSE, so the OSE sees it as a normal HTTP request. 

Figure 4-1 shows how the Web server and the httpd/mod_ose processes relate to the OSE/OJVM.

Figure 4-1 OSE/mod_ose Components

Text description of ModOse_01.gif follows.
Text description of the illustration ModOse_01.gif


The configuration of mod_ose determines which URLs cause HTTP requests to be forwarded to the OSE for processing, and which URLs are processed by the local Apache listener.

There are two files that are used by the Oracle HTTP Server to configure Apache and mod_ose. These are httpds.conf and ose.conf. Specific information about setting up these configuration files is available in Chapter 5, "Configuring mod_ose".


To use Apache and mod_ose, you must have the following components and capabilities:

Apache can run either on the same machine as the Oracle database server, or on one or more different machines. See the whitepapers from Oracle's Java Platform Group and the Internet Applications Group for more information about efficiently configuring a large application using both the Oracle HTTP Server and Oracle9i.

To configure mod_ose, see Chapter 5, "Configuring mod_ose".

Shared versus Dedicated Servers

The OSE runs under the JVM, and so must run in an Oracle9i shared server environment. (This is called the multi-threaded server for Oracle8i.) If you do not normally run a Oracle shared server configuration, it is still possible to use mod_ose by dedicating a dispatcher to a mod_ose channel. This can be done with adjustments to the Oracle listener's TNSNAMES.ORA initialization file. See the section "Non-Shared Server Installations" for more information.

mod_ose Connections

mod_ose can provide either a stateless or a stateful channel to the OSE. Both a stateful and a stateless connection is opened by each httpd/mod_ose process started by the Apache listener, and the appropriate connection is used depending upon the requirements of the Web container object (servlet or JSP) and the HTTP client. The properties of the two connection types are:


Each httpd/mod_ose process keeps an Oracle Net connection open to the OSE server, and reuses this connection for HTTP clients and requests. The connection is permanently associated with a session in the OSE/OJVM server, so that a session gets serially reused by clients that are serviced by the corresponding Apache httpd/mod_ose process. In the stateless mode there are as many OSE connection/session pairs as there are httpd/mod_ose processes.


The OSE/OJVM associates a session, either an Oracle server or a data cache session, with each Apache client. Each OSE/OJVM session has a unique ID, which is sent back to the HTTP client in a cookie. The cookie is used to route further requests to the correct session. The stateful connection is kept according to the following criteria:

  • If KeepAlive (set by the HTTP client) is ON, then the stateful connection is kept open for the duration of the HTTP client.

  • If KeepAlive is OFF, then the stateful connection is closed after each client request.

In the current implementation routing only happens at connect time. This means that if you want to send a request to a particular session you must have a connection to this session. Because multiple requests from the same client can go to different Apache httpd/mod_ose processes, if stateful connections between mod_ose and the OSE server were kept open, the number of open connections could soon become excessive.

Servlet Access Using mod_ose

When the Apache listener receives an HTTP request from a client, it determines whether the request should be handled directly by Apache, or whether the request should be forwarded to a database server for processing.

The way the request is handled is determined by the total Apache configuration, both in the main Apache configuration file, which is ($APACHE_HOME/Apache/conf/httpds.conf), and in the mod_ose configuration file, which is located in $APACHE_HOME/modose/conf/, and is called ose.conf.


$APACHE_HOME on UNIX systems is normally $ORACLE_HOME/Apache. %APACHE_HOME% on Windows NT is %ORACLE_HOME%\Apache

Apache usually serves static Web pages from the file system on its host system. For example, the host is dlsun164, Apache is listening on port 7777, and a request arrives that is


In this case, there is no URI (URL-path, or information in the URL after the hostname and the port), so Apache serves its default static HTML page. The location and name of the default HTML page is set up in the Apache main configuration file, using the DirectoryIndex directive.

After you have installed and configured both the Oracle HTTP Server and mod_ose, an HTTP client can send requests to the HTTP server, and have them forwarded to the OSE/OJVM server. The client must know the port number that Apache is listening on, if it is different from the default port 80. For example, if the Oracle HTTP Server is running on the syhstem known as dlsun164, and is listening for incoming requests on port 7777, then it can process a request from an HTTP client with a URL such as


and serve the HTML page index.html, which is located in the document root of the Oracle HTTP server. Now, suppose that the HTTP client sends a URL such as


This request is sent on to the OSE/OJVM if mod_ose has been configured to have the OSE serve pages or programs where the URL-path is /ose/* (or, specifically, /ose/simpleServlet). This routing information is located in the mod_ose configuration file ose.conf.

The module configuration file contains entries (directives) of the form <Location>, which specify the service that handles requests to Java servlets or JavaServer Pages. For example, if the configuration file contains a Location entry with an Apache SetHandler directive:

  SetHandler aurora-service /ose/*

then all requests with the URL-path /ose/<any servlet name> are forwarded to the OSE/OJVM for processing. The OSE activates the servlet or JSP, and sends the servlet response object back to the HTTP client, through Apache. The httpd/mod_ose process does not process the servlet response, other than to perform de-chunking (see "Chunking").

You can find specific information on configuring the Apache listener (through the httpds.conf file) and mod_ose (through the ose.conf file) in Chapter 5, "Configuring mod_ose".

Secure Socket Layer Connection

You can use mod_ose for Secure Socket Layer (SSL) connections to the Oracle server. For instructions on configuring mod_ose for SSL, see "SSL Configuration".

HTTP Request and Response Processing

Processing the URL

When an HTTP request comes through Apache to mod_ose, the initial path information in the URL is discarded when the path is sent to the OSE/OJVM. This includes the protocol, Web domain, and port information.

Assume for example that Apache is listening on port 7777, and that the URL that Apache receives is


This request is forwarded to the OSE/OJVM whenever the ose.conf configuration file specifies Location and SetHandler Apache directives that configure URLs with /ose/ to go to the OSE. For example, the ose.conf file contains

<Location /ose/ >
  SetHandler aurora-server

In this case, all requests in which the URI starts with /ose/ are forwarded to the OSE for processing.

mod_ose strips off the protocol (http://), domain (dlsun164), and port (7777) information from the URL before forwarding it to the OSE.

After the servlet is executed, the servlet response is returned to the client. In general, the response is not altered by mod_ose or Apache. For one exception, see "Chunking".

In the preceding example, if the OSE finds a servlet context with the virtual path ose/, and a servlet with the virtual path simpleRequest, then the servlet with the virtual path simpleRequest is activated to process the request and send a response back to the client, through mod_ose and Apache. If the servlet context or servlet is not found, then the OSE sends back a 404 HTTP error. (Or, it might send back the contents of an error page that is application specific, depending upon how the application is configured in OSE.


The HTTP 1.1 specification mandates how a server should close or hold open a connection. Whether a connection is closed or held depends on the setting of KeepAlive (by the HTTP client) and ContentLength (set by the servlet in the setContentLength() method of the ServletResponse interface).

When a connection is closed, the client reads the response up to the EOF. However if a connection is kept open, the client must know how many bytes to read to get the entire response. The following conditions determine this:

However, a servlet might not set the content length parameter in its response to the client. Therefore, in order to keep stateless connections to the OSE database alive, mod_ose uses HTTP chunking for the responses from OSE to the Apache process. HTTP chunking is set by including the value "chunked" for transfer-encoding in the Transfer Encoding header field.

The responses are de-chunked before being passed to the client. A side-effect of this is that mod_ose always removes the content length header from the response, and so HTTP clients will disconnect the connection to Apache/mod_ose. This is not a major drawback, as most proxy servers, and most browsers, close connections by default after every request is processed.

For more technical information, see RFC 2616, section 3.6. This RFC is available at:

Session ID for Real Application Clusters

When a connection is being made through mod_ose to a specific instance in a cluster database, the JSESSION cookie ID that is transmitted in the cookie that OSE sends identifies the instance as well as the session. In this case an alphanumeric identifier for the instance is appended to the session ID, following a semicolon. For example


The AuroraLocationService Directive

mod_ose normally connects to a single OSE service. This is the service specified by the AuroraService statement in the ose.conf configuration file. For example, the entry

AuroraService inst1_http

in the ose.conf file names a connection identifier in the tnsnames.ora file that connects to a specific Oracle listener. This is so because the connect string that mod_ose uses has a PRESENTATION clause that is a global parameter, used by all mod_ose requests.

This can be a limitation in some contexts. There are occasions when it would be desirable to have instances of mod_ose in a single Oracle HTTP Server that can connect to, say, an administration service and an application service. Or there might be a standard TCP protocol specified in one connect descriptor, and a Secure Socket Layer (TCPS) protocol in another connect descriptor. Or, you might want to connect to a different port number. In each of these cases a different connection identifier is required in the tnsnames.ora file. As an example, the connection identifier inst1_http connects to a standard service, inst1_https connects to an SSL service, and inst1_httpAdmin directs connections on standard TCP/IP to an administrative service.

To get around this limitation, Oracle9i provides the AuroraLocationService directive. This directive is set in the Apache Location directive of the ose.conf configuration file, and can route HTTP requests to more than one service, based on the servlet context specified in the Location directive.

See "AuroraLocationService" for specific information about configuring the AuroraLocationService directive.


The AuroraLocationService directive is available only with the Oracle9i version of mod_ose

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.

You can create multi-node, in-tandem configurations. With these types of configuration, you can make a more scalable service than you can with OSE alone or with Apache alone. Before determining the number and types of server that your network requires, you should understand the basic configuration of the two servers: Apache and OSE. Figure 4-1 shows how the components relate.

With a multi-node server arrangement there is:

Since mod_ose works in a network in conjunction with Oracle Net, Oracle Net takes care of the fail-over and load balancing. The Oracle Net Administrator's Guide describes these provisions of Oracle Net.

Using mod_osso with mod_ose

HTTP security consists of two parts:


The process of determining the identity of an HTTP client making a request, and ensuring that the client really is who it claims to be. The simplest form of verification is asking a client for a password. Another type of authentication involves the client attaching a digital certificate to its request.


Enforcing the rules of access to different documents and applications on the Web server and servlet container. Authorization is based on information provided by a successful authentication step--the name of the client, also called the user or principal.

Oracle HTTP Server includes a module, mod_osso, that allows you to protect virtual paths on the server (authorization), while delegating the authentication step to the Oracle Single Sign-On Server (called the OSSO Server for short).

The basic function of mod_ose is to let the Oracle HTTP Server forward requests for certain virtual paths, so that they are actually executed by the OSE/OJVM.

It is possible to apply both mod_osso and mod_ose to the same virtual path. In Apache terminology this is described as chaining mod_ose after mod_osso.

For example, for a URL-path consisting of a servlet context virtual path plus a servlet virtual path, you can delegate user authentication to an OSSO server, check permission on a given virtual path for a particular authenticated user, and then forward the request to the OSE/OJVM for execution.

In this scheme, the advantages of Oracle Single Sign-On are preserved. That is, if the client authenticates successfully, it is not asked to repeat authentication for requests to other protected URLs in either the Oracle HTTP Server or in the OSE/OJVM, and the client credentials will be propagated to the OSE/OJVM for all requests that are forwarded there.

When mod_osso is part of the module chain forwarding requests, servlets are able to get the user name and a principal object using standard methods of the class javax.servlet.http.HttpServletRequest, namely getRemoteUser() and getUserPrincipal().

The values returned for these methods will be based on the user identity, which was established during successful Oracle Single Sign-On.

The Oracle HTTP Server provides directives for fine-grained authorization which is functionally very similar to the same HTTP security protections that are provided by the OSE. These directives may be used independently, or in conjunction with OSSO authentication. The set of virtual paths redirected to OSE is a subset of all virtual paths serviced by the Oracle HTTP Server, so the same paths can be protected by both mechanisms.

When regular HTTP security is used with the OSE/OJVM, the user identity is not known on the Apache front end, so the only way to define access control is by using OSE HTTP authorization. However when you use OSSO authentication the situation is different. A call to the OSSO Server happens on Apache, and the user is known after that. If an access control rule requires checking the user's membership in a group, that information also needs to be obtained from the OSSO server. So, all virtual path protection should be configured on the Apache node, and any configuration for contexts protected with OSSO that may exist on OSE will be ignored.

For information about configuring the mod_osso module, see "Configuring mod_osso". For more information about the Oracle Single Sign-On server, see the Oracle Single Sign-On Application Developer's Guide, part of the Oracle9i Internet Application Server documentation set.

Go to previous page Go to next page
Copyright © 1996-2001, Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Go To Product List
Book List
Go To Table Of Contents
Go To Index

Master Index