JasperReports Library - Tutorial

In order to fill a report-design, one can use the fillReportXXX() methods exposed by the JasperFillManager class. Those methods receive as a parameter the report-design object, or a file representing the specified report-design object, in a serialized form, and also a JDBC connection to the database from which to retrieve the data to fill the report with. The result is an object that represents a ready-to-print document ( JasperPrint class) and that can be stored on disk in a serialized form (for later use), can be delivered to the printer or to the screen, or can be exported into a PDF, HTML, XLS, RTF, ODT, CSV, TXT or XML document.

As you can see, the main classes to use when working with JasperReports are:

• net.sf.jasperreports.engine.JasperCompileManager
• net.sf.jasperreports.engine.JasperFillManager
• net.sf.jasperreports.engine.JasperPrintManager
• net.sf.jasperreports.engine.JasperExportManager

These classes represent a facade to the JasperReports engine. They have various static methods that simplify the access to the API functionality and can be used to compile an JRXML report design, to fill a report, to print it, or to export to other document formats (PDF, HTML, XML).

In addition to these facade classes, you will also get to work directly with specific exporter classes, in case you need to export your reports to XLS, RTF, ODT, TXT or other document formats for which there is no corresponding helper method in the JasperExportManager, or when you need to configure the export process and adapt it to your specific needs. These exporter implementations can be found in the net.sf.jasperreports.engine.export package of the JasperReports library.

If you need to display the report inside a Swing application, you can use the JRViewer component that is shipped with the library and consists of an embeddable and configurable javax.swing.JPanel component. The JasperViewer is a stand-alone Swing application that uses the JRViewer component to display reports in proprietary format (serialized JasperPrint objects) or in XML format. To help with the report design work, JasperReports provides a report design previewer in the JasperDesignViewer class.

Report Designs

As mentioned, a report design represents a template that will be used by the JasperReports engine to deliver dynamic content to the printer, to the screen or to the Web. Data stored in the database is organized according to the report design to obtain ready to print, page oriented documents. The report designs are defined in JRXML files and must have a special structure. This structure is declared in a DTD file supplied with the JasperReports engine. The JRXML files are then compiled, in order to use them in report filling operations.

To create a simple report design, we have to edit an XML file with the following structure:

<!--?xml version="1.0"?-->
<jasperreport ...="" name="name_of_the_report"
                     xmlns="http://jasperreports.sourceforge.net/jasperreports"
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     xsi:schemalocation="http://jasperreports.sourceforge.net/jasperreports http://jasperreports.sourceforge.net/xsd/jasperreport.xsd">
    ...
</jasperreport>

To have a better understanding of the structure of a JRXML file, or of a report design in general, we recommend you to use the Quick Reference.

Compiling Report Designs

A report design is represented by a JRXML file that has the structure defined in the jasperreport.dtd file, or by an in-memory JasperDesign object. In order to generate reports according to such a report design, this needs to be compiled. Report design compilation can be done using the compileReportXXX() methods exposed by the JasperCompileManager class and results into a *.jasper file or a JasperReport object.

When compiling a report design, the engine first performs a validation to ensure that the template (JasperDesign) is consistent and then transforms all the report expressions in a ready-to-evaluate form, storing them inside the resulting compiled report template (JasperReport or .jasper file).

This transformation implies either the on-the-fly compilation of a Java class file that will be associated with the report template, or the generation of a Groovy or BeanShell script to use when evaluating report expressions during the report filling process, depending on the specified report expression language for the report (see the language property of a report template).

Before reading more about report compilation, you should understand when do you need to compile your report templates and which is the best way to do it by reading the following FAQ:

When should I compile my report templates and how?.

To make report design compilation process as flexible as possible, a special interface called JRCompiler was introduced.

As seen above, there are several different types of classes implementing this interface shipped with the library:

1. Java creport compilers. These report compilers generate and compile a Java class containing the report expressions evaluating methods; \
2. The Groovy report compiler that generates a script for runtime report expressions evaluation.
3. The BeanShell report compiler that generates a script for runtime report expressions evaluation.

For more details about report compilation, check The Definitive Guide to JasperReports.

Ant task for compiling report designs

Since the report design compilation process is more like a design-time job than a runtime one, an Ant task was provided with the library in order to simplify development.

This Ant task is implemented by the JRAntCompileTask and is very similar to the <javac> Ant built-in task, as far as syntax and behavior are concerned.

The report design compilation task can be declared like this, in a project's build.xml file:

<taskdef classname="net.sf.jasperreports.ant.JRAntCompileTask" name="jrc">
    <classpath>
        <fileset dir="./lib">
            <include name="**/*.jar" />
        </fileset>
    </classpath>
</taskdef>

In the example above, the lib folder should contain the jasperreports-<version>.jar file along with its required libraries (including the jdt-compiler-<version>.jar, which is the recommended report compiler, in case you use Java as the report expression language).

This user-defined Ant task can be then used to compile multiple JRXML report design files in a single operation, by specifying the root directory that contains those files or by selecting them using file patterns. Attributes of the report design compilation task:

The report design compilation task supports nested <src> and <classpath> elements, just like the Ant <javac> built-in task.

To see this in action, check the demo/samples/antcompile sample provided with the project source files.

Viewing a report design

Report designs can be viewed using the JasperDesignViewer application.

In its main() method, it receives the name of the file which contains the report design to view.

This can be the JRXML file itself, or the compiled report design (*.jasper file).

Filling Reports

A compiled report design can be used to generate reports by calling the fillReportXXX() methods of the JasperFillManager class. There are two flavours of the fill methods in this façade class. Some receive a java.sql.Connection object as the third parameter, and the others receive a JRDataSource object instead.

This is because most of the times reports are filled with data from a relational database to which we connect through JDBC and is very convenient to have the SQL query inside the report template itself. The JasperReports engine can use the connection passed in and execute the SQL query, thus producing a report data source for filling the report.

In cases where data is available in other forms, the fill methods receiving a data source are to be used.

View, Print and Export Reports

Generated reports can be viewed using the JasperViewer application. In its main() method, it receives the name of the file which contains the report to view.

Generated reports can be printed using the printReport(), printPage() or printPages() static methods exposed by the JasperPrintManager class.

After having filled a report, we can also export it in PDF, HTML or XML format using the exportReportXXX() methods of the JasperExportManager class.

Parameters

Parameters are object references that are passed-in to the report filling operations. They are very useful for passing to the report engine data that it can not normally find in its data source. For example, we could pass to the report engine the name of the user that has launched the report filling operation if we want it to appear on the report, or we could dynamically change the title of our report.

An important aspect is the use of report parameters in the query string of the report, in order to be able to further customize the data set retrieved from the database. Those parameters could act like dynamic filters in the query that supplies data for the report.

Declaring a parameter in a report design is very simple and it requires specifying only its name and its class:

 <parameter class="java.lang.String" name="ReportTitle" />
 <parameter class="java.lang.Integer" name="MaxOrderID" />
 <parameter class="java.awt.Image" name="SummaryImage"  />

There are two possible ways to use parameters in the query:

1. The parameters are used like normal java.sql.PreparedStatement parameters using the following syntax:

   SELECT * FROM Orders WHERE CustomerID = $P{OrderCustomer}
   

