The last two options allow report designers to specify a minimum height for the image
element in the report template and to rely on the fact that the image element will stretch
at fill time to accommodate the actual size of the rendered picture.
Note that, as for stretchable text fields, only the image height can increase. This follows
the JasperReports principle that design element widths are fixed, and that the report
flows downwards while data is fed to it.
As mentioned above, there are two scale types that allow images to stretch:
. The difference between them is that the former always preserves the
width of the image element, while the latter adjusts the width of the image when the
actual image width is smaller than the design image width. Adjusting the image width is
useful when a border needs to be drawn around the image; if the image width is not
adjusted, then the border might get drawn according to the design image width and some
empty space would be left between the image and the border.
In order for image stretching to work, the actual image size needs to be known at report
fill time. For images that use image files as sources, the image size will always be
known. For images that use other type of renderers, the image size is determined by
method on the image renderer object, which is an instance
of a class that implements
. If the
method returns a
dimension, the actual image size will not be known and the image
will not stretch, but will render inside the area given by the design image width and
Another inherent limitation is that images that have delayed evaluation will not be able
to stretch. Stretching such images is not supported because the actual image size can only
be know after the image has been positioned in the generated report and other elements
have been placed beneath the image, and stretching the image at this point would disturb
the layout of the generated report.
Stretching images will always preserve proportions and will never get deformed. Any
scaling which performed to the image will be performed uniformly on the horizontal and
If the actual image width is larger than the design width of the image element, the image
will be scaled down to fit the element width set at design time. In other words, the design
image width acts as an upper limit of the width of the generated image.
When the engine stretches an image, if the actual image height is bigger than the vertical
space left to the bottom of the page, the image will cause the band to overflow and the
engine will render the image on the new report page or column. If the vertical space
available here is still not enough to render the image at its actual size, the image will be
scaled down to fit the available height.
Note that if the actual height of the image is smaller than the declared height of the
image, the height of the generated image will not be decreased. The produced image will
always be at least as tall as the design image element, its height can only be increased
when the report is filled.
If the scale type for the image is
and the actual image is smaller
than its defined size in the report template or does not have the same proportions, the
image might not occupy all the space allocated to it in the report template. In such cases,
you can align the image inside its predefined report space using the
attributes, which specify the alignment of the image on the horizontal axis (
) and the vertical axis (
). By default, images are
aligned at the top and to the left inside their specified bounds.
All image elements have dynamic content. There are no special elements to introduce
static images on the reports as there are for static text elements. However, most of the
time, the images on a report are in fact static and do not necessarily come from the data
source or from parameters. Usually, they are loaded from files on disk and represent
logos and other static resources.
To display the same image multiple times on a report (for example, a logo appearing on
the page header), you do not need to load the image file each time. Instead, you can
cache the image for better performance. When you set the
, the reporting engine will try to recognize previously loaded images using their
specified source. For example, it will recognize an image if the image source is a file
name that it has already loaded, or if it is the same URL.
This caching functionality is available for image elements whose expressions return
objects of any type as the image source. The
flag is set to
default for images having
expressions and to
for all other
types. The key used for the cache is the value of the image source expression; key
comparisons are performed using the standard equals method. As a corollary, for images
source with caching enabled, the input stream is read
only once, and subsequently the image will be taken from the cache.
flag should not be set in cases when an image has a dynamic source
(for example, the image is loaded from a binary database field for each row) because the
images would accumulate in the cache and the report filling would rapidly fail due to an
out-of-memory error. Obviously, the flag should also not be set when a single source is
used to produce different images (for example, a URL that would return a different
image each time it’s accessed).
Lazy Loading Images
Boolean attribute specifies whether the image should be loaded and
processed during report filling or during exporting. This can be useful in cases in which
the image is loaded from a URL and is not available at report-filling time, but will be
available at report-export or display time. For instance, there might be a logo image that
has to be loaded from a public web server to which the machine that fills the reports does
not have access. However, if the reports will be rendered in HTML, the image can be
loaded by the browser from the specified URL at report-display time. In such cases, the
flag should be set to
by default) and the image expression
should be of type
, even if the specified image location is actually a
URL, a file, or a classpath resource. When lazy loading an image at fill time, the engine
will no longer try to load the image from the specified
location but only store
that location inside the generated document. The exporter class is responsible for using
value to access the image at report-export time.
sample contains an image element that points to the
JasperReports logo, which is lazy loaded from the project’s web site.
Missing Images Behavior
For various reasons, an image may be unavailable when the engine tries to load it either
at report-filling or export time, especially if the image is loaded from some public URL.
For this reason, you may want to customize the way the engine handles missing images
during report generation. The
attribute available for images allows that. It
can take the following values:
Error: An exception is thrown if the engine cannot load the image (
Blank: Any image-loading exception is ignored and nothing will appear in the
generated document (
Icon: If the image does not load successfully, then the engine will put a small icon
in the document to indicate that the actual image is missing
As with text fields, you can postpone evaluating the image expression, which by default
is performed immediately. This will allow you to display somewhere in the document
images that will be built or chosen later in the report-filling process, due to complex
algorithms, for example.
The same attributes that we talked about in the “Text Fields” section,
, are available in the
attribute can take the following values:
Immediate evaluation: The image expression is evaluated when the current band is
End-of-report evaluation: The image expression is evaluated when the end of the
report is reached (
End-of-page evaluation: The image expression is evaluated when the end of the
current page is reached (
End-of-column evaluation: The image expression is evaluated when the end of the
current column is reached (
End-of-group evaluation: The image expression is evaluated when the group
specified by the
Auto evaluation: Each variable participating in the image expression is evaluated at
a time corresponding to its reset type. Fields are evaluated
The default value for this attribute is
The value returned by the image expression is the source for the image to be displayed.
The image expression is introduced by the
element and can return
values from only the limited range of classes listed following:
When the image expression returns a java.lang.String value, the engine tries to see whether
the value represents a URL from which to load the image. If it is not a valid URL representation, it tries to locate a
file on disk and load the image from it, assuming that the value represents a file name. If no file is found, it finally
assumes that the string value represents the location of a classpath resource and tries to load the image from
there. An exception is thrown only if all these attempts fail.
If the image expression class is not specified using the class attribute, it is assumed to be
, by default.
sample provided with the project contains several
examples of image elements.
The content of an image element can come either directly from an image file like a JPG,
GIF, PNG, or can be a Scalable Vector Graphics (SVG) file that is rendered using some
business logic or a special graphics API like a charting or a barcode library. Either way,
JasperReports treats images in a very transparent way because it relies on a special
to offer a common
way to render images.
interface has a method called
, which gets called by the engine each time it needs to draw the image
on a given device or graphic context. This approach provides the best quality for the
SVG images when they must be drawn on unknown devices or zoomed into without
Other methods specified in this interface can be used to obtain the native size of the
actual image that the renderer wraps or the binary data for an image that must be stored
in a separate file during export.
The library comes with a default implementation for the
wraps images that come from files or binary image data in JPG, GIF, or PNG format.
class is actually a container
for this binary image data, which it uses to load a
object from it,
which it then draws on the supplied
context when the engine
Image renderers are serializable because inside the generated document for each image is
a renderer object kept as reference, which is serialized along with the whole
instance is serialized, so is the binary image data it contains.
However, if the image element must be lazy loaded (see the
attribute), then the
engine will not load the binary image data at report-filling time. Rather, it stores inside
the renderer only the
location of the image. The actual image data
is loaded only when needed for rendering at report-export or view time.
To simplify the implementation of SVG image renderers, JasperReports ships with an
implementation contains the code to produce binary image data from the SVG graphic in
JPG format. This is needed when the image must be stored in separate files on disk or
delivered in binary format to a consumer (like a web browser).
The JasperReports library does not produce charts and graphics itself. This is not one of
its goals. However, it can easily integrate charts, barcodes, and graphics produced by
other more specialized Java libraries.
Documents you may be interested
Documents you may be interested