Upgrading From a J2SDK1.4.2-compatible to a JDK1.5.0-compatible Verion of xReporter

This document describes the process of upgrading xReporter from the original version that ran under J2SDK1.4.2 to the version that runs under JDK1.5.0 (AKA J2SE 5.0). Because this process involves not only upgrades to the JDK, but also requires new versions of xReporter (including both the xreporter and xreporter-cocoon sub-projects), as well as new versions of Tomcat, Cocoon, and Phoenix, it is a more involved process than that associated with a conventional "cvs upgrade". In particular, we will do our best to insure that we cleanly separate the two versions both so that we can insure that the new version does not contain any vestiges of the old version and so that, if there is a problem, we can revert to the original version in reasonably quick fashion.

The process of upgrading from the original J2SDK1.4.2 version of xReporter and the newer JDK1.5.0 version of xReporter basically invovles the following key steps:

• Stopping the running versions of Tomcat and Phoenix
• Preserving the existing versions of Tomcat, Cocoon, Phoenix, coral-xr, xreporter, and xreporter-cocoon. Not only will this allow us to revert to this version, if required, but it eliminates the chance that we get a mixture of the old and new versions of any of these components which would almost certainly result in failure.
• Installing an appropriate version of the Java Development Kit and insuring that this version will be used in the build and installation of the new version of coral-xr and its associated pieces.
• Making a comaratively minor change to the rpt_roles table (owned by database user rptmgr) that is required by changes in the way that newer versions of Tomcat (either version 5.5 or 6.0) authenticate users.
• Downloading, configuring, building, installing, and testing the new version of xReporter and its associated components. This will include new versions of coral-xr, xreporter, xreporter-cocoon, tomcat, cocoon, phoenix, and tomcat-connectors.

Details of this process are included in the following sections. It is recommended that you read through this document to familiarize yourself with the process before you actually begin the upgrade.

When you are ready to upgrade from a J2SDK1.4.2-compatible version of xReporter to the JDK1.5.0-compatible version, the first requirement is to stop the existing versions of Tomcat and Phoenix. Failure to stop these now is likely to cause difficulties when you try to start and test the newly-installed version.

Because the phoenix and tomcat process are owned by Coral, they can be stopped by either the coral user or by root.

If you are running as user coral, you can stop the existing versions Phoenix and Tomcat and then confirm that they have been stopped by issuing the commands:

# /usr/local/phoenix/bin/phoenix.sh stop
# ps -ef | grep [p]hoenix
# /usr/local/tomcat4/bin/shutown.sh
# ps -ef | grep [t]tomcat

Alternatively, if you are running as the root user, you can stop the existing versions Phoenix and Tomcat and then confirm that they have been stopped by issuing the commands:

# /etc/init.d/phoenix stop
# ps -ef | grep [p]hoenix
# /etc/init.d/tomcat4 stop
# ps -ef | grep [t]tomcat

At this point, xReporter will be unavailable for use.

The coral-xr module (that is, the Coral-specific version of xReporter) makes used of several directories that constitute the "source files" of the xReporter install, as well as several installed directories. In the following section we will name those directories with their default names. If you have chosen different names or locations during your install of coral-xr and xReporter, you will need to change these names accordingly.

By default, we assume that you have downloaded the original coral-xr module into the ~coral home directory. If that is the case, then you will have 3 directories that consitute the xReporter source files located in ~coral/coral-xr, ~coral/xreporter and ~coral/xreporter-cocoon. We will preseve those directories by issuing the following commands as the coral user (assuming, of course, that you have installed coral-xr as the coral user):

# mkdir ~coral/xreporter-j2sdk1.4.2
# mv ~coral/coral-xr ~coral/xreporter-j2sdk1.4.2
# mv ~coral/xreporter ~coral/xreporter-j2sdk1.4.2
# mv ~coral/xreporter-cocoon ~coral/xreporter-j2sdk1.4.2

Next, we need to make sure that we are able to install and run the new versions of Tomcat, Cocoon, and Phoenix without confusing them with the old versions. The original version of Cocoon is installed within the original version of Tomcat, so we don't have to do anything special to it. You should have a symbolic link named /usr/local/phoenix that points to the actual installed version of Phoenix in /usr/local/phoenix-4.0.4. Similarly, you should have a symbolic link named /usr/local/tomcat4 that points to the installed version of Tomcat 4 in /usr/local/jakarta-tomcat-4.1.31. We may make room for our new installation, by simply removing the two link (but keeping the installed versions of Tomcat and Phoenix) by issuing the following commands as the root user:

# rm /usr/local/phoenix
# rm /usr/local/tomcat4

Next we need to make sure that the init.d scripts that start and stop Phoenix and Tomcat are appropriately disabled to make way for the init.d scripts that will start and stop the new versions of Phoenix and Tomcat. We will do this by issuing the following commands as root to remove the links in the various /etc/rc?.d directories that point to /etc/init.d/phoenix and /etc/init.d/tomcat4 and then by renaming the /etc/init.d/phoenix script as /etc/init.d/phoenix.orig.

# rm /etc/rc?.d/S*phoenix
# rm /etc/rc?.d/K*phoenix
# rm /etc/rc?.d/S*tomcat4
# rm /etc/rc?.d/K*tomcat4
# mv /etc/init.d/phoenix /etc/init.d/phoenix.orig

Finally, we need to remove the original version of the Tomcat Connector (mod_jk.so) to make room for the new version. This can be done by issuing the following command as root:

# rm /etc/httpd/modules/mod_jk.so

At this point you should have successfully moved the existing versions of Tomcat, Phoenix, and Cocoon out of the way in preparation for installing, configuring, and setting up the new installlation.

At this point, you need to either install JDK 1.5.0 on this machine or, if it is already installed, but not in use, make changes so that this becomes the version of Java that is used for the compilation and running of the new version of xReporter. Instructions for installing Java and setting up the appropriate JAVA_HOME environment variables and PATH variables is covered in Section Install and Configure OpenCoral Prerequisites. You should check this by insuring that the commands "which java" and "java -version" a pointing the the appropriate version of JDK 1.5.0.

Newer versions of Tomcat (specifically Tomcat 5.5 and 6.0) no longer allows role-based authentication to make use of the "*" (that is, any role) option. In particular, we must now make sure that every legitimate Coral user has been given a specific role. We will make use of the role named "active". However, because we do not wish to update our rpt_role table each time a new member is added to the Coral system, we alter the definition of the rpt_role table (which is a "view" of other tables. so that it defines the role of "active" for all active members.

If you are running a Postgresql database you should issue the following command as the rptmgr database user:

CREATE OR REPLACE VIEW rpt_role (name, role) AS
(SELECT name, 'active' FROM rscmgr.member WHERE active = 1
UNION SELECT member, role FROM rscmgr.lab_role WHERE active = 1
UNION SELECT member, role FROM rscmgr.project_role WHERE active = 1
UNION SELECT member, role FROM rscmgr.account_role WHERE active = 1);

If you are running the Oracle databse, the command is essentially the same with the addition of the "WITH read only" clause at the end:

CREATE OR REPLACE VIEW rpt_role (name, role) AS
(SELECT name, 'active' FROM rscmgr.member WHERE active = 1
UNION SELECT member, role FROM rscmgr.lab_role WHERE active = 1
UNION SELECT member, role FROM rscmgr.project_role WHERE active = 1
UNION SELECT member, role FROM rscmgr.account_role WHERE active = 1)
WITH READ ONLY;

At this point, you have moved all of the original J2SDK1.4.2-compatible components of xReporter out of the way and may follow the instructions in Section Install and Configure OpenCoral xReporter. When you configure the new version, you will want to make sure that you all of the JDK1.5.0-compatible versions of xreporter, xreporter-cocoon, phoenix, tomcat, cocoon, and jakarta connectors. Specifically those versions should be selected from the pulldown menus during the "ant configure" step:

• xReporter Revision: 1_3 (or newer)
• xReporter-cocoon Revision: 1_3 (or newer)
• Tomcat version: apache-tomcat-5.5.23 or apache-tomcat-6.0.14 (or newer). Note: if you have no explicit reason for running Tomcat 5.5, we recommend that you select Tomcat 6.0 as this is the version that is currently under primary development and support at Apache.
• Cocoon version: cocoon-2.1.10 (or newer)
• Phoenix version: phoenix-4.0.4-tiger. Note: in this case both choices are version 4.0.4. However, the JDK1.5.0-compatible version has the "-tiger" extension because JDK1.5.0 was internally named "tiger" at Sun.
• Jakarta Connectors version: tomcat-connectors-1.2.25 (or newer)

If your new installation was successful, you can then start the new Coral-specific version of xReporter by following the instructions in Section Start and Stop OpenCoral xReporter. Should you encounter problems, and wish to revert to the old J2SDK1.4.2-compatible version, you should be able reserve the things that you did to preserve the original version of xReporter outlined earlier in this section.