Package net.sf.jasperreports.view

package net.sf.jasperreports.view
Contains the Jasper viewer implementation.

Viewing Reports

The JasperReports library comes with built-in viewers for viewing the generated reports in its proprietary format or in the proprietary XML format produced by the internal XML exporter. It is a Swing-based component. Other Java applications can easily integrate this component without having to export the documents into more popular formats in order to be viewed or printed. The JRViewer class represents this visual component. It can be customized to respond to a particular application's needs by subclassing it. For example, you could add or remove buttons from the existing toolbar.

JasperReports also comes with a simple Swing application that uses the visual component for viewing the reports. This application helps view reports stored on disk in the JasperReports *.jrprint proprietary format or in the JRPXML format produced by the default XML exporter.

This simple Java Swing application is implemented in the JasperViewer class and is used in almost all the provided samples for viewing the generated reports.

To view a sample report if you have the Ant build tool installed on your system, go to the desired sample directory and launch the following from the command line:

 >ant view
 or
 >ant viewXml

Customizing Viewers

Built-in viewers are represented by the following two classes:
  • JasperViewer - use this class to view generated reports, either as in-memory objects or serialized objects on disk or even stored in XML format.
  • JasperDesignViewer - use this class to preview report templates, either in JRXML or compiled form.
However, these default viewers might not suit everybody's needs. You may want to customize them to adapt to certain application requirements. If you need to do this, be aware that these viewers actually use other, more basic visual components that come with the JasperReports library.

The report viewers mentioned previously use the visual component represented by the JRViewer class and its companions. It is in fact a special javax.swing.JPanel component that is capable of displaying generated reports. It can be easily incorporated into other Java Swing-based applications or applets.

If the functionality of this basic visual component is not sufficient, one can adapt it by subclassing it. For example, to create an extra button on the toolbar of this viewer, extend the component and add that button in the new visual component obtained by subclassing.

Another very important issue is that the default report viewer that comes with the library does not know how to deal with document hyperlinks that point to external resources. It deals only with local references by redirecting the viewer to the corresponding local anchor.

However, JasperReports lets users handle the clicks made on document hyperlinks that point to external documents. To do this, simply implement the JRHyperlinkListener interface and add an instance of this listener class to register with the viewer component, using the addHyperlinkListener(JRHyperlinkListener) method exposed by the JRViewerPanel class. By doing this, you ensure that the viewer will also call the implementation of the gotoHyperlink(JRPrintHyperlink) method in which the external references are handled.

There are two ways of rendering the current document page on the viewer component:

  • Creating an in-memory buffered image and displaying that image
  • Rendering the page content directly to the Graphics2D context of the viewer component
The first approach has the advantage of smoother scroll operations, since the page content is rendered only once as an image, after which the scroll operations occur within the view port of that image. The drawback is that at high zoom ratios, the image could become so large that an out-of-memory error might occur.

The second approach avoids any potential memory problems at high zoom ratios by rendering page content directly onto the view component, but this results in a drop of performance that can be seen when scrolling the page.

Switching between the two rendering methods can be controlled by setting the net.sf.jasperreports.viewer.render.buffer.max.size configuration property. The value of this property represents the maximum size (in pixels) of a buffered image that would be used by the JRViewer component to render a report page (the first rendering technique). If rendering a report page requires an image larger than this threshold (that is, image width x image height > maximum size), then the report page will be rendered directly on the viewer component.

By default, this configuration property is set to 0, which means that only direct rendering is performed, no matter what the zoom ratio.

JasperReports Tutorial
See Also: