Apache/JServ on NT

1. DBPrism Installation and Configuration On NT

Intent

Simply put the aim was to produce a set of instructions that not only configured prism but educated the installer.

Mostly of all a set of instructions that helped people set up DB Prism (prism for short) with no prior knowledge of Apache, Jserv etc. (If like me your background is oracle development, then the initial learning curve can be fairly steep.) This is NOT to say that Prism environment is harder to understand/install than OAS - but Prism requires numerous 'steps' its not a one step installation.

Why jserv, well when I started out using earlier versions of Prism (OWSKiller), jserv was one of the options, over the next year or so I expect TomCat to replace jserv, but it works. It should work with any servlet engine, even OAS's!

I have excluded cocoon and xml generation, simply to keep it simple stupid KISS.
I have added this toward the end

At the end of these instructions you will have a working web server supporting servlets, and prism configured so that you can generate html pages using pl/sql.

I keep an updated version of these with the zone files etc at http://www.telecomrg.com/darylcollins so they can be downloaded and maybe help get people up and running faster

Overview

2. Overview

There are numerous ways to configure the web server, jserv and oracle database, just so I dont go insane, Im putting them all on the same box, an NT machine. The configuration parts should apply across platforms but the install is different, check the install instructions for each platform.

At the time of writing Apache on NT is not considered to be stable/secure enough for production use, the intent here is not to configure a production server but a sand box for experimentation. See the apache documentation about the release of Apache on NT.
This DOES NOT mean that Apache will crash every 2 minutes, in fact I've never seen that happen in well over a year - the apache authors realize that the NT version is just not (yet) up to the high standards of apache variants on Unix.

There are other servlet engines you could use, with various web servers, but I'm not going there. I'm not going to open the can of worms that is the install of an Oracle database (others have done this) I am assuming that this has been done.

The configuration I used is as follows

Pentium III 600 MHz , 128 MB RAM (IBM Think Pad)
Oracle 8.05 installed on drive D:/orant instance name ORCL
Apache 1.3.12
Jserv 1.1
JSDK 2.0
JDK 1.1.8.003
Prism 1.0.0

We will go through the install of each component, addressing downloads, installation and configuration for each.

Why are there so many components?

Well Apache is the web server, Jserv is the servlet engine, the jsdk and jdk cannot under Suns java license be released with jserv, so we need to install them to allow the servlet engine to work JDK - Java Developers Kit JSDK - Java Servlet Developers Kit.
And last but not least Prism, which is the servlet that allows html/xml to be generated from the database using pl/sql (ie the pl/sql cartridge replacement).

3. Installation

3.1 Apache

First things first we need a web server and Apache aint a bad one (maybe the best)

3.1.1

Download Apache from http://www.apache.org/ (Get the latest stable version when these instructions where written 1.3.12 was the latest stable release. With later versions there may be differences in paths and install procedures.)

3.1.2

This is a self extracting exe

3.1.3

The instructions assume this goes in c:\program files\apache group\apache. Select typical install accepting all defaults and this will be done automatically
In fact these instructions will put all the software under c:\program files\apache group\ in various directories. This DOES NOT have to be the case, you can install the software anywhere you want. Of course following these instructions may get a little fuzzy if you choose not too.

3.1.4

Notable files c:\program files\apache group\apache\conf\httpd.conf - this is the apache configuration file, its very well documented. c:\program files\apache group\apache\logs\errors.log - this is the apache error log - useful for debugging problems later.

3.1.5

Did It Work?

There should be a program group 'Apache Web Server' with a start/stop apache icon. Start Apache, a dos window should open, kick off a browser and goto url http://127.0.0.1/ You should see an html page saying
'If you can see this, it means that the installation of the Apache web server software on this system was successful. You may now add content to this directory and replace this page.' Along with other things - if you want to change things go read the documentation, follow the link at the bottom of the page You may as well stop apache now, as we will have to restart it again soon, use stop apache from the 'Apache Web Server' Group

3.2 JDK

3.2.1

Download jdk (java developers kit) http://java.sun.com/

3.2.2

This is self extracting, accept all the defaults except for the install directory

3.2.3

