Package net.sf.jasperreports.engine.fill

Contains fill time implementations for the library's main interfaces and the entire engine used in the filling process (the actual core of JasperReports).

Filling Report Templates

The report-filling process is the most important piece of JasperReports library functionality, because it manipulates sets of data to produce high-quality documents. This is the main purpose of any reporting tool.

The following things should be supplied to the report-filling process as input:

  • a report template (in the compiled form)
  • parameters
  • data source
The output is always a single, final JasperPrint document ready to be viewed, printed, or exported to other formats.

The JasperFillManager class is usually used for filling a report template with data. This class has various methods that fill report templates located on disk, come from input streams, or are supplied directly as in-memory JasperReport objects. After getting the report template, the report filling methods are calling the related fill(...) method in the JRFiller class, that actually fills the report.

The output produced always corresponds to the type of input received. That is, when receiving a file name for the report template, the generated report is also placed in a file on disk. When the report template is read from an input stream, the generated report is written to an output stream, and so forth.

The various utility methods for filling the reports may not be sufficient for a particular application - for example, loading report templates as resources from the classpath and outputting the generated documents to files on disk at a certain location.

In such cases, manually loading the report template objects is to be considered before passing them to the report-filling routines using the JRLoader utility class. This way, one can retrieve report template properties, such as the report name, to construct the name of the resulting document and place it at the desired disk location.

The report-filling manager class covers only the most common scenarios. However, you can always customize the report-filling process using the library's basic functionality just described.

Generated Reports

The output of the report-filling process is always a pixel-perfect document, ready for viewing, printing, or exporting to other formats. These documents come in the form of JasperPrint objects, which are serializable. This allows the parent application to store them or transfer them over the network if needed.

At the top level, a JasperPrint object contains some document-specific information, like the name of the document, the page size, and its orientation (portrait or landscape). Then it points to a collection of page objects (JRPrintPage instances), each page having a collection of elements that make up its content. Elements on a page are absolutely positioned at x and y coordinates within that page and have a specified width and height in pixels. They can be lines, rectangles, ellipses, images, or text, with various style settings corresponding to their type.

Filling Order

JasperReports templates allow the detail section to be smaller than the specified page width so that the output can be structured into multiple columns, like a newspaper.

When multiple-column report templates are used, the order used for filling those columns is important. There are two possible column orders, that can be set in the report template using the printOrder attribute:

  • Vertical - meaning that they run from top to bottom and then from left to right. This is the default order. The report filling process is provided by the JRVerticalFiller class.
  • Horizontal - meaning that they first run from left to right and then from top to bottom. In this case the report is filled using methods in the JRHorizontalFiller class.
When filling report templates horizontally, dynamic text fields inside the detail section do not stretch to their entire text content, because this might cause misalignment on the horizontal axis of subsequent detail sections. The detail band actually behaves the same as the page and column footers, preserving its declared height when horizontal filling is used.

Asynchronous Report Filling

JasperReports provides the AsynchronousFillHandle class to be used for asynchronous report filling. The main benefit of this method is that the filling process can be canceled if it takes too much time. This can be useful, for example, in GUI applications where the user would be able to abort the filling after some time has elapsed and no result has been yet produced.

When using this method, the filling is started on a new thread. The caller is notified about the progress of the filling process by way of listeners implementing the AsynchronousFilllListener interface. The listeners are notified of the outcome of the filling process, which can be success, failure, or user cancellation. The handle is used to start the filling process, register listeners, and cancel the process if wanted.

A typical usage of this handle is the following:

  • The handle is created by calling the static createHandle() methods in AsynchronousFillHandle that take as arguments the report object, the parameter map, and the data source or the database connection to be used.
  • One or more listeners are registered with the handle by calling the addListener() method. In a GUI application, the listener could perform some actions to present to the user the outcome of the filling process.
  • The filling is started with a call to the startFill() method. In a GUI application, this could be the result of some user action; the user can also be notified that the filling has started and is in progress.
  • The filling can be canceled by calling cancellFill() on the handle. In a GUI, this would be the result of a user action.
  • The listeners are notified when the process finishes. There are three events defined for the listeners, only one of which will be called, depending on the outcome of the filling:
    • reportFinished() - called when the filling has finished successfully; the filled report is passed as a parameter. In a GUI, the user would be presented the filled report or would be able to save/export it.
    • reportFillError() - called when the filling ends in error; the exception that occurred is passed as a parameter.
    • reportCancelled() - called when the filling is aborted by the user.

Large File Support

If very large datasets are used for report filling, the size of the resulting JasperPrint object could also be very large and might cause the JVM to run out of memory.

