Managing cached report data

Cached report data (CRD) is a cached subset of data fetched from the database according to certain conditions and is used as a substitute for the database for retrieving data for reports. This provides several benefits.

• Reports can be run from a specific point in time such as a month end report or quarter end report without going back to the DBMS to get the original data.
• Many users can run reports from data created from a single query without impacting production DBMS users.
• Users running a report will all see the same view of the data, thus the data will not change minute by minute based on current DBMS updates.
• Caching report data can be scheduled for any time frame to simulate real time on-demand reporting for many users while not slowing down the production DBMS.

Cached report data can be created for data sources including queries, stored procedures, imported SQLs, user defined data sources, hierarchical data sources, and parameters whose type is Bind with Single Column or Bind with Cascading Columns. All these types of data sources will be called query resources for convenient documentation since they will be mentioned a lot in the following sections.

There are two types of cached report data in JReport Server: auto CRD and scheduled CRD.

Auto CRD

When running a report, if there is no scheduled CRD created for the query resource that the report is using directly or indirectly (for example, the report is created based on a report cube and the report cube is built from a query resource), data will be fetched from the data source, and at the same time the fetched data is cached and becomes an auto CRD.

When there are auto CRDs generated in a query resource, the report running request based on the query resource will first search for the auto CRD that contains all the data required by the report. If it finds one, the located CRD will retrieve data to the report, but if JReport cannot find one, data is fetched from the data source and cached to be another auto CRD.

Auto CRDs will only be available within one server running life cycle, which means that once the server closes or restarts, they will be removed and a new cycle of auto CRD generation will begin. How many auto CRDs can be held in a query resource within one server running session is decided by the maximum hard disk space configured in the Cache Configuration dialog.

Auto CRDs are disabled for generation by default. You can enable them and configure the maximum hard disk space for auto CRDs and how long an auto CRD is stored. For details, see the Automatic Cache section in the Cache Configuration dialog.

Scheduled CRD

Scheduled CRDs can be created and managed by server administrators. A query resource can have zero or one scheduled CRD. When a query resource contains parameters, its scheduled CRD can only represent the data of one parameter scenario.

Via JReport's scheduling mechanism, administrators are able to define when a scheduled CRD for a query resource will be created and how it will be updated according to time. Scheduled CRDs have no version: once they are updated, only the latest are kept in the query resource.

Creating scheduled CRDs

Administrators can schedule to have a data cache created for a query resource and updated at a specific time or periodically. When scheduling a CRD task, more than one query resource can be selected at a time and a CRD can be created for each query resource and all of the scheduled CRDs will be applied the same creation and updating policy.

1. On the JReport Administration page, click Cache on the system toolbar and then select Data Cache from the drop-down menu.
2. On the Cached Report Data tab, click New Cache on the task bar.
3. In the New Cache dialog for selecting queries, click next to the Select a Folder text field.
4. In the Select Folder dialog, browse to the folder containing the required catalog and click OK.
5. From the Select a Catalog drop-down list, select the required catalog in the specified folder.
6. Click beside the Select Queries box.
7. In the Select Queries dialog, select the query resources you want to create data caches for from the resource tree. Then click OK.
8. Click OK in the New Cache dialog for selecting queries and you are then redirected to the New Cache dialog for scheduling.
9. In the General tab, you can specify values to the parameters of the query resources listed in the Select Query drop-down list. If no values are provided, the default values will be applied. The query resource names will be used as the new CRD names.
10. Specify the other settings in the tab if needed.
11. In the Conditions tab, specify the time for when the task is to be performed in the Time sub tab, and select or create a trigger to bind with the task in the Trigger sub tab. The setting in the Conditions tab decides when the CRDs will be created and when they will be updated.
12. In the Notification tab, specify to notify someone via e-mail when the task is finished and whether it is successful or unsuccessful.
13. Click Finish, and JReport Server will then perform the task at the requested times.

See also New Cache dialog for details about options in the dialog.

Using scheduled CRDs

A scheduled CRD has four statuses. Whether reports running based on the same query resource as the CRD can fetch data from the CRD is determined by the CRD's status.