The instructions assume this goes in C:\program files\apache group\jdk1.1.8 again this could be anywhere you want

3.3. JSDK

3.3.1

Download JSDK (Java Servlet Development Kit) from http://java.sun.com/

Use 2.0, 2.1 will not work according to the apache jserv documentation, this is subject to changes for later versions

3.3.2

Download JSDK (Java Servlet Development Kit) from http://java.sun.com/

3.3.3

The instructions assume this goes in c:\program files\apache group\JSDK2.0

3.4 Apache JSERV

3.4.1

Download Apache jserv from http://www.apache.org/

3.4.2

This is self extracting, accept all the defaults except for the install directory

3.4.3

The instructions assume this goes in c:\program files\apache group\Apache JServ 1.1, again this could be anywhere you want

3.4.4

You will be prompted for the location of the following files ' The java virtual machine' ie where is the java.exe? c:\program files\apache group\jdk1.1.8\bin ' The directory JSDK 2.0 is installed in ' ie where is jsdk.jar c:\program files\apache group\jsdk2.0\lib You will be asked if you want to modify the apache httpd.conf file, select yes, this modifies the apache httpd.conf file to kick off jserv when apache is brought up. You will be asked for the location of the httpd.conf file. c:\program files\apache group\apache\conf

3.4.5

Notable Files Apache Jserv extends the apache conf file with
# Include the configuration for Apache JServ 1.1 Include "c:\program files\apache group\Apache JServ 1.1\conf\jserv.conf"
The contents of jserv.conf are included into the httpd.conf (using the include directive, this is why the jserv install asked you for the location of httpd.conf file). This separates the jserv directives (in c:\program files\apache group\Apache JServ 1.1\conf\jserv.conf) from the apache directives. We will return here as we need to configure jserv

3.4.6

Did jserv install OK? Start Apache, kick off a browser and goto url http://127.0.0.1/jserv/ Keep the trailing slash. You should see an html jserv configuration page

4. Review

4.1

So far we have a working web server with a servlet engine - now lets discuss the basic ideas and concepts before moving on to configuration

4.2 Zones

There's some documentation about zones on the apache pages. Basically each zone gets mounted by jserv, each zone is a collection of servlets(or just one servlet). The zones are configured to execute the servlet when a request is made and return (at least in our case) html. Our zone will be configured to execute Prism, Prism executes the pl/sql and returns the html generated by it. Easy? Prism also has a configuration file.

4.2.1 Summary

jserv, configured to mount zones
zone, configured to execute Prism servlet
Prism, configured to connect to database

At first it appears to be confusing, but the architecture if flexible and versatile. We will configure each file as needed. Once you have been through a few configurations it becomes much easier, as your understanding grows it becomes a breeze. Remember when we started the instructions where written to get you up and running without having to load OAS, (since you will probably need to buy more RAM or upgrade NT to the correct service pack, or like many just give up).

4.3 Requests

When an http request is serviced, apache would normally return and html file, no mystery here. When a request is made to access a servlet, apache passes the request onto jserv (apache gets configured to do this) jserv accesses the servlet (jserv is configured to do this). When the request is made for a pl/sql procedure, all the above happens the servlet - prism - executes the pl/sql (prism is configured to do this) and returns html. Voila!
Browser <--> Apache <--> Jserv <--> Prism <--> PL/SQL

5. Configuration

Lets assume I want to set up an url that looks like this http://127.0.0.1/dev/plsql/hw, where hw is the name of a stored procedure (ah familiar territory for those coming from the oracle database world)

5.1 Configure Apache

Leave httpd.conf alone there is no need to add any configuration data here. Just needed to mention it the documentation is very extensive. (and you have the documentation installed for both apache and jserv locally)

5.2 Configure Jserv

5.2.1

