Microsystems Technology Laboratories > OpenCoral

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

Overview of Upgrade Process

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.

One of the reasons that we suggest that you go to the process of preserving the existing Coral xReporter installation, instead of simply wiping it out and starting fresh, is that it insures that any local changes that you have made, but not checked into the repository, will be preserved. This is particularly important if you have either created any new reports or modified any of the standard reports locally.

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.
During this process xReporter will be unavailable to your Coral users (although Coral itself will be fully available and functional during this time). As a result, it is recommended that this upgrade be scheduled at a time when you expect light demand for xReporter. In particular, you will likely want to avoid the end-of-month accounting period. Although others may find differently, we believe that this upgrade process should take no more than 2 hours. If this is not your experience, please let us know so that we can either improve our documentation, resolve problems, or at least make our estimates more realistic.

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.

In the following sections, I've assumed that xReporter is owned and being installed by the coral user and that the coral-xr source files live in the ~coral/coral-xr directory. Furthermore, I've assumed that versions of Tomcat and Phoenix have been (for the existing versions) and will be (for the new versions) installed in /usr/local. If these do no match the ownership or install directories that you use, you will need to make appropriate changes to some of the listed commands.

Shutting Down the Existing Version of xReporter

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.

Preseving the Existing Version of xReporter

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
We have now made is possible to install the xreporter and xreporter-cocoon packages in the coral-xr directory (rather than, by default, at the same level as the coral-xr directory). This makes the entire coral-xr installation more self contained as everything lives in the coral-xr directory. In this case, you will want to check "ant configure". You likely specified that the xReporter Home and xReporter-cocoon Home properties are "../xreporter" and "../xreporter-cocoon", respectively. If you do not adjust these now, they will stay as you originally specified them. We now recommend that these be set to "./xreporter" and ".xreporter-cocoon" respectively to achieve this improved packaging.

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:

The following command likely only works for a default Linux installation. If you have httpd installed on elsewhere or if you are running under Solaris, the directory in which mod_jk.so is located will likely differ. You may be able to easily find where this is by looking for the httpd_module_dir property in your original coral-xr configuration file which at this point should be ~coral/xreporter-j2sdk1.4.2/coral-xr/conf/${site}-prod.properties.
# 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.

Installing JDK 1.5.0

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.

Depending on your installation style, you can actually "pre-install" JDK 1.5.0, and then "activate" it by making the appropriate links. For example, if you use the Linux "package" install of a JDK, it is tpically installed in a directory named something like /usr/java/j2sdk1.4.2_12 or /usr/java/jdk1.5.0_14. We typically create a symbolic link named /usr/j2se that points to the current version and then make sure that our JAVA_HOME environment variable is set to /usr/j2se and that $JAVA_HOME/bin is in our PATH environment variable. If this is your approach, you can pre-install a version of JDK 1.5.0 even though you are still running J2SDK 1.4.2 and then simply "activate" it at this point by removing the symbolic link named /usr/j2se that points to /usr/java/j2sdk1.4.2_12, for example, and create a new link named /usr/j2se that points to /usr/java/jdk1.5.0_14.

Required Database Changes

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)

Configuring and Installing the New Version of xReporter

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.