• Not ready
  CRD is not initiated yet. The reports will try to get data from the data source directly.
• Initiating
  CRD is preparing its data for the first time, but still not ready. The reports will wait for the CRD to be ready and then fetch data from the ready CRD.
• Ready
  CRD is prepared and ready to use. All reports based on the same query resource will fetch data from the CRD.
• Updating
  CRD is updating itself at a scheduled point. All reports based on the same query resource will use the ready CRD before the update happens. Once the update is finished, later reports will get data from the updated CRD.

After a scheduled CRD is created and ready to use, all reports based on the same query resource as the CRD will automatically use the CRD for retrieving data.

Since a scheduled CRD freezes parameters in the query resource, if a report uses a scheduled CRD and its query resource contains parameters, when running the report, only parameters used in the report are available for specifying values and the query resource parameters will be disabled for editing. In JReport, a parameter may depend on another parameter; if the latter is frozen, the former will be frozen as well.

Editing scheduled CRDs

The generated scheduled CRDs are displayed in the Cached Report Data tab.

You can further edit the scheduling information of the CRDs if required. To do this, select the row in which the CRD you want to edit is located, then click Edit > Properties on the task bar or right-click on the row and select Properties from the shortcut menu. If parameters or schedule policy is changed, they will only take effect after the next CRD update; before that, all reports using the CRD will still get the old data.

In addition, if you find any of the scheduled CRD is no longer required, you can remove it. To do this, select the row where the CRD is, then clicking Edit > Delete on the task bar; or right-click in the row and select Delete from the shortcut menu.

Viewing and managing scheduled CRD tasks

CRD tasks that are waiting to be performed are listed in the Scheduled tab. To access the tab, click Cache > Data Cache on the system toolbar and then go to the Scheduled tab.

CRD tasks that are currently being performed are listed in the Running tab. To access the tab, click Cache > Data Cache on the system toolbar and then go to the Running tab.

CRD tasks that have already been performed are listed in the Completed tab. To access the tab, click Cache > Data Cache on the system toolbar and then go to the Completed tab. You can remove the record of a completed CRD task from the tab if required. To do this, select the row where the record is located and then click Delete on the task bar, or right-click on the row and select Delete from the shortcut menu.

For details about the tabs, refer to Data Cache panel.

Recovering scheduled CRDs

Scheduled CRDs will be recovered after the server shuts down and then restarts. The data before the shutdown will be maintained.

If a CRD is updating when the shutdown happens, the CRD will continue with the update when the server restarts.

Synchronizing scheduled CRDs with catalog republish

After a catalog is republished, how the existing scheduled CRDs based on the old query resources in the catalog will be updated depends on the following conditions:

• If no query resource is modified, the existing CRDs will be automatically applicable to the new catalog.
• If a query resource is modified, the scheduled CRD based on the old query resource will behave as follows:
  • Before the next schedule time, the CRD will be disabled for retrieving data to reports.
  • When it is the next schedule time, data is fetched from the new query resource to generate an updated scheduled CRD:
    • If new parameters are added in the new query resource, default values will be used until an administrator specifies values to them.
    • If old parameters are deleted from the new query resource, the parameter values previously specified in the CRD will be removed.
    • If parameters are changed and the previously specified values do not match the type, error messages will be given in the server error log and the CRD is disabled for service.

Configuring the CRD memory usage

Administrators can configure the maximum CRD memory in the Cache Configuration dialog, which is applicable for both types of CRDs (to access the dialog, focus on the Cached Report Data tab, then click Cache Configuration on the task bar). The value should be at least 4 MB and not more than 80% of the JVM current maximum heap size. The number of MBs must be configured in whole numbers. The cache is used to improve performance when multiple users are running reports using the same CRD. Any size CRD can be accessed with even the smallest cache size. The larger the cache size the faster performance will be for concurrent users, but a large cache size may lower performance for users who do not use the CRD. All CRDs share the same cache area.

If possible, set the maximum memory usage to a number that the memory can handle, for example, 512 MB or bigger.