We need to modify jserv.conf (sometimes called mod_jserv.conf depending on your platform) to mount the zones we require (the jserv.conf file contains directives to the httpd processes (ie apache) on how to handle the requests. So when we configure jserv.conf we are in fact configuring apache on how to process certain requests.

5.2.2

This is an extension of mapping virtual paths to actual physical directories, or executing cgi scripts or processing files of a certain extension in a particular way (.xml for example). For jserv apache passes the request to the servlet engine.

5.2.3

Edit the file c:\program files\apache group\Apache JServ 1.1\conf\jserv.conf, find the directive ApjServMount there could be 2 zones already mounted for demos


	ApJServMount /servlets /root ApJServMount /servlet /root

Replace these lines with


	#ApJServMount /servlets /root #ApJServMount /servlet /root ApjServMount /dev /devzone

You do not need to comment out the root zone demo servlet and servlets, but KISS again
This tells apache that requests to /dev/***** should be passed to jserv

5.3 Configure Servlet Engine

Edit the file c:\program files\apache group\Apache JServ 1.1\conf\jserv.properties

5.3.1

This file has a number of notable lines
The following lines tell jserv where the jre is


	wrapper.bin=c:\program files\apache group\jdk1.1.8\bin\java.exe

The following lines tell jserv about needed jar files namely


	wrapper.classpath=c:\program files\apache group\Apache JServ 1.1\ApacheJServ.jar wrapper.classpath=c:\program files\apache group\jsdk2.0\lib\jsdk.jar

Now you know why the installation kept prompting us for directories, it did some configuration for us. Its the same as a class path environment variable
You can add additional jars and zip files as needed.

Any jar or zip added here will be available to all zones, there is a way, as we will see later to add jar files for specific zones. Does it matter? Well yes from a security standpoint but also from a development standpoint. Any jar added here will be loaded once on startup of apache, if we add the jar to the zone it is reloaded when changed. Not a big deal on your own machine but something to keep in mind for later.

5.3.2 Add jdbc drivers

Just under the line


	wrapper.classpath=c:\program files\apache group\jsdk2.0\lib\jsdk.jar

add the lines

oracle jdbc drivers the oracle home is on drive D NOT C - wherever your classess111.zip file is


	wrapper.classpath=d:\ORANT\jdbc\lib\classes111.zip

Notice we have not added the Prism.jar file we will do that in the zone.

5.3.3 Declare our zones

Find the line


	zones=root

and replace it with (to declare a zone names devzone)


	#zones=root zones=devzone

So now the servlet engine (jserv) knows all about our zones, no wait there is more, each zone has a configuration

5.3.4 Zone configuration files

Find the line


	root.properties=c:\program files\apache group\Apache JServ 1.1\servlets\zone.properties

and replace it with (to tell Jserv how to configure the devzone)


	#root.properties=c:\program files\apache group\Apache JServ 1.1\servlets\zone.properties devzone.properties=c:\program files\apache group\Apache JServ 1.1\servlets\dev.properties

5.4 Zone configuration

Copy


	c:\program files\apache group\prism\conf\zone.properties


	c:\program files\apache group\Apache JServ 1.1\servlets\dev.properties

Why bother to copy the files, 2 reasons, first Id like a clean copy of those distributed so when we go edit them we can always go back to a known starting point and secondly it keeps all the properties files in the same directory. As you become more proficient at the configuration you will see that its fairly flexible and you can come up with your own directory structures for conf files.

Edit the file c:\program files\apache group\Apache JServ 1.1\servlets\dev.properties replace the lines


	repositories=/usr/local/prism/bin/Prism.jar,/usr/local/Cocoon/bin/cocoon.jar with repositories=c:\program files\apache group\prism\bin\prism.jar

This tells the zone to use the prism jar file
Also find the lines (at the bottom)

servlet.plsql.initArgs=properties=/usr/local/prism/conf/prism.properties
servlet.demo.initArgs=properties=/usr/local/prism/conf/prism.properties
servlet.xml.initArgs=properties=/usr/local/Cocoon/conf/cocoon.properties
servlet.xmld.initArgs=properties=/usr/local/Cocoon/conf/cocoon.properties
and replace them with
servlet.plsql.initArgs=properties=c:\program files\apache group\Apache JServ 1.1\servlets\devprism.properties
#servlet.demo.initArgs=properties=/usr/local/prism/conf/prism.properties
#servlet.xml.initArgs=properties=/usr/local/Cocoon/conf/cocoon.properties
#servlet.xmld.initArgs=properties=/usr/local/Cocoon/conf/cocoon.properties

Here I remove some examples that come with Prism, KISS again

5.5 Prism - finally we get there

5.5.1

Copy c:\program files\apache group\prism\conf\prism.properties to c:\program files\apache group\Apache JServ 1.1\servlets\devprism.properties, remember in dev.properties we pointed to this file.

5.5.2

Edit c:\program files\apache group\Apache JServ 1.1\servlets\devprism.properties
Find the following


	global.webmaster=mochoa@ieee.org

Change the email address please. This is used by Prism to display an email address in the event of an error in a procedure call.

Connection string
Find the line

plsql.connectString=jdbc:oracle:thin:@cobra:1521:OI
The connectString is used to tell Prism how to go connect to the DB in the following format
plsql.connectString=jdbc:oracle:thin:@<Server Name>:<TNS Listener Port>:<Instance Name>
try
plsql.connectString=jdbc:oracle:thin:@127.0.0.1:1521:ORCL

jdbc driver


	plsql.compat=8i replace it with plsql.compat=7x

If you are using db and jdbc drivers prior to 8.1 otherwise leave it alone

Authentication options
Find the line


	plsql.DynamicLogin=false replace it with plsql.DynamicLogin=true

This will require you to enter the database username and password for the user whos procedure you are going to execute

Other configuration directives


	plsql.toolkit=3x - use this if you have the 3.x pl/sql toolkit plsql.toolkit=4x - use this if you have the 4.x pl/sql toolkit

5.6 PL/SQL Install

Its is assumed that the pl/sql toolkit is installed, if you dont have a copy go look its all over the web, once is at Search for XML Toolkit

5.6.1

We need one additional package, execute
c:\program files\apache group\prism\plsql\myows.sql
If you are using synonyms create a synonym.

5.6.2

As an oracle user in sql*Plus enter


	create procedure HW as begin htp.p('Hello Non OAS World!'); end;

5.6.3

Start Apache (database and tns listener should already be up and running) and goto http://127.0.0.1/dev/plsql/hw

5.7 When things do not work

Check the various log files for error messages Sign up on the OWSKiller (aka Prism) mailing list at http://owskiller.penguin.cz/

5.8 Cocoon set up

5.8.1

Download latest cocoon release from http://xml.apache.org/

5.8.2

At the time of writing 1.7.3 was the latest, unzip the file to c:\program files\apache group\cocoon-1.7.3

5.8.3

Edit the file c:\program files\apache group\Apache JServ 1.1\conf\jserv.conf, find the line


	#ApJServAction .xml /dev/org.apache.cocoon.Cocoon

Add the following lines


	Action cocoon /dev/org.apache.cocoon.Cocoon AddHandler cocoon xml Alias /xsl/ "C:/Program Files/Apache Group/prism/xsl/"

The first part tells apache to let cocoon handle all processing for files with the extension xml, the second part is a virtual path mapping to the xsl style sheets used in the demo (the demo you are about to add)

5.8.4

Edit the file c:\program files\apache group\Apache JServ 1.1\conf\jserv.properties, add the following lines

wrapper.classpath=c:\program files\apache group\cocoon-1.7.3\bin\cocoon.jar
wrapper.classpath=c:\program files\apache group\cocoon-1.7.3\lib\xerces_1_0_3.jar
wrapper.classpath=c:\program files\apache group\cocoon-1.7.3\lib\xalan_1_0_1.jar
wrapper.classpath=c:\program files\apache group\cocoon-1.7.3\lib\fop_0_12_1.jar

The numbers 1_0_3.jar etc change with different cocoon releases

5.8.5

Edit the file c:\program files\apache group\cocoon-1.7.3\conf\cocoon.properties, add the following lines


##########################################
# Prism DB Producer params
# properties.plsql must be point to corrected prism.properties file !!!
##########################################
producer.type.db = com.prism.CocoonWrapper
producer.properties.db = c:\program files\apache group\Apache JServ 1.1\servlets\devprism.properties

##########################################
# Header Processor, set this to work with cookies, redirect url and dymamic login
##########################################
processor.type.http = com.prism.HeaderProcessor

##########################################
# Prism Excel Formatter, simple formatter to generate Excel output see PLSQL demo source for details of usage
##########################################
formatter.type.application/vnd.ms-excel = org.apache.cocoon.formatter.TextFormatter
formatter.application/vnd.ms-excel.MIME-type = application/vnd.ms-excel

# Logic Sheet for XSPConnectionWrapper
processor.xsp.logicsheet.connection.java = resource://com/prism/xsp/connection.xsl

5.8.6

Edit the file c:\program files\apache group\Apache JServ 1.1\servlets\dev.properties, Find the line


	#servlet.org.apache.cocoon.Cocoon.initArgs=properties=/usr/local/Cocoon/conf/cocoon.properties

replace it with


	# Do not break this line servlet.org.apache.cocoon.Cocoon.initArgs=properties= c:\program files\apache group\Apache JServ 1.1\servlets\cocoon.properties

Find the line


	servlet.plsql.code=com.prism.ServletWrapper

Add


	servlet.demo.code=com.prism.ServletWrapper servlet.xml.code=org.apache.cocoon.Cocoon servlet.xmld.code=org.apache.cocoon.Cocoon

Find the line


	servlet.plsql.initArgs=properties=c:\program files\apache group\Apache JServ 1.1\servlets\devprism.properties

Add

servlet.demo.initArgs=properties=c:\program files\apache group\Apache JServ 1.1\servlets\devprism.properties
servlet.xml.initArgs=properties=c:\program files\apache group\Apache JServ 1.1\servlets\cocoon.properties
servlet.xmld.initArgs=properties=c:\program files\apache group\Apache JServ 1.1\servlets\cocoon.properties

All we did here was set up demo, xml and xmld all used in the demo (the demo we will finally get to)

5.8.7

Edit the file c:\program files\apache group\Apache JServ 1.1\servlets\devprism.properties, Find the line


	global.alias=plsql

Replace it with


	global.alias=plsql demo xml xmld org.apache.cocoon.Cocoon

Set up 'DADs' for demo, xml and xmld (simply copy all the lines for plsql)

5.8.8

Edit c:\program files\apache group\prism\plsql\demo_bdy.sql
At the end of the file replace package initialization part with (this should have changed at prism version 1.0.1)
BEGIN
url_server := 'http://127.0.0.1';
END demo;

also replace /servlets/ with /dev/ - this needs to be done throughout the file.
Remember we never set up servlets as a zone dev was used as our mount point. I do this because I frankly feel there is something confused about calling a servlet zone servlets.

5.8.9

Log into sql (same user used to add HW procedure)
run the following scripts found in the c:\program files\apache group\prism\plsql directory

xtp.sql
or xtp_public.sql for OAS/IAS/Web DB Toolkits

demo.sql

You will also need to have the demo tables added s_inventory etc. These normally come with oracle (oci directory in a file summit2.sql) if not goto http://www.telecomrg.com/darylcollins/ get the file and run it

5.8.10

Check cocoon installed correctly
Copy the directory c:\program files\apache group\cocoon-1.7.3\samples to c:\program files\apache group\apache\htdocs\samples
Start apache
Goto http://127.0.0.1/Cocoon.xml - general status page
Goto http://127.0.0.1/samples/index.html - lots of cocoon examples
Goto http://127.0.0.1/dev/demo/demo.startup - lots of cocoon examples with prism and db connections

6. Credits

Since I wrote these instructions oracle have announced iAS and apache based web server. OK short of going on a rant here Ill let it go at this. Oracle web development strategy has been a mess from day one (iAS is an admission that OAS/WAS did not work) Its still a mess - I prefer to focus on delivering high quality web based applications than attempting to figure out Oracles strategy du jour. Prism/apache/cocoon are all open source projects, while at first it may be a little unnerving to use these tools`- they have one saving grace - they work and if you get involved you can help shape their future directions and development. The other option, get dragged around by the nose by Oracle. You have a choice.

Michael Hagan for the feedback through all versions of the instructions (his idea to write it up)
Gary Wong being the inspiration for rewriting the instructions, and for pointing out numerous holes
Marcelo F.Ochoa for helping and explaining stuff when I cant figure it out
If you find anything wrong let me know

ToDo List

Use TomCat not jserv