Upgrading JasperReports Server 3.1 to 3.5 For Tomcat + Oracle + Linux

Introduction

When a new JasperReports Server version is released, customers typically want to upgrade to the new version in order to have the latest bug fixes and the newest features.

While the upgrade process is documented in the JasperServer-Install_Guide.pdf that comes with the new release, this tutorial is more narrowly focused on the Oracle database, the Linux operating system, and the Tomcat application server.

Product Version

This tutorial works with version 3.0 and 3.1, upgrading to version 3.5.

Objectives

This guide will enable you to:

Pre-upgrade Steps
Upgrade Steps
Post-upgrade Steps
- Login to JasperReports Server
- Troubleshooting

Pre-Requisites

Users should have JasperReports Server 3.1 or 3.0 installed under Linux using the Oracle 10.x or 11.x database and Tomcat 5.5 or 6.x.

Assumption: This tutorial uses Tomcat as the example application server.

If you have an application server other than Tomcat you can still use this tutorial.
Substitute your application server's specific information when doing the application server portion of the upgrade steps.

Pre-Upgrade Steps

Note on JasperReports Server 3.0: There were no database changes between JasperReports Server 3.0 and 3.1. Therefore, this upgrade procedure works for upgrades that start with either version.

Handling Customizations:

If you made modifications or customizations to your JasperReports Server 3.0 or 3.1 application, these configurations are typically found in the WEB-INF/applicationContext-*.xml set of files.
Configuration modifications such as client specific security classes or LDAP server configurations need to be hand copied from the older 3.0 or 3.1 environment and re-integrated into the new 3.5 environment.
Running diffs between the files will help highlight your local customizations.

Backing Up Database

Follow these steps for an Oracle JasperReports Server database backup.

Step	Action
1	Shutdown your JasperReports Server Application Server instance (or make sure that user activity is read-only)
2	Login to a shell account on a machine where you can run the Oracle client/DBA utilities.
3	Run the datapump utility, which is available on Oracle 10 and 11.
4	As DBA admin, create a location for the backup. a. sqlplus /nolog b. Make sure the directory pointed to below exists on the Oracle server: SQL> connect sys as sysdba Enter password: Connected.SQL>CREATE DIRECTORY dmpdir AS '/opt/oracle'; SQL>GRANT read, write ON DIRECTORY dmpdir TO jasperserver; c. Exit sqlplus. d. Do the datadump export: expdp jasperserver/password DIRECTORY=dmpdir DUMPFILE=jasperserver_31.dmp *Note*: For additional reference: view the Oracle Datapump Wiki site.

Backing Up JasperReports Server WAR File

Follow these steps to save off the 3.1 jasperserver-pro war file(s).

Step	Action
1	The jasperserver-pro war file is typically deployed as a directory, so move and rename this directory. Login to your application server machine.
2	Shutdown your application server
3	cd
4	mkdir js-3.1-war-backup mv {apache-tomcat}/webapps/jasperserver-pro to {apache-tomcat}/js-3.1-war-backup

Exporting Your 3.1 Data

Follow these steps to export your current 3.1 repository data (also known as repository resources) from JasperReports Server. We use the JasperReports Server Export utility which is a java program.

First configure the export utility for the Oracle database. You will go to your 3.1 installation directory, called: {js-install-3.1}

Step	Action
1	cd {js-install-3.1}/scripts/config
2	Edit the js.jdbc.properties file. Set the properties to the following Oracle settings:
3	Make sure the following items in bold are correct for your instance: jdbc:oracle:thin:@localhost:1521:orcl jasperserver password *Note:* You can cut and paste from the following file to avoid typing errors: {js-install-3.1}/scripts/oracle/js-jdbc-oracle.properties
4	Copy the Oracle database driver to the {js-install-3.1}/scripts/lib directory. Copy from one of the following locations: {js-install-3.1}/scripts/drivers/ojdbc14.jar {js-install-3.1}/auto-install-scripts/conf_source/db/oracle/jdbc/ojdbc14-10.2.0.jar cp {js-install-3.1}/scripts/drivers/ojdbc14.jar {js-install-3.1}/scripts/lib *Note: By default, the Oracle driver is already in place {js-install-3.1}/scripts/lib/ojdbc14.jar*
5	Now, run the export command: cd {js-install-3.1}/scripts ./js-export.sh --everything --output-zip js-3.1-export.zip

Downloading the 3.5 WAR File Distribution

Follow these steps to download the 3.5 WAR File distribution.

Step

Action

Download the folder: jasperserver-pro-3.5-bin.zip.

Unzip this file into a convenient location. For instance:

cd /home/username

unzip jasperserver-pro-3.5-bin.zip
This location will now be known as: {js-install-3.5} {js-install-3.5}

Upgrade Steps

Configuring for Upgrade

The JasperReports Server download contains a set of scripts known as the “Buildomatic” scripts. These scripts use the Apache Ant tool to automatically configure all the settings you need for Tomcat and Oracle; all that is required is to configure a single property file.

Step	Action
1	Make sure your application server is shutdown.
2	Copy sample property file to current directory and rename it to default_master.properties: cd /buildomatic cp sample_conf/oracle_master.properties default_master.properties
3	Edit the default_master.properties file. The settings below are examples, update items in bold to match your settings: *Note*: Be careful to make sure there are no additional spaces at the end of lines.

Copying js-3.1-export.zip to Buildomatic

Locate the js-3.1-export.zip that you created in earlier steps, in your new {js-install-3.5} directory for convenience.

Step	Action
1	cd {js-install-3.5}/buildomatic
2	cp {js-install-3.1}/scripts/js-3.1-export.zip