2. Sometimes is useful to use parameters to dynamically modify portions of the SQL query or to pass the entire SQL query as a parameter to the report filling routines. In such a case, the syntax differs a little, like in the following example:

   SELECT * FROM Orders ORDER BY $P!{OrderByClause}
   

   There are also the following built-in system parameters, ready to use in expressions:

   Parameter Name	Description
   REPORT_PARAMETERS_MAP	This parameter will contain a map with all user defined and built-in parameters
   REPORT_PARAMETERS_MAP	This parameter will contain a map with all user defined and built-in parameters
   REPORT_CONNECTION	A user supplied java.sql.Connection used for JDBC datasources
   REPORT_DATA_SOURCE	A user supplied instance of JRDataSource representing either one of the built-in data source types or a user-defined one
   REPORT_MAX_COUNT	An integer allowing users to limit the datasource size
   REPORT_SCRIPTLET	A JRAbstractScriptlet containing an instance of the report scriptlet provided by the user
   REPORT_LOCALE	A java.util.Locale instance containing the resource bundle desired locale
   REPORT_RESOURCE_BUNDLE	The java.util.ResourceBundle containing localized messages
   REPORT_TIME_ZONE	A java.util.TimeZone instance to use for date formatting
   REPORT_VIRTUALIZER	The JRVirtualizer object to be used for page virtualization
   REPORT_CLASS_LOADER	A java.lang.ClassLoader instance to be used during the report filling process to load resources such as images, fonts and subreport templates
   IS_IGNORE_PAGINATION	If set to java.lang.Boolean.TRUE the report will be generated on one long page and page break will not occur

Data Source

JasperReports support various types of data sources using a special interface called JRDataSource.

There is a default implementation of this interface, the JRResultSetDataSource class, which wraps a java.sql.ResultSet object. It allows the use of any relational database through JDBC.

When using a JDBC data source, you could pass a java.sql.Connection object to the report filling operations and specify the query in the report definition itself (see the element in the XML file) or could create a new instance of the JRResultSetDataSource by supplying the java.sql.ResultSet object directly.

With other types of data sources, things should not be different and all you have to do is to implement the JRDataSource interface, or use one of the implemetations that are shipped with the JasperReports library to wrap in-memory collections or arrays of JavaBeans, CSV or XML files, etc.

Fields

Report fields represent the only way to map data from the data source into the report generating routines. When the data source of the report is a java.sql.ResultSet, all fields must map to corresponding columns in the java.sql.ResultSet object. That is, they must have the same name as the columns they map and a compatible type.

For example:

If we want to generate a report using data retrieved from the table Employees, which has the following structure:

We can define the following fields in our report design:

 <field class="java.lang.Integer" name="EmployeeID" />
 <field class="java.lang.String"  name="LastName"   />
 <field class="java.lang.String"  name="FirstName"  />
 <field class="java.util.Date"    name="HireDate"   />

If we declare a field that does not have a corresponding column in the java.sql.ResultSet, an exception will be thrown at runtime. Columns present in the java.sql.ResultSet object that do not have corresponding fields in the report design do not affect the report filling operations, but they also won't be accessible.

Expressions

Expressions are a powerful feature of JasperReports. They can be used for declaring report variables that perform various calculations, for data grouping on the report, to specify report text fields content or to further customize the appearance of objects on the report.

Basically, all report expressions are Java expressions that can reference report fields and report variables.

In an XML report design there are several elements that define expressions:

  <variableexpression> , <initialvalueexpression> , <groupexpression> , <printwhenexpression> , <imageexpression> and <textfieldexpression>

In order to use a report field reference in an expression, the name of the field must be put between $F{ and } character sequences.

For example, if we want to display in a text field, on the report, the concatenated values of two fields, we can define an expression like this one:

<textfieldexpression>
    $F{FirstName} + " " + $F{LastName}
</textfieldexpression> 

The expression can be even more complex:

<textfieldexpression>
    $F{FirstName} + " " + $F{LastName} + " was hired on "
    + (new SimpleDateFormat("MM/dd/yyyy")).format($F{HireDate}) + "."
</textfieldexpression>

To reference a variable in an expression, we must put the name of the variable between $V{ and } like in the example below:

<textfieldexpression>
    "Total quantity : " + $V{QuantitySum} + " kg." 
</textfieldexpression>

