|Oracle9i Servlet Engine Developer's Guide
Release 1 (9.0.1)
Part Number A90213-02
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
http://httpd.apache.org/ 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.
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.
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.
Figure 4-1 shows how the Web server and the
httpd/mod_ose processes relate to the OSE/OJVM.
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
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:
mod_solibrary must be installed in the Oracle HTTP Server, or there must be other equivalent support for Dynamic Shared Objects (
mod_so.cis compiled into the Oracle HTTP Server by default)
mod_mimemust be installed in the Oracle HTTP Server
mod_ossoto use with
mod_ose(see "Using mod_osso with mod_ose")
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.
mod_ose, see Chapter 5, "Configuring mod_ose".
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 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:
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:
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.
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
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
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
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
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".
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".
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
SetHandler Apache directives that configure URLs with
/ose/ to go to the OSE. For example, the
ose.conf file contains
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
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:
KeepAliveis OFF, the servlet engine always closes the connection. In this case, the client can read all the data in the response, up until EOF is detected.
KeepAliveis ON and the
ContentLengthof the response is set by the servlet, the connection is kept open.
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:
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
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
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
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
See "AuroraLocationService" for specific information about configuring the
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:
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.
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_ose to the same virtual path. In Apache terminology this is described as chaining
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.
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
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.