The JasperReports Ultimate Guide
Page 1
The JasperReports Ultimate Guide
Version 1.0
Author:
Teodor Danciu
Copyright © 2002 Teodor Danciu (teodord@hotmail.com). All rights reserved.
The JasperReports Ultimate Guide
Page 2
Table of contents
1 Introduction______________________________________________________4
2 API Overview_____________________________________________________5
3 Main Tasks and Processes _________________________________________10
3.1 XML Parsing _____________________________________________________ 10
3.2 Compiling Report Designs __________________________________________ 10
3.3 Report Design Preview _____________________________________________ 12
3.4 Filling Reports ____________________________________________________ 13
3.5 Viewing Reports ___________________________________________________ 15
3.6 Printing Reports___________________________________________________ 16
3.7 Exporting Reports _________________________________________________ 17
3.8 Object Loading and Saving__________________________________________ 17
4 Report Designs___________________________________________________19
4.1 DTD Reference ____________________________________________________ 19
4.2 XML Encoding____________________________________________________ 20
4.3 Report Properties__________________________________________________ 21
5 Report Data _____________________________________________________25
5.1 Expressions _______________________________________________________ 25
5.2 Parameters _______________________________________________________ 26
5.2.1 Built-in Report Parameters ______________________________________________ 28
5.3 Data Source_______________________________________________________ 29
5.4 Report Query _____________________________________________________ 31
5.5 Fields ____________________________________________________________ 32
5.6 Variables _________________________________________________________ 34
5.6.1 Calculations __________________________________________________________ 35
5.6.2 Built-in Report Variables________________________________________________ 37
6 Report Sections __________________________________________________38
6.1 Main Report Sections ______________________________________________ 39
6.2 Data Grouping ____________________________________________________ 40
7 Scriptlets________________________________________________________43
8 Report Elements _________________________________________________44
8.1 Text Elements_____________________________________________________ 48
8.1.1 Fonts and Unicode Support ______________________________________________49
8.1.2 Static Texts __________________________________________________________ 53
8.1.3 Text Fields ___________________________________________________________ 53
8.2 Graphic Elements__________________________________________________ 56
8.2.1 Lines _______________________________________________________________57
8.2.2 Rectangles ___________________________________________________________ 58
8.2.3 Images ______________________________________________________________ 58
The JasperReports Ultimate Guide
Page 3
8.2.4 Charts and Graphics____________________________________________________ 60
8.3 Hyperlinks _______________________________________________________ 60
8.4 Element Groups ___________________________________________________ 62
9 Subreports ______________________________________________________63
9.1 Subreport Parameters ______________________________________________ 65
9.2 Subreport Data Source _____________________________________________ 66
10 Advanced JasperReports _________________________________________67
10.1 XML Report Designs Loading and Writing ____________________________ 67
10.2 Implementing Data Sources _________________________________________ 67
10.3 Customizing Viewers _______________________________________________ 68
10.4 Exporting to New Output Formats____________________________________ 68
The JasperReports Ultimate Guide
Page 4
1 Introduction
The JasperReports library is a very powerful and flexible report-generating tool that has the ability to
deliver rich content onto the screen, to the printer or into PDF, HTML or XML files. Hopefully, in the
future, other output formats such as CSV, XLS, RTF and other will be supported.
The library is entirely written in Java and can be used in a variety of Java enabled applications,
including J2EE or Web applications, to generate dynamic content. Its main purpose is to help creating
page oriented, ready to print documents in a simple and flexible manner.
JasperReports organizes data according to the report design defined in an XML file. This data may
come from various data sources including relational databases, collections or arrays of Java objects.
Users can plug the reporting library to custom made data sources, by implementing a simple interface,
as you will see later in this book.
In order to fill a report with data, the XML report design must be compiled first. Through compilation,
a report design object is generated and then serialized in order to store it on disk or send it over the
network. This serialized object is then used when the application wants to fill the specified report
design with data. In fact, the compilation of a report design implies the compilation of all Java
expressions defined in the XML file representing the report design. Various verifications are made at
compilation time, to check the report design consistency. The result is a ready to fill report design that
will be then used to generate documents on different sets of data.
To fill a report design, the engine needs to receive the report data. This may come in various forms.
Some of this data can be passed in as report parameters. But most of the data will be found in the report
data source. The reporting engine can directly receive special data source objects from which to get the
information to put on the report, or can deal itself with a supplied JDBC connection object, if that data
is located in a relational database.
The result of the report filling operation is a new object that represents the ready to print document.
This one is also serialized for storage on disk or network transfer. It can be viewed directly using the
JasperReports built-in viewer or can be exported to other, more popular formats like PDF, HTML or
XML.
The JasperReports Ultimate Guide
Page 5
2 API Overview
Most of the time, when using the JasperReports library, people will get to work only with a few classes
and won't have to get to know the entire API, in order to benefit from all its features and functionality.
In this section we shall get a close look at the classes and interfaces which are significant when using
the library and see how to make use of them in applications that need the reporting functionality that
JasperReports offer.
- figure 1 -
Class dori.jasper.engine.design.JasperDesign
We begin with this class because instances of it represent the raw material, which the JasperReports
library uses for report generating purposes. Such instances are obtained after the XML report design
files are parsed by the library internal XML parsing procedures, for example, but can be build
programmatically, by the application that uses JasperReports, if working with XML files is not an
option. Among the supplied samples that come with the project source files, there is one called
noxmldesign that you can check to see how to dynamically create a
dori.jasper.engine.design.JasperDesign object without editing an XML report design file.
All instances of the dori.jasper.engine.design.JasperDesign class are subject to compilation
before being used for filling and report generation. This is why they are considered the raw material for
the library.
Class dori.jasper.engine.JasperReport
Instances of this class represent compiled report design objects. These can be obtained only as a result
of the JasperReports report compilation process and are ready to use for filling with data and report
generation.
Through compilation, along with various consistency checks and rearrangements of the report elements
for more rapid later utilization, the library creates a temporary class file containing all the report
expressions such as report variables expressions, text field and image expressions, group expressions,
etc.
This temporary Java source file is compiled on the fly using either the Java compiler classes from the
JDK used to run the application. If the
tools.jar file is not found in the classpath in order to do that,
the compilation will go ahead anyway by launching at runtime the
javac.exe compiler, behind the
scenes. The bytecodes of the resulting class file are stored in the resulting
dori.jasper.engine.JasperReport for using when filling the report with data, to evaluate the
various report expressions at runtime.
JasperDesign
JasperReport JasperPrintXML
PDF
XML
HTML
Screen
Printer
JRXmlLoader JRCompiler
JasperCompileManager
JasperFillManager
parse compile
fill
JasperPrintManager
JasperExportManager
print
export