There is an equivalent syntax for using parameters in expressions. The name of the parameter should be put between $P{ and } like in the following example:

<textfieldexpression>
    "Max Order ID is : " + $P{MaxOrderID} 
</textfieldexpression>

Variables

A Report variable is a special objects build on top of an expression. Variables can be used to simplify the report design by declaring only once an expression that is heavily used throughout the report design or to perform various calculations on the corresponding expressions.

In its expression, a variable can reference other report variables, but only if those referenced variables were previously defined in the report design. So the order in which the variables are declared in a report design is important.

As mentioned, variables can perform built-in types of calculations on their corresponding expression values like : count, sum, average, lowest, highest, variance, etc.

A variable that performs the sum of the Quantity field should be declared like this:

<variable calculation="Sum" class="java.lang.Double" name="QuantitySum">
    <variableexpression>
        $F{Quantity}
    </variableexpression> 
</variable>

For variables that perform calculation we can specify the level at which they are reinitialized. The default level is Report and it means that the variable is initialized only once at the beginning of the report and that it performs the specified calculation until the end of the report is reached. But we can choose a lower level of reset for our variables in order to perform calculation at page, column or group level.

For example, if we want to calculate the total quantity on each page, we should declare our variable like this:

<variable calculation="Sum" class="java.lang.Double" name="QuantitySum" resettype="Page" > 
    <variableexpression>
        $F{Quantity}
    </variableexpression>
    <initialvalueexpression>
        new Double(0)
    </initialvalueexpression>
</variable>

Our variable will be initialized with zero at the beginning of each new page.

There are also the following built-in system variables, ready to use in expressions:

• PAGE_NUMBER
• COLUMN_NUMBER
• REPORT_COUNT
• PAGE_COUNT
• COLUMN_COUNT
• GroupName_COUNT

Report Sections

When building a report design we need to define the content and the layout of its sections. The entire structure of the report design is based on the following sections:

Sections are portions of the report that have a specified height and width and can contain report objects like lines, rectangles, images or text fields.

When declaring the content and layout of a report section in an XML report design we use the generic element .

This is how a page header declaration should look. It contains only a line object and a static text:

<pageheader>
    <band height="30">
        <rectangle>
            <reportelement height="25" width="555" x="0" y="0"></reportelement>
            <graphicelement></graphicelement>
        </rectangle>
        <statictext>
            <reportelement height="25" width="555" x="0" y="0"></reportelement>
            <textelement textalignment="Center"></textelement>
            <text>Northwind Order List</text>
        </statictext>
    </band>
</pageheader>

Frames

Sometimes a group of elements have to share a common background or have a common border around them. This was achieved by putting a rectangle behind them, but it did not work with the grid exporters since overlapping elements are not supported there.

The new frame element is recognized by the grid exporters and can be used to group elements together by nesting them inside a frame. Frames can be nested on an unlimited number of levels.

Groups

Groups represent a flexible way to organize data on a report. When filling a report, the JasperReports engine tests all the defined group expressions to see whether a group rupture has occurred and if so it introduces the corresponding <groupfooter> and <groupheader> sections on the report.

We can have as many groups as we want on a report. The order of groups declared in a report design is important because groups contain each other. One group contains the following group and so on. When a larger group encounters a rupture, all subsequent groups are reinitialized.

When declaring a report group, along with its corresponding data grouping expression, we have to declare the two sections: the group's header section and the group's footer section.

See the Jasper Sample report for an example on how to define groups.

Fonts and Unicode Support

Now you can create your reports in any language!

New attributes in the element where introduced to allow the mapping between the Java fonts and the PDF fonts. PDF uses special font settings and there was no way to make use of them in the previous version of JasperReports. With the introduction of those new attributes, the users can specify what PDF specific font should be used to display different character sets (pdfFontName attribute), what is the type of the encoding (pdfEncoding attribute) and whether the font should be embedded in the PDF document or not (isPdfEmbedded).

