| DBPrism Home Page | Documentation | Installing DBPrism on Cocoon2/OC4J/Linux: Introduction ....

Installing DBPrism/Cocoon2 on Linux

This This document is intended to give non-expert users (DBPrism, Cocoon, OC4J) a head-start, so they can see DBPrism/OC4J in action. Some text of this document is directly copied from the document OC4J.html, which was written by Marcelo F. Ochoa - mochoa@ieee.org, the creator of DBPrism.

This manual is not intended as a general installation guide for DBPrism: only use the versions of the software components as they are given below or you're in for a disappointment. The goal of this manual is to set up a working DBPrism configuration on a Linux machine as quickly and easily as possible. This means that certain things you might want (such as setting up new DADs) are outside the scope of this document. Refer to the standard DBPrism documentation for these topics. If you have comments/remarks, please email them to Roel Franken, rfranken@importalis.com, so that I can improve this document.

DBPrism is a servlet that can be used in two modes:

A mode emulating the Oracle Apache mod_plsql. This will allow you to execute stored procedures in the Oracle database through the DBPrism servlet.

A mode that makes DBPrism behave as an XML producer for Cocoon. Instead of outputting directly to the web-server, XML is directed towards Cocoon, using Cocoon as an XML publishing framework.

In this installation manual we will start to describe how the general components (such as Java) must be installed. Then the installation of each of these modes is described. .

Software Configuration

The installation described in this document is restricted to a particular configuration of software modules (in bold), which are defined in the table below:


Software	Version	Where to get it
DBPrism	2.0.0-alpha1	HERE
Cocoon	2.0	...from Apache.org: HERE
OC4J	1.0.2.2.1	...from Oracle Technet: HERE
Java Runtime Environment	Java(TM) 2 Runtime Environment, SE (build 1.3.1_02-b02)	...from Sun Corp: HERE
Linux Kernel	Linux 2.4.10-4GB	-
Oracle rdbms	8.1.7/9.0.x	...from Oracle Technet:
Apache	1.3.20	...from Apache.org

Note: For the software objects in bold, it is critical to select exactly the mentioned version. For instance, if you use Cocoon 2.0.1 this installation will fail! The installation of Linux and Oracle is outside the scope of this document. Also, this manual will not work with OC4J 2.0 (sorry!).

Preliminary Actions

It is wise not to install the DBPrism-components as user root. On a multi-user OS, such as Linux, create a user for running the OC4J container. In this installation manual the OS-user oracle is used (which comes pre-installed with the SUSE distribution), that has as its home directory /opt/oracle. (If you have to create the oracle account yourself, make sure it belongs to primary group oinstall, secondary dba).

Using DBPrism (in either mode) requires installing a number of general components. Apart from Linux (OS) and Oracle (rdbms), which are not described in this document, the following general software components must be installed:

a Java Runtime Environment (JRE)

The Oracle Container for Java (OC4J)

Apache webserver

Setting up the Java Runtime Environment

The Java distribution from Sun comes as a self-extracting BIN-file or a TAR-archive. Download the distribution (see " Table 1 : Software Configuration.") and install (as user oracle) it by following the instructions on: http://java.sun.com/j2se/1.3/install-linux-sdk.html.

In this example we install Java in /usr/local/jdk1.3.1_02.

If you want it there too and you 're using the BIN-file, do the following:

Log on as oracle

Download the BIN-file and put it in /usr/local

Extract. The directory jdk1.3.1_02 with subdirectories is created

Now modify the .profile file for the user oracle. By adding the following lines, the oracle user uses the correct JRE:


	PATH=/usr/local/jdk1.3.1_02/bin:$PATH JAVA_HOME=/usr/local/jdk1.3.1_02

Log on again or do a

oracle@linux:~>. ~/.profile

command to reload the profile settings.

Then issue the

oracle@linux:~>which java

command to verify the correct JRE settings.

The result should be:

/usr/local/jdk1.3.1_02/bin/java

Setting up the Apache webserver.

To check if the Apache webserver is running, load the following URL in the browser:

http://<your host>/index.html.en

