Factors to consider when upgrading

Introduction

Setting up a server environment in production usually involves customizations and configurations that need to be taken into account when doing an upgrade.

In general, doing custom software not based on API's is high risk, since the underlying server code may change from version to version, which could force you to refactor that custom code for the new server version.

Of medium risk are changes to JSP pages. JSP pages don't change that much from version to version (aside from the UI changes in 4.0), but you'll still need to be careful. The least risky changes are changes made to configuration files (such as jasperreports.properties and others), since they are just property files that drive the server's behavior and don't change much from version to version.

Categories

The most typical customization topics include:

• SSO
• Software Customization
  • Engine level (e.g., State Street's "service engine", etc)
  • UI Customization (Themes, Flows, Chart Customizers)
  • Changes to JSP files (landing pages after login, decorators, etc)
  • Additional values in properties files (jasperreports.properties, virtualizer settings, other properties files under WEB-INF directory)
  • Modifications to the JasperReports Library
  • Development of customized web services
• Custom Datasources (and associated Spring configuration files)
• Other layers of the software stack (databases, operating systems, JVM, web servers, etc)
• Documentation - you have a detailed list and a procedure for installing customizations and other modifications to JRS.

SSO

The security framework that ships with JasperReports Server changed from using Acegi Security in 3.5.1 to using Spring Security 2.0 in version 3.7. Consequently, if there is custom software that uses Acegi, it will break in newer versions of the server, and that code will have to be refactored.

If there's a straightforward configuration you applied from the Authentication cookbook (such as enabling LDAP authentication), you'll have to follow re-apply those configuration settings in the new server version's Spring configuration file; this is less risky than doing actual custom software.

Software Customizations

Engine-level customizations

These are the most delicate, because the server code these customizations are based on changes from server version to server version. Since they are not going through API's, there is no guarantee that the custom software would even compile, much less work properly.

UI Customizations

Themes were introduced in version 4.0, so if you're upgrading from that version to a newer version, you should not encounter problems at this level. Themes are stored in the repository, so by simply exporting and importing the repository, you'll get the themes you defined.

Flow files are XML files you find under /jasperserver-pro/WEB-INF/flows, so if there are changes you've made there, they should port without a problem.

Chart customizers, which involve custom Java code packed up in JAR files, should port as well.

JSP file customization

These are low-to-medium level of complexity, should be fairly straightforward to port. The big changes happened from version 3.7.1 to 4.0, so customizations done in 3.7.1 that you wish to bring over to version 4.0+ will need a little bit more work.

Modified properties files

These changes include modified version of jasperreports.properties, ehcache.xml, log4j.properties and other files you may have changed on your old server version. It's usually enough to just apply the same modifications from your old server to your new server.

Modifying the JasperReports Library

The JasperReports library is open source, and from time to time, customers with deep technical knowledge and expertise modify the underlying library on which the server is based. This is a really deep, fundamental change to the lowest level of functionality that we don't recommend and that clients take at their own peril. The same caveats that we mentioned for engine-level customizations apply here.

Custom Datasources

Porting custom datasources from one environment to another is of medium risk. Custom datasources involve the development of custom software and configuring Spring files. What makes it less risky than pure custom software development is that custom datasources use API's that won't change (The nitty-gritty is that they are JAVA classes that implement interfaces for datasources, query executers and executer factories, and these interfaces will not change).

Other layers of the software stack

Since JasperReports Server is one element within its software stack, we need to take into account changes you may have done outside of JasperReports Server. This includes web servers, databases, operating systems, and JVM settings.

You can check which product versions work best with JasperReports Server by checking your version's Supported Platforms sheet, which you can find here: http://www.jaspersoft.com/supported-platforms.

Web Servers

This is typically the least problematic element in the software stack, but properties to remember include any global timeout settings you may defined for your old server environment as well as defining concurrent user settings.

Application Servers

Settings that have an impact here include the size of the database connection pool and the number of threads available to JasperReports Server. Make sure to look what your old server's settings are.

Java Virtual Machine

The JVM settings are usually defined in the application server's startup script, so make sure to note what they are there in your old server environment. If you use the default settings for the JVM, you'll get lower memory settings, which would impact performance.

Databases

Beyond just making sure that you're using a supported database, make sure to optimize it in the same way you may have done with another database. It's also easy to forget about the database driver, so take care to use the most current driver, and work back from there if you're not getting the performance you want.

Process for upgrading

To get a good sense of how challenging an upgrade can be, you can try doing it yourself on a test environment. You should then be able to tell what parts, if any, broke during the upgrade. By listing the parts that broke, you can get a sense of the level of effort needed to do the upgrade.