Zurück

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.

  • Java servlets without database access are stored in the filesystem and executed by the Oracle HTTP Server (Apache/Jserv).

References

[#]

Name of document

source

[1]

Oracle 9i Oracle Servlet Engine User’s Guide

http://tahiti.oracle.com

[2] Oracle 9i Java Developers Guide

[3]

Oracle Java Tools Reference

[4]

Java Naming and Directory Interface JNDI

http://java.sun.com/products/jndi/

[5]

Oracle 8i Database Access with Apache / Jserv

Apache / JServ

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

Fig2 Direct client access

Application Flow

The HTTP-Client sends an URL in the form:

http://<host>:<port>/<webservice>/<servlet>

to the listener port (endpoint). The listener forwards the request to the OSE, which reads the associated servlet context from the JNDI and executes the servlet.

An URL with a the pattern:

http://<host>:<port>/<webservice>/<html_page>

causes the OSE to read the HTML-page from the predefined OS-Directory.

Database Session

Each HTTP-Client request initiates the OSE to start a new DB session. The session runs in the context of the Web service owner. A DB session activates its own Java Virtual Machine (JVM). The JVM runs in the same address space as the SQL- and PLSQL-engine and provides therefore a faster access to database objects without additional login.

DB-Session termination is controlled by the use of a timeout parameter.

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

Fig3 Indirect access to the OSE over the Oracle HTTP Server

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

Servlets loaded and published in a JNDI servlet context can be configured to run either in stateful or in a stateless context. A stateful application tracks status information for all request-response sequences of a HTTP-client session. Cookies or URL-rewrites are the mechanism in charge. For details see [1].

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

#

Description

1

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

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

3

Calling a servlet in the servlet zone of the Oracle HTTP server (Apache).

4

Calling a servlet in the OSE over the Oracle HTTP server. The servlet reads the EMP table using the internal KPRB JDBC driver.

 

Platform

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

Server

  • OS RedHat Linux 7.2

  • Oracle Oracle9i Enterprise Edition Release 9.0.1

Client

  • OS Windows 2000

  • Oracle 8.1.7 / 9.0.1 Client

  • HTTP-Browser MS-Explorer 5.0

Windows 2000

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

 

Requirements

  • JServer installed in the Oracle database server. Make sure, that you have setup the following Shared and Java Pool to install the Java Development. After running the scripts initjvm.sql and init_jis.sql you may reset this parameters to smaller values.

# 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 HTTP server (is part of Oracle 9i) installed under:

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)

  • Start installation script:

ORACLE_HOME\javavm\install\init_jis.sql

  • Check and change if necessary the INIT-ORA-Parameter "mts_dispatchers"

mts_dispatchers="(PROTOCOL=tcp)"

DB-Restart (if changes occoured)

  • Check and grant if necessary (as user SYS)

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.

  • Create an OS directory e.g.

$ mkdir <DIR>/SougDemo/StaticPages/

  • Invoke the session shell tool

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

  • Create a Web domain. The option –docroot defines the path of static HTML pages

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

  • Create a context within the Web domain

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

  • Add a new endpoint to the listener

sess> addendpoint -port 7778 -register SougDemo SougEndpt01

  • Setup access rights for the new objects

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

  • Invoke SQL*Plus as User SYS

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.

  • Create and compile a Java servlet e.g

$ javac ReadEmployees.java

  • Load servlet in to the database

$ 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

  • Publish the servlet within the Web service
     
    Invoke the session shell tool:

$ 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

  • Check and change if necessary in File

$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

  • Check and change if necessary in Files

$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

  • Create a new configuration file sougdemojserv.properties by using:

$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"

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

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

  • /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