The JasperReports library comes with built-in viewers that enable you to display the
reports stored in the library’s proprietary format or to preview your report templates
when you create them.
These viewers are represented by the following two classes:
: Use this class to view generated
reports, either as in-memory objects or serialized objects on disk or even stored in
: 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
class and its companions. It is in fact a
component that is capable of displaying generated
reports. It can be easily incorporated into other Java Swing–based applications or
If the functionality of this basic visual component does not meet your needs, you 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 yourself in the new visual component
you obtain by subclassing.
This is shown in the
sample, where the “Printer Applet”
displays a customized version of the report viewer with an extra button in the toolbar.
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
However, JasperReports lets you handle the clicks made on document hyperlinks that
point to external documents. To do this, simply implement the
interface and add an instance
of this listener class to register with the viewer component, using the
method exposed by the
class. By doing this, you ensure that the
viewer will also call your implementation of the
method in which
you handle the external references yourself.
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
context of the viewer
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 could 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
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
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.
Recent surveys indicate that JasperReports is usually used inside web-based applications
to render dynamic content.
When using JasperReports inside such applications, keep in mind how to handle report
templates, reference report resources, and deal with images when exporting to HTML.
A small web application that does these things is included as one of the samples. The
directory inside the project distribution package contains the
source files of a simple web application that uses JasperReports for rendering a report.
This report can be viewed in HTML and PDF format, or even directly as a
object using the built-in Swing viewer as an applet inside the browser.
Any Java application that needs reporting functionality can use the JasperReports library
in two ways:
To generate documents out of static report templates that get compiled at
development time and are distributed in the compiled form as part of the
application distribution files
To generate documents out of dynamically built or so-called ad hoc report
templates that are the result of some user input at runtime
In the first case,
files containing compiled report templates are deployed as
resources inside the application distribution package, just as images or normal Java
files are distributed and deployed. The compilation of the static report
templates should be part of the application build system, taking into account that the
library is shipped with a ready-to-use Ant task for bulk-compiling multiple report
template files at once.
The second scenario assumes that static report templates cannot be used, or at least are
subject to some runtime modifications based on user feedback. Runtime-created or
runtime-modified report templates must be compiled on the fly. Report compilation in a
web environment can be a challenge if JDK-based report compilers are used, because
they require a temporary working directory and an explicitly set classpath. However,
recent versions of JasperReports use the JDT-based compiler by default, which is both
faster and easier to use because it does not require any configuration. To use it, make
file distributed with the JasperReports project source files
directory is part of the web application classpath.
Report templates can reference other resources such as images, fonts, or other report
templates used as nested subreports. In any Java application, but especially inside web
applications where locating files on disk is more challenging, the best way to locate static
resources is by means of classpath. All the resources that need to be loaded using a
relative location at runtime should be part of the application’s classpath. Images, fonts,
and subreports should be referenced inside a report template using their relative location
within the classpath. By doing this, you ensure that links between those resources are
still valid regardless of how the application is actually deployed.
Since images cannot be embedded in the HTML output directly, but are supposed to be
retrieved by the browser from their specified public URL, a web application using
JasperReports for generating reports in HTML must be specially configured for the
JasperReports is now shipped with a ready-to-use servlet implementation that can deliver
images from a
document or a list of
documents placed on
the HTTP session.
The HTML exporter can be configured so that all the images point to this servlet in their
URLs. To do this, supply the URL prefix to use for all the images as the value for the
The image servlet is implemented by the
class. An example is in the
sample inside the project distribution.
can be configured to export one page at a time. With the source
document kept on the HTTP session, an application can simulate a viewer
that allows users to view the document page by page, as we do with the built-in Swing
viewer, instead of viewing all the pages at the same time, one after the other.
sample shows how such a simple HTML viewer
can be implemented inside a web application.
Although it can send binary PDF content directly into an output stream, the PDF exporter
must be used in combination with an in-memory
when used inside a web application to send output to the browser on the client side. It
must measure the length of the binary output that it produces before even attempting to
send that output directly to the browser because some browsers need to know the size of
the binary content they will receive in order to work properly.
The downside is that you consume extra memory by temporarily storing PDF content
instead of sending it directly to the consumer.
If a web-based application is used only or mainly inside an intranet, and it is acceptable
to use Java applets for enhanced usability, generated reports can be viewed with the
built-in Swing viewer. The server application would no longer need to export the
objects to more popular formats such as HTML or PDF, but can instead
send the objects over the network in serialized form to an applet that can display them
Among the files available for download on the JasperReports web site is one called
. This JAR file is smaller than the complete
because it contains only the class interfaces that the
viewer needs to display documents in the proprietary
format, making it
more appropriate for an applet.
An applet making use of this smaller JAR file is in the supplied
sample provided with the project’s source files.
Documents you may be interested
Documents you may be interested