6
OracleJSP Migration

OracleJSP and Apache JServ are application platforms. They allow developers to customize the configuration to suit their applications. Unlike some tools included with Oracle9i Application Server, migration of JSP and servlet applications can be more complicated. It requires working knowledge of JavaServer Pages, the servlet API, Apache Web Server configuration, HTTP, and the applications that are being migrated.

This chapter explains the process of migrating JSP applications from OracleJSP version 1.0 (1.0.0.6.1) to 1.1 in Oracle9i Application Server 1.0.2.

Differences between OracleJSP 1.0 and 1.1

The following sections provide an overview of the differences between OracleJSP version 1.0 and version 1.1.

Functionality Differences

OracleJSP 1.1 is a Sun Microsystems JavaServer Pages 1.1 compliant implementation. It is different from OracleJSP 1.0 in the following ways:

It runs on servlet 2.0, 2.1, and 2.2 engines, while OracleJSP 1.0 runs only on servlet 2.0 and 2.1 engines.

Note:
For Oracle9i Application Server 1.0.2, the servlet.jar used in NEW_HOME/Apache/Jserv/etc/jserv.properties is a servlet 2.2 API jar. This jar is used by OracleJSP internally. However, please note that when you use Apache JServ to run your JSP application, you are still using a servlet 2.0 implementation.

It supports tag extensions in JSP 1.1 standard style.
It supports <jsp:param> in <jsp:include> and <jsp:forward>.
It supports the precompile option, as specified in the JSP 1.1 specification.
It supports <jsp:include> and <jsp:forward> tags on Apache JServ so you can include and forward to a static HTML file, not just to a JSP file.

Enhancements in OracleJSP 1.1 are backward compatible. You can migrate your JSP applications from OracleJSP 1.0 to OracleJSP 1.1 without any code changes.

Note:
There has been a change in the default value of a configuration parameter. In OracleJSP 1.0, alias_translation is by default true. In OracleJSP 1.1, alias_translation is by default false.

The Oracle9i Application Server 1.0.2 installation turns on the alias_translation parameter explicitly in NEW_HOME/Apache/JServ/etc/zone.properties with the following line:

servlet.oracle.jsp.JspServlet.initArgs=alias_translation=true

If you put your JSP files under an aliased directory, please remember to retain this option.

For details of OracleJSP functionality, please refer to Oracle JavaServer Pages Developer's Guide and Reference in the Oracle9i Application Server Documentation Library.

Installation and Configuration Differences

In Oracle Internet Application Server 1.0.0, all OracleJSP files are installed under the directory:

<OLD_HOME>/Apache/Ojsp

In Oracle9i Application Server 1.0.2, most of the OracleJSP files are installed under the directory:

<NEW_HOME>/jsp

while the file ojsp.conf is under the NEW_HOME/Apache/jsp/conf directory.

Also, Oracle9i Application Server 1.0.2 uses JDK 1.2. Therefore, the tools.jar from JDK is now included in the CLASSPATH for JSP javac compilation. Additionally, the JDBC and SQLJ related zip files used in jserv.properties are also updated to the versions that correspond to JDK 1.2.

Pre-migration

The following sections explain pre-migration steps. These instructions must be followed before beginning any migration work. Pre-migration consists of two steps:

Verifying the New Installation

Before you start any migration, you should first verify whether your new Oracle9i Application Server 1.0.2 installation is working correctly. To verify that OracleJSP 1.1 has been installed correctly, perform these steps:

Navigate to the default home page of your new installation. There you see a list of links for the different components.
Click the OracleJSP samples link to see a list of OracleJSP samples, and select a sample to test.

Most of the samples should work without extra configuration changes or deployment steps, except for the CORBA and EJB samples. These two samples require you to first deploy the corresponding CORBA and EJB components.

The OracleJSP samples which work without extra configuration changes include:

basic	sql
custom tags	OracleJSP extensions
XML

Some samples require that you have a database up and running.

After you have verified that OracleJSP has been installed correctly, you are ready to back up your configuration files.

Backing Up Configuration Files

Before making any changes to the configuration files, you should back up all the configuration files in your new installation that you are going to change. Then, if you make a mistake during migration, you can restore the old configuration files and perform the migration steps again.

Typically, the following files are changed when you migrate your JSP and servlet applications after installing Oracle9i Application Server 1.0.2:

<NEW_HOME>/Apache/Apache/conf/httpd.conf
<NEW_HOME>/Apache/Jserv/etc/jserv.conf
<NEW_HOME>/Apache/JServ/etc/jserv.properties
<NEW_HOME>/Apache/JServ/etc/zone.properties
<NEW_HOME>/Apache/jsp/conf/ojsp.conf

Most of these configuration files of the old installation should be just under the directory with the same path under OLD_HOME. For example, jserv.conf should be in OLD_HOME/Apache/JServ/etc/jserv.conf, if the files have not been moved.

Note:
The default location of ojsp.conf in the old installation is slightly different. It is under the directory: OLD_HOME/Apache/Ojsp/conf/.

Environment

No environment migration tasks are necessary.

Configuration

Anyone performing the OracleJSP 1.1 migration should have working knowledge of the applications and the JSP/servlet environment. First, you must identify what environment settings are made by the Oracle9i Application Server 1.0.2 installation and what environment settings are used for your applications.

JSP Environment

The environment settings typically used include (but are not limited to) those listed in Table 6-1:

Table 6-1 Environment Variables and Settings for OracleJSP 1.1

Variable	Setting
PATH	specified in wrapper.env in jserv.properties
CLASSPATH	specified in wrapper.classpath entries in jserv.properties
LD_LIBRARY_PATH	specified in wrapper.env entry in jserv. properties
any alias directories settings	specified in your httpd.conf
any web resource protection settings	specified in your httpd.conf

Oracle9i Application Server 1.0.2 Installation Configuration Changes

After backing up the configuration files, we recommend that you compare the old with the new configuration files using a tool like the diff command. Check the differences line-by-line to determine whether the difference is due to the new Oracle9i Application Server 1.0.2 installation or it is due to prior configuration customizations. If the difference in configuration settings is required for an application, then apply the changes to the new configuration.

Examples of changes in the new Oracle9i Application Server 1.0.2 installation include (but are not limited to):

the JDK has been switched from 1.1 to 1.2
tools.jar has been added for javac compilation
the version of servlet.jar has been changed from 2.1 to 2.2
the version of ojsp.jar has been changed from 1.0 to 1.1
ojsputil.jar has been added for supporting JavaBeans and custom tag libraries
the version of zip files for SQLJ and JDBC drivers has been changed from 8.1.6 to 8.1.7 and from JDK 1.1 to JDK 1.2, respectively

Keep these changes in your new configuration because they provide faster performance and a richer set of functionality for your JSP applications.

General Guideline

Follow these steps as a general guideline for applying changes to the new configuration files:

Add changes batch-by-batch. If you make a small number of changes and check your work before making further changes, then it is easier to locate errors.
Restart your Oracle9i Application Server machine after you have made a batch of changes.
Verify whether your changes work in the new installation by checking that you can run the OracleJSP samples.

If everything works correctly after you apply a batch of changes, then continue to apply your next batch of changes.

Note:
In most cases, you do not need to remove or comment out any lines in the new configuration files. If you need to, then remove configuration lines after you have made your additions and have verified the new configuration.

After you have applied all the necessary changes, copy your JSP files and class files to the right locations. Then you can test whether your application runs on the new server.

For general troubleshooting, see the Oracle JavaServer Pages Developer's Guide and Reference and other Oracle reference manuals in the Oracle9i Application Server Documentation Library.

Application Logic

OracleJSP 1.1 provides a very good backward compatibility with 1.0. Therefore, you do not need to change your JSP source code to run it on OracleJSP 1.1.

However, the new version of OracleJSP uses Java 1.2. Since your existing applications use Java 1.1.8, you will need to recompile all JSP pages to fully utilize the benefits of Java 1.2.

OracleJSP 1.1 supports a JSP 1.1 standard runtime tag extension mechanism. If you are using JML tags from OracleJSP 1.0, then we suggest that you migrate tags in your JSP files from the OracleJSP 1.0 compile time mechanism to the new runtime version.

For more information, see the Oracle JavaServer Pages Developer's Guide and Reference in the Oracle9i Application Server Documentation Library.

Tools

OracleJSP 1.1 has an updated ojspc, the OracleJSP translator command line tool found in ORACLE_HOME/bin. It allows you to compile JSP files in the file system without a web server. In OracleJSP 1.1, this tool has a few new options, and the name of the option -includePath has been changed to -appRoot.