If you see the test page then apache is running: go to step " Setting up the OC4J Servlet Container". If you don 't see the test page, this can mean any of the following:

That Apache is installed but not running

That Apache is not installed

To find out which of the two is the case, do the following:

Connect as root (by default Apache runs under the root user):

oracle@linux:~>su root

Issue the command:

linux:~ # apachectl

If you get an error like:

linux:~ # bash: apachectl: command not found

Then Apache is not installed and you have to install it from the Linux cdrom or download in from the site mentioned above. Refer to the documentation provided from Apache Org. to install it.

If you get the help information for apachectl, then apache is installed but not running. Start Apache by issuing the command:

linux:~ # apachectl start

Result:

/usr/sbin/apachectl start: httpd started

Setting up the OC4J Servlet Container

The Oracle9iAS new J2EE container, OC4J, is based on some technology licensed from Ironflare Corporation, which develops the OrionServer: one of the market's leading J2EE containers. This container is written entirely in Java that executes on the standard Java Development Kit (JDK) Virtual Machine (JVM).

Installing OC4J requires the following simple steps:

Unpack the distribution - unzipping the distribution file

Install - through the java virtual machine

Start OC4J

Unpacking the distribution

First, log on as the oracle user.

OC4J could be unpacked on any directory, but Oracle recommends installing into $ORACLE_HOME directory. If the oracle user does not have the $ORACLE_HOME set (check by using the set | more command) then add the following line to the .profile file: ORACLE_HOME=/opt/oracle and reload the profile settings as described above.

Now go to $ORACLE_HOME and create a directory oc4j:


	oracle@linux:~> cd $ORACLE_HOME oracle@linux:~> md oc4j oracle@linux:~> cd oc4j

and download the oc4j.zip from Oracle Technet into the directory /opt/oracle/oc4j.

After that:


	oracle@linux:~> ls -l /opt/oracle/oc4j totaal 9512 -r-xr-xr-x 1 oracle oinstall 9721825 jan 26 23:19 oc4j.zip

Then execute these commands:


	oracle@linux:~> cd $ORACLE_HOME oracle@linux:~> unzip /opt/oracle/oc4j/oc4j.zip

Result:

Archive: /opt/oracle/oc4j/oc4j.zip

creating: j2ee/home/
creating: j2ee/home/applications/
inflating: j2ee/home/applications/atm-install.txt
inflating: j2ee/home/applications/estore-bugs.txt
...
inflating: j2ee/home/jta.jar
inflating: j2ee/home/jndi.jar
inflating: j2ee/home/Readme.txt

Installing OC4J

Issue the command

oracle@linux:~> cd $ORACLE_HOME/j2ee/home

to go to the directory where OC4J was installed. Then issue:


	oracle@linux:~> java -jar orion.jar -install Enter an admin password to use: admin Confirm admin password: admin Installation done

Starting OC4J

Now that OC4J is installed, all you have to do is start it. Starting, Stopping and Re-starting is done by scripts. OC4J is operated through java -jar commands, but in many cases a shell or script is the best solution.

Here are scripts to use for these functions:

For starting OC4J:


	#!/bin/sh # Start script (start.sh) # adds path to java virtual machine executable file export JAVA_HOME=/usr/local/jdk1.3.1_02 export PATH=$JAVA_HOME/bin:$PATH java -jar orion.jar

Copy the above script, save it as start.sh in $ORACLE_HOME/j2ee/home and execute to start the OC4J container: oracle@linux:~/j2ee/home> sh start.sh

Result


	Oracle9iAS (1.0.2.2.1) Containers for J2EE initialized

Note: The OC4J application server listens on port 8888 by default.

For stopping OC4J:

#!/bin/sh
# Shutdown script (shutdown.sh)
# adds path to java virtual machine executable file
export PATH=/usr/local/jdk1.3.1_02/bin:$PATH
unset CLASSPATH
export CLASSPATH=
java -jar admin.jar ormi://localhost/ admin admin -shutdown

Restart script:

#!/bin/sh
# Restart script (restart.sh)
# adds path to java virtual machine executable file
export PATH=/usr/local/jdk1.3.1/bin:$PATH
# unset CLASSPATH
export CLASSPATH=
java -jar admin.jar ormi://localhost/ admin admin -restart

