Akadia Information Technology

Karl Seematter, Akadia AG, Information Technology, CH-3604 Thun
Phone: +41 33 335 86 24 / Fax: +41 33 335 86 25 /
EMail: karl.seematter@akadia.com

Adapted to Oracle 9.0.1.2 / RedHat Linux 7.2 / Martin Zahn / 19.02.2002

Content

Part 1: Architecture

Introduction
References
Components
Terms
Access to OSE Servlets
Summary
Example Configuration

Part 2: Configuration and Installation

Configuration Steps
Summary of Examples
Platform
Requirements
Installation
Examples
Example 1
Example 2
Example 3
Example 4

Trobleshooting

Test all Examples here
Download all Configurationfiles and Examples here

Part 1: Architecture

Introduction

For internet applications with dynamic contents, more and more J2EE components (Servlets, JSP’s, EJB) come into operation.

With servlet based applications, the servlets are stored in the filesystem and accessed and executed by a web server with its servlet engine e.g. Apache / Jserv. For database access, methods like JDBC or SQLJ are used.

Oracle8i /9i brings some extensions in the area of server side Java programming. In this article we consider a configuration of a Web application where:

• Java servlets with database access are loaded into the database and executed by the Oracle Servlet Engine.

References

Components

All required components (Oracle HTTP Server , JRE, JDK, JSDK) are available with the Oracle 9i installations CD-ROM.

Terms

Oracle Servlet Engine OSE

See [1]

OSE is a built-in Web server with an integrated servlet engine running inside Oracle 9i. OSE executes Java Server Pages, Servlets and Java Stored Procedures.

Java Naming and Directory Interface JNDI

See [3] [4]

JNDI defines a hierarchical directory model for the administration of Web application objects (Servlets, initial parameters, JSP's etc.).

Access to the JNDI structure and its objects is permitted by a session shell tool called "sess_sh". The tool is driven by a command language similar to Unix. JNDI supports three type of access rights: READ, WRITE and EXECUTE.

Fig 1 Example: JNDI structure for a single domain Web service

• A Web service defines a root directory within the JNDI, the hierarchical directory structure and the stored objects for one ore more Web domains. OSE supports two different Web service configurations: single-domain and multi-domain.

Example (command within the session shell tool):

$ createwebservice -root /SougDemoRoot SougDemo

/SougDemoRoot: Name of the rootdirectory
SougDemo: Name of the Web service

In a single-domain Web service the Web domain corresponds to the root directory of the Web service.

• The Servletcontext - (part of) an application - contains servlets, configuration parameters and eventually pointers to static Web contents in the OS filesystem.

The hierarchical model represents a presentation layer and complies to the JNDI standard. In effect, directories and objects are stored in database tables.

• An Endpoint corresponds to a dynamic port in the listener for a Web service. The listener receives requests from a HTTP-Client or an external HTTP-Server and transfer them to the Web service or to the OSE respectively.

Example:

$ addendpoint -port 7778 -register SougDemo SougEndpt01

SougDemo: Name of the Web service
SougEndpt01: Name of the Endpoint

• The modul MOD_OSE is attached to the Oracle HTTP Server (use directive "LoadModule"). MOD_OSE serves as a conduit form the Oracle HTTP Server to OSE using Net8.

Access to OSE Servlets

Oracle8i OSE provides two different access methods:

1.)  Direct access from a HTTP-Client to the OSE

Application Flow

Database Session

2.) Indirect access over the Oracle HTTP-Server (Apache)

In this configuration the OSE serves as an additional servlet engine for the Oracle HTTP server. Servlets without database access are stored in the repository or in a servlet zone of the Apache Web server respectively (see [5]). Servlets with database access are loaded into the database. This architecture allows a flexible scalability for Web applications.

Application Flow

The Oracle HTTP-Server analyses a client-URL:

• If it contains a static page from the path indicated by the DOC_ROOT directive, this page is sent back to the caller
   

• If it contains a servlet zone, the request is forwarded to the MOD_JSERV module.
    

• If it contains a servlet context of an OSE-handler, the first part "http://<host>:<port>" of the URL is removed and the remaining part is transferred to MOD_OSE, which then connects to the OSE.

Remark:

A servlet context "SougDemo" is defined with the  following directive: (See Configurationfile: mod_ose.conf)

