Some of the new and enhanced features in JasperReports Server 4.7, 5.0, and 5.6 can affect your deployment and you should plan your upgrade accordingly. Prior to upgrading to you should make sure to:
| • | Review this information carefully and determine how the changes described affect your deployment. |
| • | Make sure to back up your current JasperReports Server installation and repository before upgrading. |
The versions and their affected functionality are as follows:
| • | Changes in 5.6 affect XML/A connections. |
| • | Changes in 5.0 affect XML/A connections and deployments with custom settings. |
| • | Changes in 4.7 affect deployments with theme customizations. In addition, if you enable the data snapshot functionality added in 4.7, size requirements for your repository may increase. |
Changes are cumulative, so review all topics that affect you. For example, if you are upgrading from 4.7 to 6.0, you may be affected by changes in 5.0 and 5.6.
This section describes only those changes that can significantly impact your existing deployment. For an overview of new features, improvements, and bug fixes see the release notes in the root directory of the distribution. For information on how to use the new features, see the JasperReports Server User Guide or the JasperReports Server Administrator Guide.
This chapter contains the following sections:
| • | Changes in 5.6 That May Affect Your Upgrade |
| • | Changes in 5.0 That May Affect Your Upgrade |
| • | Changes in 4.7 That May Affect Your Upgrade |
Changes in 5.6 That May Affect Your Upgrade
The following changes in 5.6 and newer can significantly affect your deployment:
| • | Changes to OLAP engine: Due to change between version of the OLAP engine, if you use Jaspersoft OLAP’s XML/A functionality to connect to a remote JasperReports Server’s XML/A sources, you must take additional steps to complete your upgrade to 5.6. |
Changes to OLAP Engine
If you use Jaspersoft OLAP’s XML/A functionality to connect to a remote JasperReports Server’s XML/A sources, you must take additional steps to complete your upgrade to 5.6. This is due to a change between versions of the OLAP engine.
Once the new version of JasperReports Server is installed and running, locate all the XML/A connections that point to a remote JasperReports Server instance. Then, edit the DataSource field to specify JRS as the DataSource portion of its value.
For example, in previous versions, the Foodmart XML/A connection specified:
Provider=Mondrian;DataSource=Foodmart;
During upgrade, this connection must be changed to:
Provider=Mondrian;DataSource=JR
Note that for 5.6, the trailing semicolon should be removed (the older 5.5 syntax includes a semicolon at the end).
For more information about creating and editing XML/A connections, refer to the Jaspersoft OLAP User Guide.
One reason you might have XML/A connections to remote instances of JasperReports Server is to create a load-balanced Jaspersoft OLAP environment. For more information, refer to the Jaspersoft OLAP Ultimate Guide.
Changes in 5.0 That May Affect Your Upgrade
The following changes in 5.0 and newer can significantly affect your deployment:
| • | Upgrading preserving global properties: If you perform an upgrade using the WAR file scripts, you might be able to preserve any custom global settings you have set. See Upgrading Preserving Custom Settings for more information about this feature. |
Upgrading Preserving Custom Settings
If you perform an upgrade using the WAR file scripts, there is no specific action you need to take. However, you need to be aware that the js-upgrade-samedb
Changes in 4.7 That May Affect Your Upgrade
The following changes in 4.7 can affect your deployment:
| • | Themes: An upgraded user interface eliminates unnecessary white space and lets users see more on a single screen. There have been changes to the resources and CSS used by themes, which make it easier to build and maintain new themes. However, existing themes will have to be redesigned in order to work in 4.7. See Upgrading Themes in 4.7 for details on how to upgrade themes. |
| • | Data Snapshots: Reports stored in JasperReports Server can now be configured to store snapshots of the report data in the repository resource. Data snapshots load quickly without querying the data source, thus increasing performance and reducing database load. If data snapshots are turned on, size requirements for your repository may increase dramatically. Data snapshots are disabled globally by default. See Planning Your Upgrade for more information on data snapshots. |
Upgrading Themes in 4.7
The look and feel of the JasperReports Server web interface has been redesigned to increase usable space and be more compatible across browsers. In addition, navigation has been improved with simplified menus and a new Library page that provides quick access to all reports, dashboards, and views a user may access. To accomplish this, images, markup, and styles have been modified and many elements and images are smaller in size. As a result of these modifications, custom themes developed for the previous interface will need to be updated for the new interface.
This section details the changes made to the user interface and describes some of the steps necessary to update custom themes. For information on developing new themes, see the JasperReports Server Administrator Guide.
Banner and Toolbar Modifications
Banner settings have changed in 4.7, which means you will need to modify your theme to work with the new banner. “Banner and Toolbar Settings” shows the elements you need to modify and their default locations. The default values are for these elements are in the default.css file.
|
Element |
Classname and Modification |
File |
Notes |
|
Banner |
.banner Give custom value to height. |
containers.css |
Default value: |
|
Banner Logo |
#logo Give custom values to height and width that match the dimensions of your logo. |
theme.css |
Default values: |
|
Banner |
.menu.primaryNav .wrap Set height and line-height to the same measurement as .banner. |
containers.css |
Default values: |
|
Banner |
.menu.primaryNav .wrap.over
If you already have values for these defined in your alternate theme, then you need to change height and |
containers.css |
Not explicitly defined, but a value of 26px for both elements is cascaded from .menu.primaryNav .wrap If the over and pressed effects fill the banner height after applying the modifications to .menu.primaryNav .wrap, then this step is not necessary. |
|
Banner |
.menu.primaryNav #main_home.wrap > .icon
Set height to be 2px shorter than the height of .banner. Set values for width and background-position to fit your image. |
containers.css |
Default value: Height should be two pixels shorter than banner height. Height is not explicitly defined, but a value of 24px is cascaded from .button .icon in buttons.css Width is not explicitly defined, but a value of 14px is cascaded from .menu.primaryNav #main_ home .wrap > .icon in the containers.css file. |
|
Banner |
.menu.primaryNav .node > .wrap> .icon
Set height to your desired value, with the maximum value being the same height measurement as the .banner element. Set background-position to a value that properly displays the default or your custom image. |
containers.css |
Default values: If you are using Chrome or Safari, the classname that you apply background position to must be preceded by |
|
Banner |
.menu.primaryNav .wrap.over .menu.primaryNav .wrap.pressed Set background-position to a value that properly displays the default or your custom image. |
containers.css |
background-position is not explicitly defined. The value is cascaded from .menu.primaryNav .node > .wrap > .icon This only needs to be adjusted if you want a different color disclosure indicator for the pressed and over states of the main menu links. |
|
Banner Metadata |
#metalinks li Set line-height to the desired value that will vertically center it within the banner. |
theme.css |
Default value: |
|
Banner |
#globalSearch.searchLockup Set margin-top to desired value that will vertically center it within the banner. |
controls.css |
Default value: |
|
Body |
#frame Set a custom top value that positions the body of the application below the banner. |
containers.css |
Default value: This value needs to be greater than the value you apply to the height of .banner. |
|
Toolbar |
.toolbar Set custom height value that will fit your capsule buttons. |
containers.css |
Default value: This is only necessary if you have customized capsule buttons that differ in height from the default images. |
|
Footer |
#frameFooter Rename ID in stylesheet |
containers.css |
The #footer element was renamed to #frameFooter. Change style rules for #footer to #frameFooter. |
Changes to IE Overrides
All style rules have been moved out of the IE-specific CSS files and into the base CSS files. IE-specific notations have been applied to these rules so they can be condensed into the class declarations with the other style rules for a given element. IE-specific styles are commented as shown below:
| • | The following comment indicates a general IE style rule: |
\* IE \*
| • | The following comment indicates a style rule specific to IE7: |
\* IE7 \*
| • | The following comment indicates a style rule specific to IE8 and IE9: |
\* IE8 and IE9 \*
“Changes to Implementation for IE Style Rules” shows an example of an IE7 style rule that has been combined into the base style rules in 4.7 and newer.
|
IE overrides (4.5.1 and earlier) |
lists.css (4.5.1 and earlier) |
lists.css (4.7) |
|
.stepIndicator .icon { *top: 2px; } |
.stepIndicator .icon { margin: 0; top: 1px; margin-right: 3px; } |
.stepIndicator .icon { position: relative; margin: 0px; top: 1px; *top: 2px; \\* IE7 \\ margin-right: 3px; } |
Images in JasperReports Server 4.7
Images for navigation, buttons, and backgrounds in the default theme have changed in version 4.7. Some images have been deleted or moved into a sprite file with a different name, other images have been modified and their properties (such as height and width) may have changed. You need to ensure your custom themes refer to these images. If you have used custom images, you may need to adjust them to work with the new default scheme. This section lists the image files and indicates the changes.
“New Images in 4.7 Default Theme” lists the images that have been added in the 4.7 default theme.
|
Image |
Usage |
Notes |
|
banner_bkgd.png |
Background gradient image for application banner |
|
|
column_header_bkgd.png |
Background gradient image for .header elements in columns and dialogs |
Replaces panel_dialog_header_sprite.png image used for dialog box headers in 4.5.1. |
|
inner_pagination_sprite.png |
Pagination icons (next, previous, etc) for dashboard report widgets |
|
|
spacer.gif |
Icon that appears in the column header of spacer columns in Ad Hoc Editor |
|
|
viewer_toolbar_buttons_sprite.png |
Button icons for the Ad Hoc Editor toolbar |
|
“Modified Images in 4.7 Default Theme” lists the images that have been modified for the 6.0 and newer default theme.
|
Image |
Usage |
Notes |
|
adhoc_toolbar_buttons_sprite.png |
Button icons for the Ad Hoc Editor toolbar |
Some icons are new. All icons have new shadow effect. |
|
button_action_primary_sprite.png |
Background gradient images for the three states of .action.primary buttons |
Removed rounded corners. Colors were adjusted. |
|
button_action_sprite.png |
Background gradient image for the up, over, and pressed states of action buttons |
Removed rounded corners. Colors were adjusted. |
|
button_action_square_icons_sprite.png |
Button icons for the .action.square buttons |
All icons have new shadow effect. |
|
button_capsule_sprite.png |
Background images with rounded corners for capsule buttons |
Rounded corners have a smaller radius. Colors adjusted. Buttons are shorter in height. |
|
button_options_sprite.png |
Background images for the up, over, and pressed states of options buttons |
Removed rounded corners. Added a shadow-only image for the pressed state. |
|
disclosure_indicators_sprite.png |
Small icons that disclose functionality in various parts of the application (within buttons, menus, lists, and forms) |
Shadow effect added to icons for .button.capsule.indicator. |
|
home_bkgd.png |
Large background image on home page |
Image refactored. |
|
home_icons_sprite.png |
Large icons for .action.jumbo button on home and admin home pages |
Icons for View Reports and Create Ad Hoc View refactored. |
|
input_bkgd.png |
Top inner shadow background image for text inputs |
Shadow lightened. Image height changed from 2px tall to 3px tall. |
|
login_welcome_bkgd.jpg |
Main image on login page of pro edition |
Image refactored. |
|
login_welcome_ce_bkgd.jpg |
Main image on login page of community edition |
Image refactored. |
|
logo.png |
Logo used in the banner of the application |
Image is smaller. |
|
menu_primaryNav_sprite.png |
Sprite containing background gradients for mouse over effects and the home icon used in the main menu |
Home icons reduced in size and shadow effect added. |
|
panel_inset_inset_bkgd.png |
|
|
|
search_sprite.png |
Icons used in search controls (search and clear search) |
Images refactored. Input background removed. |
|
tabs_horizontal_sprite.png |
Background gradient images for the over and pressed states of horizontal tabs |
Removed rounded corners. Colors adjusted. |
|
tabs_vertical_sprite.png |
Background gradient images for the up, over and pressed states of vertical tabs |
Removed rounded corners. Colors adjusted. |
“Images With No Modifications in 4.7” lists the images that have not been affected by the refactoring of themes in 4.7.
|
Image |
Usage |
|
adhoc_datatree_icons_sprite.png |
Node and leaf images for fields, measures, and dimensions in the ad hoc data tree |
|
floatingMenu_sprite.png |
Popup menu icons for dashboard widgets |
|
grid_20x20_bkgd.png |
Grid background for dashboard designer canvas |
|
list_node_animation.gif |
Miniature “please wait” animation used in list nodes |
|
list_pressed_bkgd.png |
Background image for the top inner shadow that appears for the pressed state of a .list.filter list item |
|
lists_sprite.png |
Small icons used in various lists throughout the application. Also used for tokens, menus and OLAP cell sorting |
|
loadinfo.gif |
“Please wait” animation used for iPad only |
|
message_icons_sprite.png |
Sprite containing a single icon used for alert message |
|
panel_sizer_sprite.png |
Sprite containing icons for resizing panels and dialogs |
|
report_load_animation.gif |
Animation used in the toolbar of the interactive viewer when a report is loading |
|
sort_indicators_sprite.png |
Sprite containing icons used for the up, over, and pressed states of sortable lists (ascending and descending) |
|
tabs_horizontal_buttons_bkgd.png |
Image used as the top drop shadow for .tabSet.horizontal.buttons |
|
wait_animation_large.gif |
“Please wait” animation used in dialog boxes on page loads and in dashboard iframes when widgets are loading |
“Images from Previous Default Theme Removed in 4.7” shows images used in the earlier themes that have been removed in 6.0, as well as images that have been refactored by placing them in the file inner_pagination_sprite.png.
|
Image |
Usage |
Notes |
|
ajax-loader.gif |
Animation used in the “please wait” dialog for printing dashboards that contain charts |
replaced with wait_animation_large.gif |
|
body_bkgnd.png |
Gradient background image used as the body background for all pages |
|
|
button_action_jumbo_sprite.png |
Background images with rounded corners used for up, over, and pressed states of jumbo buttons |
|
|
column_bkgd_corners.png |
Background image used for rounded corners with drop shadow on column decorated elements |
|
|
column_bkgd_edges_rl.png |
Background image used for right and left borders with drop shadow on column decorated elements |
|
|
column_bkgd_edges_tb.png |
Background image used for top and bottom borders with drop shadow on column decorated elements |
|
|
first-d.gif |
Disabled state of “go to first” icon used for pagination controls inside report dashboard widgets |
Image placed in sprite file inner_pagination_sprite.png |
|
first.gif |
“Go to first” icon used for pagination controls inside report dashboard widgets |
Image placed in sprite file inner_pagination_sprite.png |
|
frame_background_sprite.png |
Gradient background image for the #frame element |
|
|
frame_bkgd_corners.png |
Background image used for rounded corners with drop shadow on the #frame element |
|
|
frame_bkgd_edges_rl.png |
Drop shadow image used for right and left edges of the #frame element |
|
|
frame_bkgd_edges_tb.png |
Drop shadow image used for top and bottom edges of the #frame element |
|
|
frame_header_sprite.png |
Gradient background image with rounded corners used for the header of the #frame element. |
#frame header element holds the main navigation. |
|
last-d.gif |
Disabled state of “go to last” icon used for pagination controls inside report dashboard widgets |
Image moved to sprite file inner_pagination_sprite.png. |
|
last.gif |
“Go to last” icon used for pagination controls inside report dashboard widgets |
Image placed in sprite file inner_pagination_sprite.png. |
|
login_welcome_bkgd_ipad.jpg |
Main image on login page for iPad |
|
|
logo_small.png |
Logo used in the frame header/main navigation bar for iPad |
|
|
menu_context_bkgd_corners.png |
Background image used for rounded corners with drop shadow on .menu.context elements |
|
|
menu_context_bkgd_edges_rl.png |
Background image used for right and left borders with drop shadow on .menu.context elements |
|
|
menu_context_bkgd_edges_tb.png |
Background image used for top and bottom borders with drop shadow on .menu.context elements |
|
|
menu_dropDown_bkgd_corners.png |
Background image used for rounded corners with drop shadow on .menu.dropDown elements |
|
|
menu_dropDown_bkgd_edges_rl.png |
Background image used for right and left borders with drop shadow on .menu.dropDown elements |
|
|
menu_dropDown_bkgd_edges_tb.png |
Background image used for top and bottom borders with drop shadow on .menu.dropDown elements |
|
|
menu_vertical_bkgd.png |
Background for .menu.vertical |
|
|
next-d.gif |
Disabled state of next icon used for pagination controls inside report dashboard widgets |
Image placed in sprite file inner_pagination_sprite.png. |
|
next.gif |
Next icon used for pagination controls inside report dashboard widgets |
Image placed in sprite file inner_pagination_sprite.png. |
|
panel_bkgd_corners.png |
Background image of rounded corners with drop shadow used for the .dialog.overlay element |
|
|
panel_bkgd_edges_rl.png |
Background image of right and left borders with drop shadow used for the .dialog.overlay element |
|
|
panel_bkgd_edges_tb.png |
Background image of top and bottom borders with drop shadow used for the .dialog.overlay element |
|
|
panel_dialog_header_sprite.png |
Background for dialog headers |
|
|
panel_info_bkgd_corners.png |
Background image of rounded corners with drop shadow used for the .info element |
|
|
panel_info_bkgd_edges_rl.png |
Background image of right and left borders with drop shadow used for the .info element |
|
|
panel_info_bkgd_edges_tb.png |
Background image of top and bottom borders with drop shadow used for the .info element |
|
|
panel_info_system_bkgd_corners.png |
Background image of rounded corners used for the .info.system element |
|
|
panel_info_system_bkgd_edges_rl.png |
Background image of right and left borders used for the .info.system element |
|
|
panel_info_system_bkgd_edges_tb.png |
Background image of top and bottom borders used for the .info.system element |
|
|
panel_info_tooltip_bkgd_corners.png |
Background image of rounded corners used for the .panel.tooltip.info element |
|
|
panel_info_tooltip_bkgd_edges_rl.png |
Background image of right and left borders used for the .panel.tooltip.info element |
|
|
panel_info_tooltip_bkgd_edges_tb.png |
Background image of top and bottom borders used for the .panel.tooltip.info element |
|
|
panel_inlay_bkgd_corners.png |
Background image of rounded corners with drop shadow used for the .dialog.inlay element |
|
|
panel_inlay_bkgd_edges_rl.png |
Background image of left and right borders with drop shadow used for the .dialog.inlay element |
|
|
panel_inlay_bkgd_edges_tb.png |
Background image of top and bottom borders with drop shadow used for the .dialog.inlay element |
|
|
panel_inlay_gradient_left.png |
Left background image with gradient and rounded corners used for the .dialog.inlay .footer element |
|
|
panel_inlay_gradient_right.png |
Right background image with gradient and rounded corners used for the .dialog.inlay .footer element |
|
|
panel_inset_bkgd_corners.png |
Background image of rounded corners with drop shadow used for the .groupBox element |
|
|
panel_inset_bkgd_edges_rl.png |
Background image of left and right borders with drop shadow used for the .groupBox element |
|
|
panel_inset_bkgd_edges_tb.png |
Background image of top and bottom borders with drop shadow used for the .groupBox element |
|
|
panel_widget_header_sprite.png |
Background gradient with rounded corners used for the headers of the .panel.widget and .dialog.overlay.widget elements |
|
|
prev-d.gif |
Disabled state of Previous icon used for pagination controls inside report dashboard widgets |
Image placed in sprite file inner_pagination_sprite.png |
|
prev.gif |
Previous icon used for pagination controls inside report dashboard widgets |
Image placed in sprite file inner_pagination_sprite.png |
|
toolbar_bkgd.png |
Background gradient image for the .toolbar element |
|
Data Snapshots
As of 4.7, reports in JasperReports Server can store snapshots of the report data as part of the report unit in the repository. Data snapshots load quickly without querying the data source, thus increasing performance and reducing database load. Data snapshots can be refreshed on-demand, by scheduling, or by setting server-wide or report-specific policies. Existing installations should also resolve any upgrade issues before enabling data snapshots.
Data snapshots are stored in the JasperReports Server repository, which may significantly increase the size of the repository. Before enabling data snapshots, you may want to analyze the effect of snapshots on your repository size and upgrade your storage. For most installations, the benefits from reducing the overall number of queries should outweigh the cost of additional storage.
The actual effect on your repository size depends on the nature of your reports and how many snapshots you enable. It is difficult to give a standard estimate, because snapshot size depends on factors such as the number of columns and the complexity of the report. For a given report, the overall snapshot size is usually proportional to the number of rows. For example, if you have a report of 100,000 records, with 20 records per page, and the snapshot size for one page is 2KB, the overall size of the snapshot will be (100,000 ÷ 20) × 2 KB, or 10 MB.
Data snapshots are turned off globally by default in 4.7 and newer. If you enable data snapshots, they can be turned on or off for each individual report.
See the JasperReports Server Administrator Guide for more information about enabling data snapshots in your JasperReports Server deployment. See the JasperReports Server User Guide for more information about using data snapshots with individual reports.
Using Data Snapshots
Enabling data snapshots has the following benefits:
| • | Queries are only run when a new data snapshot is enabled, when the snapshot is refreshed, and automatically when the server detects that the snapshot is out of date. This allows multiple users to look at the same report without running multiple queries. |
| • | Sharing data snapshots means everyone sees identical data. A data snapshot is a static entity that reflects the state of the data at the time the snapshot was created. This eliminates differences sometimes experienced when data has changed in the repository, or queries are run in different time zones. |
| • | Users can refresh a snapshot and view the latest data by clicking a Refresh button. Non-administrative users do not have permissions to overwrite the snapshot after refresh. |
| • | You can turn off snapshots for reports that need to be dynamic, such as real-time reports in dashboards. |