Configuring Apache to re-route to OC4J

Oracle recommend that you tunnel requests to the J2EE Container from Apache using mod_proxy. Although this is not necessary, it ensures that all pages that are served by the Oracle9i Application Server can benefit from other Oracle9i Application Server services--such as SSL and WebCache. This avoids wasting Java resources for serving static pages.

This is a simple step that could be done by adding these lines to Apache httpd.conf file:


	<IfModule mod_proxy.c> ProxyRequests On ProxyPass /dbprism/ http://<oc4j-host>:8888/dbprism ProxyPassReverse /dbprism/ http://<oc4j-host>:8888/dbprism/ </IfModule>

A more structured way is to create a file called oc4j.conf file with the above lines and to modify Apache httpd.conf with the line:

include "/u01/app/oracle/product/8.1.7/Apache/Apache/conf/oc4j.conf"

Setting up the MOD_PLSQL emulation mode

Now that the general components are set up, we can proceed with the installation of the MOD_PLSQL emulation. In this mode the DBPrism servlet is used to call stored procedures in the (Oracle) database and outputs the result directly to the webserver.

Installing DBPrism

Log on as oracle user if you hadn't already done so

Download DBPrism from the URL given at " Software Configuration".

Unpack the DBPrism distribution into directory /opt/dbprism.

Add the following lines to the .profile file:


	#Set PRISM home: PRISM_HOME=/opt/dbprism/

Reload the .profile file so these settings take effect.

Installing the /dpls zone

Creating the EAR file

From the installation directory, an EAR-file has to be generated for deployment on the OC4J application server. An EAR file is a JAR archive that contains a J2EE application.

Creating an EAR-file can be done easily with the script $PRISM_HOME/applications/build-dpls.sh that comes with the DBPrism installation , executing it from $PRISM_HOME/applications:

oracle@linux:/opt/dbprism/applications> . build-dpls.sh
Building dpls.ear using JAVA_HOME => /usr/local/jdk1.3.1_02 ....
Including last minute changes on Prism.jar
added manifest
adding: examples-jsp/(in = 0) (out= 0)(stored 0%)
adding: examples-jsp/demo.jsp(in = 352) (out= 219)(deflated 37%)
...

In the $PRISM_HOME/bin directory a file called dpls.ear has been created.

Copy this file to $ORACLE_HOME/j2ee/home/applications directory. In this EAR-file a version of DB Prism configured as IAS mod_plsql/OAS/OWS compatibility has been copied from the DBPrism installation. To avoid the problem of different configurations, it includes a private copy of prism.jar located (after deployment) on the $ORACLE_HOME/j2ee/home/applications/dpls/dpls/WEB-INF/lib directory and a private copy of prism.properties file located on $ORACLE_HOME/j2ee/home/applications/dpls/dpls directory.

Configuring the server.xml

First, start the OC4J server is it isn 't running.

The server.xml (in $ORACLE_HOME/j2ee/home/config/) contains the configuration for the OC4J application-server and (among other things) the paths to the libraries of the various applications deployed. So when we add the DBPrism application for the dpls zone, we must modify this file. Add the following lines:

Make sure you do not put this between the comment tags () in this file!

Now in the window running the OC4J server, you should see the following:


	Auto-unpacking /opt/oracle/j2ee/home/applications/dpls.ear... done. Auto-unpacking /opt/oracle/j2ee/home/applications/dpls/dpls.war... done. Auto-deploying dpls (New server version detected)...

The OC4J server has recognised the new application dpls.

Configuring the default-web-site.xml

The default-web-site.xml is located in the $ORACLE_HOME/j2ee/home/config directory. Add the following line:

<web-app application="dpls" name="dpls" root="/dpls" />

(Again: Make sure you do not put this between the comment tags.)

This line tells to OC4J server which directory is used as a mount point for this application

Installing a Database user for testing

This can be done in two ways:

Simple: just create one stored procedure containing HTP.P commands to check the installation of the dpls zone