<Location /SougDemo/* >
   SetHandler aurora-server
</Location>

Stateful and Stateless Servlets in the OSE

Summary

Using the OSE for 3-tier applications offers additional scalability. Depending of its task, Java servlets can run either in the middle-tier or in the database server.

The administration of a Web service within the JNDI namespace is rather annoying!

Example Configuration

You will find running examples for the different access methods and step by step instructions for the configuration of the Oracle Servlet Engine, the Oracle HTTP Server (Apache/Jserv) and the particular examples.

Part 2: Configuration and Installation

Configuration Steps

• the Oracle Servlet Engine

• the Oracle HTTP-Server (Apache) with Jserv and MOD_OSE

• the different examples

Summary of Examples

Platform

These examples have been installed and configured on the following platform:

Server

Client

Windows 2000

We also installed, configured and successfully tested the whole application
on a Win 2K PC.

Requirements

# This are the normal parameters
# parallel_automatic_tuning = false
# shared_pool_size = 20000000

# This are the necessary parameters to setup
# the JAVA development

parallel_automatic_tuning = false
shared_pool_size = 200000000
java_pool_size = 100000000

Installscripts:

ORACLE_HOME\javavm\install\initjvm.sql

ORACLE_HOME/Apache

• Install correct JDK !

When you install the Oracle HTTP Server, you will be asked for the location of the JDK. This is usually not within the ORACLE_HOME path. We install the JDK in /usr/local/jdk. We noticed, that only JDK Version 1.3 works well.

4096 Jun 27 2001 j2sdk-1.3.1-FCS-linux-i386/
  26 Mar 8 22:25 java -> j2sdk-1.3.1-FCS-linux-i386/
  26 Mar 8 22:20 jdk -> j2sdk-1.3.1-FCS-linux-i386/
   7 Mar 7 13:59 jsdk -> JSDK2.0/
4096 Apr 21 1998 JSDK2.0/

Installation

Install Oracle Servlet Engine (OSE)

ORACLE_HOME\javavm\install\init_jis.sql

mts_dispatchers="(PROTOCOL=tcp)"

DB-Restart (if changes occoured)

GRANT JAVAUSERPRIV TO SCOTT;

Further Information

Additional information for the Java enviroment is provided under:

$ORACLE_HOME/javavm/readme.txt

Examples

Configuration steps for all examples, please take note of:

$     Unixprompt
sess> Prompt sess_sh tool
SQL>  SQL*PLUS Prompt
\     Line continuous character, not part of the command,
      copy all continuous lines in one single line.

Enable a Web service within the OSE

• Invoke the session shell tool on the database server

$ sess_sh -u sys/manager -role SYSDBA -s jdbc:oracle:oci8:@
--Session Shell--
--type "help" at the command line for help message

• Create a Web service and a root directory in the JNDI namespace

sess> createwebservice -root /SougDemoRoot SougDemo

• Change the owners from SYS to SCOTT

sess> chown -R SCOTT /SougDemoRoot

• Define access rights

sess> chmod -R +rwx SCOTT /SougDemoRoot

Example 1

Direct access from a HTTP client to the OSE, calling a static HTML page in the OS filesystem.

$ mkdir <DIR>/SougDemo/StaticPages/

$ sess_sh -u sys/manager -role SYSDBA -s jdbc:oracle:oci8:@

sess> createwebdomain -docroot <DIR>/SougDemo/StaticPages /SougDemoRoot

• Create a context within the Web domain

sess> createcontext -virtualpath /SougDemo -docroot <DIR>/SougDemo/StaticPages \
      /SougDemoRoot SougDemoContext

sess> addendpoint -port 7778 -register SougDemo SougEndpt01

sess> chmod -R +rwx SCOTT /SougDemoRoot
sess> exit

SQL> exec dbms_java.grant_permission (\
     'SCOTT','SYS:java.io.FilePermission',\
     '<DIR>/SougDemo/StaticPages/\
     example_1.html','read'
     );
     commit;

• Test example 1 with the URL

http//:<your_host>:7778/SougDemo/example_1.html

Example 2

Direct access from a HTTP client to a servlet in the OSE. The servlet reads the EMP table using the internal KPRB JDBC driver.

$ javac ReadEmployees.java

$ loadjava -verbose -u SCOTT/tiger ReadEmployees.class
arguments: '-verbose' '-u' 'SCOTT/tiger' 'ReadEmployees.class'
created :JAVA$CLASS$MD5$TABLE
creating : class ReadEmployees
created :CREATE$JAVA$LOB$TABLE
loading : class ReadEmployees

$ sess_sh -u sys/manager -role SYSDBA -s jdbc:oracle:oci8:@

sess> publishservlet -virtualpath \
      /Emp \
      /SougDemoRoot/contexts/SougDemoContext \
      ReadEmployees SCOTT:ReadEmployees
 
sess> chmod -R +rwx SCOTT /SougDemoRoot
 
sess> exit

• Test example 2 with the URL

http//:<your_host>:7778/SougDemo/Emp

Example 3

Calling a servlet in the servlet zone of the Oracle HTTP server.

Configure Apache/Jserv

$ORACLE_HOME/Apache/Apache/conf/httpd.conf
 
# Include JServ Module
include "/usr/oracle/product/9.0.1/Apache/Jserv/etc/jserv.conf"

# This port is used when starting without SSL
Port 7777

$ORACLE_HOME/Apache/Jserv/etc/jserv.conf
 
ApJServMount /SougdemoJserv /SougdemoJserv
 
$ORACLE_HOME/Apache/Jserv/etc/jserv.properties
 
# Servlet Zones parameters
zones=SougdemoJserv
...
SougdemoJserv.properties=<your_path> \
/Jserv/sougdemojserv.properties

$ORACLE_HOME/Apache/Jserv/etc/zone.propertes

as a template file and save it as:

<your_path>/Jserv/sougdemojserv.properties

# List of Repositories
repositories==<your_path>/Jserv

Create Servlet

Create and compile a Java servlet e.g.

$ javac HelloAkadia.java

and save it as

<your_path>/Jserv/

Start, stop resp. restart Oracle HTTP server in

$ORACLE_HOME/Apache/Apache/bin/

$ ./apachectl [start,stop,restart,...]

Test example 3 with the URL

http//:<your_host>:7777/SougdemoJserv/HelloAkadia

Example 4

Calling a servlet in the OSE over the Oracle HTTP Server (Apache). The servlet reads the EMP table using the internal KPRB JDBC driver.

For this example the same servlet is used as for example 2.

Configure Apache/OSE

Apache configurationfiles (Check and change if necessary)

• /opt/oracle/product/9.0.1/Apache/Apache/conf/httpd.conf

...
Port 7777
...
# Include the Oracle configuration file for custom settings
include "/opt/oracle/product/9.0.1/Apache/Apache/conf/oracle_apache.conf"

...
include "/opt/oracle/product/9.0.1/Apache/modose/conf/ose.conf"
...

LoadModule ose_module libexec/libjipa8i.so

#
# Apache configuration
# Domain: /webdomains
#
# o/p generated by
# exportwebdomain -format apache -netservice
# AuroraSrv1 -nodocs -nodefault /webdomains
#
<IfModule mod_ose.c>
 
  AuroraService AuroraSrv1
 
  #
  # Context for VPATH /SougDemo/
  #
 
  <Location /SougDemo/>
    AddHandler aurora-server snoop
  </Location>
 
  # SougDemo
  # * ==> all Servlets under /SougDemo
 
  <Location /SougDemo/*>
    SetHandler aurora-server
  </Location>
 
</IfModule>

Start stop resp. restart Oracle HTTP server

$ORACLE_HOME/Apache/Apache/bin/

$ ./apachectl [start,stop,restart,...]

Tnsnames.ora

Add the following entry to tnsnames.ora:

AuroraSrv1.world
  (DESCRIPTION = (ADDRESS = (COMMUNITY = tcp.world)
  (PROTOCOL = TCP) (Host = <your_host>) (Port = 1521))
  (CONNECT_DATA = (SID = <your_SID>)
    (GLOBAL_NAME = <your_SID>.world)
    (PRESENTATION = http://SougDemo)
    (SERVER = SHARED)))

Restart listener resp. reload config-file

$ lsnrctl
$ reload <your_listener>
$ exit

Add a new endpoint for the connection from Oracle HTTP Server to the OSE

Invoke the session shell tool

$ sess_sh -u sys/manager -role SYSDBA -s jdbc:oracle:oci8:@
 
sess> addendpoint -net8 -register SougDemo SougNet8Endpt01

Test example 4 with the URL

http//:<your_host>:7777/SougDemo/Emp

Notice that instead of port 7778 (direct access to the OSE ) port 7777 (access to the Oracle HTTP server) is used.

Troubleshooting

If you cannot connect to the example, then try the following

1. Shutdown the Database

2. Shutdown Listener

3. Shutdown Apache

4. Startup the Database

5. Startup Listener

6. Startup Apache