To simplify the use of the font settings, a new element was introduced: .

Report fonts are report level font definitions that ca be used as default or base font settings in other font definitions throughout the entire report. Since the support for international characters is somehow tied to the iText library, you can find more details about how to create PDF documents in different languages and different character sets in the iText documentation.

Styles

Report styles were introduced in order to group together a set of visual properties that would then be applied to report elements that reference the report style. This new concept is an extension of the former report font concept which is now deprecated. Report elements that reference a report style definition could override the values of any visual property defined in the style.

Report styles could also reference other report styles and the same inheritance and override mechanism applies to them too. Styles are useful when a whole range of elements need to share the same visual properties and any change made to that has to apply to all of them. This can be achieved by changing the report style they all reference.

Scriptlets

All the data displayed on a report comes from the report parameters and from the report fields. This data can be processed using the report variables and their expressions.

There are specific moments in time when variable processing occurs. Some variables are initialized according to their reset type when the report starts, or when a page or column break is encountered, or when a group changes. Furthermore, variables are evaluated every time new data is fetched from the data source (for every row).

But only simple variable expressions cannot always implement complex functionality. This is where scriptlets intervene.

Scriptlets are sequences of Java code that are executed every time a report event occurs. Through scriptlets, users now have the possibility to affect the values stored by the report variables.

Since scriptlets work mainly with report variables, is important to have full control over the exact moment the scriptlet is executed. JasperReports allows the execution of custom Java code BEFORE or AFTER it initializes the report variables according to their reset type: Report, Page, Column or Group.

In order to make use of this functionality, users only have to create a scriptlet class by extending JRAbstractScriptlet class or JRDefaultScriptlet class. The name of this custom scriptlet class has to be specified in the scriptletClass attribute of the <jasperreport> element.

When creating a JasperReports scriptlet class, there are several methods that developers should implement or override, like: beforeReportInit(), afterReportInit(), beforePageInit(), afterPageInit(), beforeGroupInit(), afterGroupInit(), etc. Those methods will be called by the report engine at the appropriate time, when filling the report.

There is a default report parameter called REPORT_SCRIPTLET which represent a reference to the scriptlet object instantiated by the report engine when filling the report. It can be used in expressions throughout the report, to call custom methods on the scriptlet object, making the whole mechanism even more flexible.

And that is all!

See the ScriptletReport sample for more details.

Subreports

Subreports are an important feature for a report-generating tool. They allow the creation of more complex reports and simplify the design work.

Subreports are very useful when creating master-detail type of reports, or when the structure of a single report is not sufficient to describe the complexity of the desired output document.

A subreport is in fact a normal report incorporated into another report. One can overlap subreports or create subreports containing subreports themselves, up to any nesting level. Any report template can be used as a subreport when incorporated into another report, without anything inside it having to change.

Like other report elements, the subreport element has an expression that is evaluated at runtime in order to obtain the source of the JasperReport object to load.

There are two ways to supply parameter values to a subreport. First, you can use the element which introducest the expression that will be evaluated to produce the specified parameters map. And/or you can supply the parameters individually using a <subreportparameter> element for each relevant parameter. When using simultaneously both ways to supply parameters the parameters values specified using <subreportparameter> will override values specified with <parametersmapexpression>.

Subreports require a data source in order to generate their content, just like normal reports, behave in the same way, and expect to receive the same kind of input when they are being filled.

Values calculated by a subreport can be returned to the parent report. More specifically, after a subreport is filled, values of the subreport variables can be either copied or accumulated (using an incrementer) to variables of the caller report (master variables).

See the Subreport sample for details.

Internationalization

JasperReports allows associating a java.util.ResourceBundle with the report design, either at runtime, by using the new resourceBundle attribute or at runtime, by providing a value for the REPORT_RESOURCE_BUNDLE built-in parameter.

