Virtualizers in JasperReports

There has been several articles written about Virtualizers. The aim here is to gather all of the pieces of information related to them and to get deeper into the details. This article won't focus on a particular version of JarperReports. Starting by a little bit of background, what is important to  understand is the need and use of the Virtualizer in JasperReports. We will then enumerate the situation where a Virtualizer is needed. Moving then to a more technical approach, we will go through the different virtualizers available and when to use them.

A little bit of background: How a report is generated

I'm going to start by quickly explaining how a report is generated. The report template that is generally built by iReport or Ad Hoc report designer (a jrxml file) is compiled by JasperReports into a .jasper file. Then this .jasper file is filled with data to create a jasper print object. This jasper print object is then exported to the format you want (HTML, PDF, Excel,...).

When to use a Virtualizer

The virtualizer will be involved at the creation of the jasper print file. Because you may have a very large amount of data, the jasper print might be a very large file. This can lead to an Out Of Memory exception. The Virtualizer will cut the jasper print into different files and save them on the hard drive and/or compress it. The result generally makes the generation of the report a bit slower but it will solve the memory exception.

Different Virtualizers available with JasperReports

There are different Virtualizers available with JasperReports.

Each virtualizer has his strength and choosing the one which will be the perfect fit depends on the context. In most cases the swap file virtualizer is faster than the JRFileVirtualizer. The difference comes from file system implementations, most deal better with one large file than with many small files. But the only catch is that you need to pick sensible parameters for the swap file. Good default values are something like 4096 for block size and 200 for grow count.

The Gzip significantly reduces memory usage (somewhere between 10x and 20x, depending on the report) at the expense of CPU time. It obviously scales worse than disk virtualizers and in some scenarios it can even be slower.

How to use a virtualizer for your report generation?

The configuration of the virtualizer is done in the applicationContext.xml, one of the Spring framework configuration files. This file is located in the /jasperserver-pro/WEB-INF directory.

The only part to modify is the fileVirtualizerFactory bean. By default it should look like this:

<!--report virtualizers-->
<bean id="fileVirtualizerFactory"
      class="com.jaspersoft.jasperserver.api.engine.common.service.impl.FileVirtualizerFactory">
    <property name="maxSize" value="300"/>
    <property name="directory" value="${java.io.tmpdir}"/>
</bean>

So, by default, the FileVirtualizer is used.

To use the Swap virtualizer simply change the class of the FileVirtualizer bean to "com.jaspersoft.jasperserver.api.engine.common.service.impl.SwapFileVirtualizerFactory" and change property name "directory" to "tempDirectory"

And similarly the class for the GZIP virtualizer is "com.jaspersoft.jasperserver.api.engine.common.service.impl.GZipVirtualizerFactory".

Also notice the 2 parameters:

• maxSize - this is the number of pages at which the virtualizer should kick on - setting this very high effectively disables the virtualizer. 300 is the default value in JasperReports Server. Finding the right number will require some experimentation/calculation based on the amount of RAM allocated to the JVM and the amount of simultaneous large report executions that you will have.
• directory - this is the directory to save the tempoary files. On Linux if you want "off heap" memory to kick on set it to a RAM disk like /dev/shm

As a general indicator, to determine what is the "best" virtualizer to use for JasperServer and your individual situation, you should consider:

• How many simultaneous reports are going to be run?
• How large are they (number of pages)?
• Are they graphics heavy?
• Are the users using the browser to page through reports?

For example If the number of simultaneous pages is low, then the GZIP virtualizer can be a better choice, as it should be faster than the file based virtualizers. But on the downside if the traffic/usage suddenly spikes, you could run out of memory with this virtualizer.

To make sure your new configuration is taken in account make sure to restart the server.

How to use a virtualizer in iReport Designer?

The virtualizer can be tested directly in iReport Designer. There is no need to deploy to the server to evaluate the gain in performance.

To setup iReport Designer:

Run iReport Designer Select Options->iReport->Compilation and execution->Execution options tab, to enable it by checking "Use virtualizer" Select iReport->Options->iReport->Compilation and execution->Virtualizer tab, to set the virtualizer parameters here.

See also

• Custom virtualizer: Configuring a Report Virtualizer
• Comparison between the different virtualizers: Comparison of Report Virtualizers
• Virtualizers in iReport Designer: How to use the build-in parameter REPORT VIRTUALIZER in iReport