Eleborate: Use the DBPRISM scripts to install the SCOTT account and test the demo?s

(You can do both of course)

A Simple Test

As Oracle DBA: Create a user prismtest on your target database.

Grant connect and resource to this user.

Connect as prismtest and execute the following (with SQL*Plus or another tool) :


	CREATE OR REPLACE PROCEDURE simple_test IS BEGIN htp.p('This is DBPrism. Connected as:'); htp.p(user); END simple_test;

Modify the prism.properties file located in $ORACLE_HOME/j2ee/home/applications/dpls/dpls directory:

Set the DAD for sample to the following settings:


	sample.dbusername=prismtest sample.dbpassword=<password for prismtest> sample.connectString=jdbc:oracle:thin:@<host>:<port>:<instance>

e.g.: sample.connectString=jdbc:oracle:thin:@localhost:1521:orcl

Now in your browser request:

http://<your_server>:8888/dpls/sample/prismtest.simple_test (of course, the " prismtest." is optional)

and you will see:


	This is DBPrism. Connected as: PRISMTEST

If you don't see this, try start and stop OC4J

A more elaborate test: The Prism Demos

Before you can test the demos for this zone, you must install the scott user in the target database by executing all the following SQL-scripts:

As dba: /opt/dbprism/plsql/scott.sql:creates user SCOTT with the necessary privileges

Connect as SCOTT and execute:

ALTER SESSION SET NLS_DATE_FORMAT = 'DD-MON-YY';

and

ALTER SESSION SET NLS_LANGUAGE=AMERICAN;

(Why? Because Oracle put dates in the summit2.sql script (see below) like '04-MAR-90 ' which might cause an error if your language is not American.)

Run summit2.sql: populates the SCOTT schema with the necessary tables etc. Comes with the database installation. Look for this script under $ORACLE_HOME on the database server (like ../RDBMS/demo).

Run /opt/dbprism/plsql/xtp.sql

Run /opt/dbprism/plsql/doctbl.sql

(there is an exit in this script, which is not nice)

Run /opt/dbprism/plsql/demo.sql

Run /opt/dbprism/plsql/show_open_sessions.prc

Run /opt/dbprism/plsql/show_open_cursors.prc

Modify the prism.properties file located on $ORACLE_HOME/j2ee/home/applications/dpls/dpls directory: Set the DAD for sample to the following settings:


	sample.dbusername=scott sample.dbpassword=tiger

Now in your browser request:

http://<your_server>:8888/dpls/sample/

and you will see the DBPrism Demo Page:

Demos Prism mod_plsql

Setting up the COCOON2 XML producer mode

Now that the /dpls zone is working correctly, we are going to set up the mode for communication with COCOON2. This means setting up a complete new application in the application server (OC4J), that is again copied from the DBPrism installation and deployed by means of an EAR-file.

Installing the correct JAR-files in the OC4J library

OC4J comes with JAR-files that are conflicting with the COCOON2 library. So in order to get Apache Cocoon running the JAR-files need to be reshuffled. Do this by executing the following:

Download and extract the COCOON2 distribution mentioned in the " Software Configuration" to /opt/cocoon/cocoon-2.0

Stop the OC4J server if it is running.

Remove the following files from the $ORACLE_HOME/j2ee/home directory:

jaxp.jar

crimsom.jar

parser.jar

Set Cocoon home by modifying the .profile file for the user oracle; add the following line: COCOON_HOME=/opt/cocoon/cocoon-2.0. And reload the .profile file.

Merge xerces-1.4.4.jar from the Cocoon distribution with xml-apis.jar into one file named xerces.jar. Do this by saving the following script as merge.sh:

echo "Merging Xerces and xml-apis jar..."
mkdir /tmp/xerces
cd /tmp/xerces
jar xvf $COCOON_HOME/lib/xerces-1.4.4.jar (the Cocoon2.0 version)
jar xvf $COCOON_HOME/lib/xml-apis.jar
jar cvf ../xerces.jar *

Run merge.sh. The result is a 940155 bytes in size xerces.jar on /tmp.

