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

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.

Name the Oracle Net8 connection descriptor in tnsnames.ora as a pointer to the OSE service (see Example 5-1).
Generate a Web domain configuration file using the session shell command, exportwebdomain (see Example 5-2).
Include this generated configuration file in the Apache configuration file, httpd.conf (see Example 5-3).
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

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").

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

Enter:

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

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

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/Counter. mod_ose forwards the request as, /MyContexts/Counter, to OSE. If /Counter 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.

5Apache Module for Oracle OSE