To increase the memory available for the Java application, first use the -Xmx option when launching the JVM, since the default value for this parameter is fairly small. However, if you do this with large datasets (for example, containing tens of thousands or more records and resulting in documents that have thousands or more pages), the JVM may run out of memory.

JasperReports offers a simple solution to the problem by introducing the report virtualizer. The virtualizer is a simple interface (JRVirtualizer) that enables the reporting engine to optimize memory consumption during report filling by removing parts of the JasperPrint object from memory and storing them on disk or in other temporary locations. If a report virtualizer is used during filling, the engine keeps only a limited number of pages from the generated JasperPrint object at a time and serializes all the other pages to a temporary storage location, usually the file system.

Using a report virtualizer is very simple. You supply an instance of the JRVirtualizer interface as the value for the built-in REPORT_VIRTUALIZER parameter when filling the report.

In virtualized form, a generated JasperPrint document still behaves normally and can be subject to exporting, printing, or viewing processes, and the impact on memory consumption is minimal even when dealing with very large documents.

When produced using a virtualizer (which itself performs partial document serialization into temporary files), once completed, a JasperPrint document can itself be serialized normally without any loss of information. During the serialization of a virtualized JasperPrint object, the program puts back together all the pieces and a single serialized file is produced. However, because this single file is probably very large, simple deserialization would not make sense (in fact, it wouldn't be possible, as the JVM would run out of memory, which is the reason for using virtualization in the first place). So in order to reload into memory a virtualized document that was serialized to a permanent storage facility, a report virtualizer is needed. This would be set using a local thread variable by calling the following: 

 JRVirtualizationHelper.setThreadVirtualizer(JRVirtualizer virtualizer)

File virtualizer

The library ships with a ready-to-use implementation of this interface called JRFileVirtualizer, which stores document pages on disk during the filling process to free up memory. Once a JasperPrint object is produced using a report virtualizer, it can be exported to other formats or viewed directly using the library's built-in viewer component, even though this document is not fully loaded at any one time. The virtualizer ensures that pages are deserialized and loaded from their temporary storage location as needed during exporting or display. A single JRFileVirtualizer instance can be shared across multiple report-filling processes so that the number of document pages kept in-memory at any one time will be limited by the virtualizer maxSize property, regardless of the number of reports that are generated simultaneously.

Because it works with temporary files on disk, the file virtualizer has a built-in mechanism to remove those files after they are no longer needed (that is, after the generated document or the virtualizer itself have been disposed of by the JVM). The cleanup() method exposed by this virtualizer implementation can be also called manually so that the temporary files are removed from disk right away instead of after the finalization of the entities involved.

To ensure that no virtualization files are left over on disk by the application that uses the file virtualizer, all these temporary files are registered with the JVM so that they are deleted automatically when the JVM exits normally.

But using File.deleteOnExit() will accumulate JVM process memory on some virtual machine implementations (see http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4513817); you should avoid using this feature in long-running applications by turning it off using the net.sf.jasperreports.virtualizer.files.delete.on.exit configuration property.

Swap File Virtualizer

On some platforms, working with a large number of files in a single folder, or even the file manipulating processes themselves, may have a significant impact on performance or pose additional problems. This makes the use of the JRFileVirtualizer implementation less effective.

Fortunately, there is another implementation of a file-based report virtualizer that uses a single swap file and can also be shared among multiple report-filling processes. Instead of having one temporary file per virtualized page, we create a single file into which all virtualized pages are stored to and then retrieved from.

This swap file virtualizer implementation is represented by the JRSwapFileVirtualizer class that is part of the JasperReports library core functionality, and works in combination with a JRSwapFile instance representing the target swap file.

The JRSwapFile instance has to be created and configured prior to being passed to the swap virtualizer. You can create such an instance by specifying the target directory where the swap file will be created, the size of the blocks allocated by the swap file, and the minimum number of blocks by which the swap file will grow when its current size becomes insufficient.

The JRConcurrentSwapFile class represents an enhanced implementation of the JRSwapFile that only works with JRE version 1.4 or later, because it uses a java.nio.channels.FileChannel to perform concurrent I/O on the swap file.

In-Memory GZIP Virtualizer

The JRGzipVirtualizer is a convenient report virtualizer implementation that does not rely on the file system to temporarily store unused/virtualized document pages during the report filling. Rather, it optimizes memory consumption by compressing those pages in-memory using a GZIP algorithm. Tests indicate that memory consumption during large report-generating processes is reduced up to a factor of ten when the in-memory GZIP report virtualizer is used.

Related Documentation

JasperReports Tutorial
See Also:
JasperFillManager, JasperPrint, JasperReport, JRPrintPage, JRVirtualizer, JRConcurrentSwapFile, JRLoader, JRSwapFile