If the report needs to be generated in a locale that is different from the current locale, then the built-in REPORT_LOCALE parameter should be used to specify the runtime locale when filling the report.

In order to ease the internationalization of the reports there is a special syntax available inside report expressions that allows referencing String resources placed inside a java.util.ResourceBundle object associated with the report. The $R{...} syntax is for wrapping resource bundle keys in order to retrieve the value for that key.

For formatting messages in different languages, based on the report locale, there is a built-in method inside the JRCalculator associated with the report that offers functionality similar to the java.text.MessageFormat class. This method is called msg() and has 3 convenience signatures that allow using up to 3 message parameters in the messages. There is also the build-in str() method which is the equivalent of the $R{...} syntax inside the report expressions, giving access to the resource bundle content based on the report locale.

In the generated output, the library now keeps information about the text run direction so that documents generated in languages that have right-to-left writing (like Arabic and Hebrew) could be rendered properly.

Check the I18nReport and UnicodeReport samples for details.

Datasets

Charts and crosstabs sometimes need to use data which the containing report does not iterate though directly at fill time. This would be the case with data sources that have fields which could themselves be data sources for subreports.

In order to eliminate the need to use subreports to render a chart or a crosstab that would be fed with the nested data, a new concept called a dataset was introduced. A dataset is something between a data source and a subreport because it contains parameters, fields, variables and groups, but no layout information. Check /demos/samples/charts and the Crosstabs sample.

Charts

JasperReports now has built-in support for charts. There is a new, ready-to-use chart component, although we already had images, text fields, subreports and other elements. This greatly simplifies the way charts are included inside reports, because previously the user had to completely rely on scriptlets in order to gather the chart data and render the chart using an image element in the report template.

Now with the new chart component, the user only has to make the desired visual settings and define the expressions that will help the engine build up the chart dataset in an incremental fashion during the iteration through the report data source.

When including and configuring a chart component, there are three entities involved:

• the overall chart component;
• the chart dataset (groups chart data related settings);
• the chart plot (groups visual settings related to the way the chart items are rendered)

JasperReports currently supports the following types of charts:

Pie, Pie 3D, Bar, Bar 3D, XY Bar, Stacked Bar, Stacked Bar 3D, Line, XY Line, Area, XY Area, Scatter Plot, Bubble, Time series, High Low Open Close, Candlestick.

These types of charts use several types of datasets (each type of chart works with certain types of datasets): Pie Dataset, Category Dataset, XY Dataset, Time Series, Time Period Values, XYZ Dataset, High Low Dataset.

For all charts we can configure the following:

• border around all sides
• background color
• title
• title position (top, left, bottom, right)
• title font
• title color
• subtitle
• subtitle font
• subtitle color
• show/hide legend
• plot area background color
• plot area background transparency (alpha)
• plot area foreground transparency (alpha)
• plot orientation (vertical, horizontal)
• axis labels

For all datasets we can configure:

• increment type (detail, column, page, group, report)
• increment group
• reset type (none, column, page, group, report)
• reset group

Specific settings by chart type:

• Pie 3D
  • depth factor
• Bar, XY Bar, Stacked Bar
  • hide/show labels
  • hide/show tick marks
  • hide/show tick labels
• Bar 3D, Stacked Bar 3D
  • hide/show labels
  • x offset (3D effect)
  • y offset (3D effect)
• Line, XY Line, Scatter Plot, Time series
  • hide/show lines
  • hide/show shapes
• Bubble
  • scale type (both axes, domain axis, range axis)
• High Low Open Close
  • hide/show close ticks
  • hide/show open ticks
• Candlestick
  • hide/show volume

JasperReports uses the JFreeChart library to render the charts. Details about how to use this functionality can be found in the supplied JFreeChart Sample.

Crosstabs

Crosstabs are a special type of table component in which both the rows and the columns are dynamic. They are used to display aggregated data using tables with multiple levels of grouping for both columns and groups.

For more details, check the crosstabs sample provided.