Copy this xerces.jar from /tmp to $ORACLE_HOME/j2ee/home/xerces.jar (remove old one first).

Copy xalan-2.2.0-D13.jar from cocoon/lib to $ORACLE_HOME/j2ee/home/xalan.jar (remove old one first)

Adding a new zone to OC4J

This involves the following steps:

Make an EAR file distribution

Edit the server.xml file

Edit the default-web-site.xml file

Make an EAR file distribution

As described in Creating the EAR file this is done by a script that comes with the installation. For the dbprism zone this script is called:

$PRISM_HOME/applications/build-dbprism.sh

Execute this script while on the $PRISM_HOME/applications directory. It will pack all files required by the zone. In the $PRISM_HOME/bin directory a file called dbprism.ear will be created.

Copy this file to $ORACLE_HOME/j2ee/home/applications.

This dbprism.ear file (like dpls.ear) includes a private copy of the prism.jar. It also includes a cocoon.jar which is based on COCOON2 and located in the $ORACLE_HOME/j2ee/home/applications/dbprism/dbprism/WEB-INF/lib directory and a private copy of prism.properties file located in $ORACLE_HOME/j2ee/home/applications/dbprism/dbprism.

Edit the server.xmlfile

(See:Configuring the server.xml)

Add the following line for the /dbprism zone:

Edit the default-web-site.xml file

(See:Configuring the default-web-site.xml)

Add the following line for the /dbprism zone:

<web-app application="dbprism" name="dbprism" root="/dbprism" />

Testing the DBPrism Cocoon interaction

To test the use of COCOON2 through DBPrism, start the OC4J server again; then in your browser request:

http://<your host>:8888/dbprism/ (Be patient because COCOON2 has to be compiled)

You should see the Cocoon welcome page.

If you want to test the DB Prism 2.0.0-alpha1 / Cocoon2 - Demos (top left corner) you have to install these demos first.

The Oracle IAS's mod_plsql support demo will work only if you have tested in the 'eleborate ' way. This because this sample uses the SCOTT user with the demo's installed.

For testing the DB Prism Java Stored Procedures support you will have to edit the prism.properties file on $ORACLE_HOME/j2ee/home/applications/dbprism/dbprism:

Change the XMLJ DAD:


	xmlj.connectString=jdbc:oracle:thin:@<db server>:<db port>:<db instance name>

If you installed the DEMO.SQL in another user 's schema you will also have to change the lines:


	xmlj.dbusername=<your demo user> xmlj.dbpassword=<your demo user?s password>

Problems you can run into

Here are some problems you can run into when testing the DBPrism modes:

Problem: When using DBPrism in the Cocoon-mode (mode 2), an error page is returned in the browser saying:


	type internal-server-error message The sitemap handler's sitemap is not available. Please check logs for the exact error.

Cause: You started OC4J in a session without a valid X server running (e.g. in a TELNET window on Windows).

Solution: start the OC4J server on an xterm. You could also use the Xvfb program. Install if necessary, start it:


	/usr/bin/X11/Xvfb :1 -screen 0 800x600x8& export DISPLAY=:1

Problem: When I try to run the simple example I see the following error:


	Servlet Wrapper Error Page I/O-exception: The Network Adapter could not establish the connection

Cause: You didn't specify the correct database server in prism.properties:


	sample.dbusername=<username for prismtest> sample.dbpassword=<password for prismtest> sample.connectString=jdbc:oracle:thin:@<your_host>:<your_port>:<your_instance>

Solution: Test <your_host> by pinging it from the machine that's running OC4J and then correct the prism.properties entry.

Problem: I get a PL/SQL error telling me ROWS_IN or ROWS_OUT is/are not defined

Cause: In the DAD the toolkit property is set to '3x ' while it should be '4x '.

Solution: Change it from '3x' to '4x'. (at present the default is '3x ')

Problem: When I execute the shutdown.sh script, the console window running the server says "Shutting down..." After that it hangs.

Cause: Cocoon2 does not shutdown gracefully on orions webservers (Orion and OC4J), this bug was corrected on the CVS (later) versions

Solution: Use shutdown with "force" option or you could use CTRL-C.