Configuration for Session Persistence

Many application servers have the ability to store user sessions while a web app is offline, for example when changing JasperReports Server configuration files. The app server remembers all the information about a user's session, such as the session ID and what page was being viewed, and when the web app restarts, the user session is restored. The user does not have to log in again, and often will not even notice that the server was temporarily unavailable. This is called session persistence.

Sessions are not persisted when redeploying a web app in the application server, only when restarting the web app.

JasperReports Server supports a limited form of session persistence. When session persistence in enabled in the app server for JasperReports Server, user sessions can be restored in the following cases:

Browsing the repository, expanding folders in the repository tree and viewing folder contents.
Searching the repository, including all search filters and results.
Repository permissions dialog, including state and selections.
Add folder dialog.
Add resource dialogs, including adding or editing a data source, JasperReport, and other repository objects.
Copy, cut, and pasting resources in the repository.
Scheduling a report, including all information such as a schedule and notifications.

If the server becomes unavailable when using the pages or dialogs above, the user will see a pause only when performing an action on these pages, such as submitting. When the server has finished restarting, the user can continue interacting with these pages or dialogs. If the user does not perform any action while the server is unavailable, he may not even notice that there was a failure.

However, for other interactive dialogs in JasperReports Server, the state is too large to store in the user session. The following features do not support session persistence:

Ad Hoc editor - The state of the report layout and data in the Ad Hoc editor cannot be restored, so any unsaved changes are lost.
Dashboard designer - The contents and state of the canvas cannot be restored, so any unsaved changes are lost.
Interactive report viewer - The data in the report, as well as the state of column sorting and filtering cannot be saved, so any unsaved changes are lost.
Domain designer - Any tables, joins, filters, calculated fields, and display names cannot be restored, and so any unsaved changes are lost.
OLAP viewer - The data in the OLAP view and current MDX expression cannot be restored, so any unsaved changes would need to be created again.
Administration dialogs (when creating or editing an organization, user, or role) - The information entered in an administration dialog cannot be restored if it was not submitted.

In the cases listed above, the user's work is interrupted, and any unsaved work is lost. However, when the server restarts, the user does not have to log in again, the server displays a message about the session that could not be fully restored, and the server redirects the user to the home page. The user must relaunch the interactive feature and recreate any unsaved work.

Session persistence also affects web service calls. The REST API supports a login to store a session ID, and with persistence enabled, that session ID will still be valid when the application server restarts. This simplifies the code you need to handle timeouts. In general, web service calls do not support interactive work such as designing an Ad Hoc view, a dashboard, a Domain, or exploring data in OLAP, so they are not affected by the lack of session persistence in those cases. However, web service calls are affected in the following case:

Report execution - All asynchronous API calls for running and exporting reports rely on the large JasperPrint object that cannot be persisted. When the server restarts, the asynchronous calls will return errors because the reports could not be saved in the session. Your application needs to detect this error and include code for re-running the report.

JasperReports Server also supports session replication between multiple instances of the server in a cluster. However, session replication has the same limitations because it is based on session persistence. For more information, see the JasperReports Server Ultimate Guide.

The following procedure gives the configuration in JasperReports Server and the Apache Tomcat application server to enable session persistence. For other application servers, refer to that server's documentation.

To configure JasperReports Server and Apache Tomcat for session persistence:

1. Edit the file <web-app>/META-INF/context.xml to comment out the Manager property as follows:
<!-- Manager pathname="" /-->
2. Edit the file <web-app>/WEB-INF/web.xml to make the following changes.
a. Locate the listener of class RequestContextListener and replace it with the listener of class TolerantRequestContextListener. The new listener class is given in comments that you need to uncomment as follows:
b. Locate the ClusterFilter that is given in comments and uncomment it as follows:
c. Locate the corresponding mapping for the ClusterFilter and uncomment it as well. You must also uncomment the <distributable> element below it as follows:
3. Add the following property to your JVM environment:
4. Restart your Apache Tomcat application server.