Java Bytecode Assembly, Interesting concepts in the art of Computer Science/Software Development, maybe from time to time other pesky corp. related development issues.

Tuesday, December 15, 2009

Jasper Reports - Subreport usage demonstration

This post is part of Jasper Reports demo documentation project, please read that post for information on downloading the discussed demo files


This demonstration will teach you how to reuse sub-reports for enhancing report visual layout. Subreports among other things allow you to achieve high level of data presentation complexity with relatively small overhead.

a Subreport in Jasper terminology is single jrxml report file which is designed to be included in a master report, the master report should pass parameters to the subreport (For ex. rowId or street address) which are accessed by the subreport using $P{"parameterName"} notation. Optional feature for subreport is return parameters which allow passing information from calculations done within the subreport back to the master report, under the hood these are variables which are defined in the master report and passed to the subreport element (we will see an example of this later in the post).

Lets start with the basics setup required to get the report demo running:

First you will need to start the hsqldb database.

Next open all 3 reports in iReports.
  • MasterReport.jrxml
  • ProductReport.jrxml
  • AddressReport.jrxml

Test the report is working:
  1. In iReports, assuming you followed the hsqlsdb setup guide you should select "jdbc:hsqldb:hsql://localhost" as your datasource.
  2. Make sure you have focus on the MasterReport tab
  3. Now click "Preview"
    1. In the popup windows select "Use Default"
This should bring a semi-working report that looks something like this:

To configure a fully functional we will need to do some adjustment steps, as we are operating the report from iReport instead from Java code.

MasterReport has has a parameter called ProductsSubreport of type net.sf.jasperreports.engine.JasperReport this parameter can be used in production environment to dynamically supply the subreport Class Instance that will be used by one of this subreport elements (more on this later). For now, lets change this to supply a fixed sub report element so that we can preview the full report in iReports as Jasper team designed it.

Locate in iReports the element's:
  1. MasterReport -> Details 1 -> $P{ProductsSubreport} then set the following fields:

    • Subreport Expression = "ProductReport.jasper"
    • Expression Class = java.lang.String

  2. MasterReport -> Parameters -> ProductsSubreport then set the following fields:

    • Use as a prompt = [ ] (unselected)

Now if you try to preview the report again the following will be shown:

Good! The report is fully operation. Lets start analyzing.

Understanding Report logical Structure

This report prints product orders grouped by city. The report layout is as following:

== Report Title =
 Heading + Total number of orders
== Page Title ==
Page Heading
== Details ==
= First page =
City name     COUNTER: Number of address ordered in this city
= Next n pages =
City name     cont

Then 2 lists order side by side displaying:
First list =  Products ordered by people in current city
Second list = Address that made orders in current city

== Page Footer ==
Page X out of XXX

Understanding Report JRXML structure

Master Report :: Query
The main report is based on the following SQL query: SELECT City FROM Address GROUP BY City ORDER BY City which should self explentionary.

Master Report -> Title
This section contains static text and a graphical horizontal bar.

Pay attention to the Text Field that as part of his expression uses the dynamically calculated variable $V{ProductTotalPrice} this variable is returned from the sub reports called during report filling phase and the results are summarized by the engine. More on this later.

Master Report -> Page Header 
Nothing special here. Static text that will be printed at the start of each page.

Master Report -> Details 1

The heart of the report.

It is important to understand that a details band can grow beyond single page size, Jasper has special treatment for these situation via settings which can be set on each element as we shall see next:

On the first page we want to print "CityName"  COUNTER Addresses, on the following pages for the same city OTOH all we want to print is "CityName"  cont

The idea is that if a city band grows to several pages we will reprint the "CityName" and the text "Cont"

TextField $F{City} has the setting Print Repeated Values and Print When Details Overflows which causes it repeat on each page, even when the band for current city grows beyond 1 page size.

TextField $V{CityAddressCount} + " addresses" has the setting Print Repeated Values which will allow this field to be printed even if 2 cities have the same number of addresses but note this Print When Details Overflows is turned off which causes this text to be printed only on the first page of the band !

Label (continued) has the setting Print Repeated Values turned off and Print When Details Overflows enabled. This cause this label to be printed only on overflowed bands (meaning only on 2nd pages and following...).

Subreport $P{ProductsSubreport} is the embedding of the ProductReport subreport. Note this report gets the Database connection from the MasterReport, we also pass a parameter to this report City = $F{City}. This report returns a variable, the way this is implement in Jasper Reports is as following: We define a variable in the master report ProductTotalPrice, then we pass this variable to the subreport which sets values into this variable. Then, after the subreport evaluation has ended in the MasterReport we can use this variables value. In the present context we use this method to calculate a summary (TOTAL) of the price of all the products being evaluated by the subreport. Note that as part of the definition of the variable on the subreport element we configure Calculation Type = Sum this allows the engine to do the summary of this variable (which is passed to many subreport's - A subreport is evaluated for each city). See Variables section for another note on the ProductTotalPrice variable.

Master Report -> Variables

ProductTotalPrice this variable is used by the MasterReport to display the sum of the price of all products that have been evaluated by the subreport ProductReport note this variable has the property Calculation = System meaning that it is being manipulated separately (not by the engine). This is actually a little hack (IMHO) because we do sum it using the engine only we do it on the Subreport $P{ProductsSubreport} variable configuration properties. Just in case you wondered: Yes! it works.

To be continued...
To be continued...

Monday, December 14, 2009

Jasper Reports hsqldb database setup

This post is part of Jasper Reports demo documentation project, please read that post for information on downloading the discussed demo files
Jasper Report distribution comes with a sample database populated with data which proves to be as useful as it can be for running the supplied demo reports / testing concepts before implementing in production environments.

To use this database you will need to
  1. Have it up and running
  2. Configure the connection in iReports

On a linux box this is straight forward as explained below (Win/OSX and others should have similar guide lines).

Have HSqlDB it up and running

// Demonstrated for iReports, JasperReports v3.7.0

Open up a terminal windows and issue the following commands:

$ cd JasperReports/jasperreports-3.7.0/demo/hsqldb/
$ ant

You will see output similar to this
Buildfile: build.xml

[java] [Server@15c7850]: [Thread[main,5,main]]: checkRunning(false) entered
[java] [Server@15c7850]: [Thread[main,5,main]]: checkRunning(false) exited
[java] [Server@15c7850]: Startup sequence initiated from main() method
[java] [Server@15c7850]: Loaded properties from [/home/maximv/Desktop/JasperReports/jasperreports-3.7.0/demo/hsqldb/]
[java] [Server@15c7850]: Initiating startup sequence...
[java] [Server@15c7850]: Server socket opened successfully in 4 ms.
[java] [Server@15c7850]: Database [index=0, id=0, db=file:test, alias=] opened sucessfully in 607 ms.
[java] [Server@15c7850]: Startup sequence completed in 612 ms.
[java] [Server@15c7850]: 2009-12-14 18:32:33.542 HSQLDB server 1.8.0 is online
[java] [Server@15c7850]: To close normally, connect and execute SHUTDOWN SQL
[java] [Server@15c7850]: From command line, use [Ctrl]+[C] to abort abruptly

That's it. Keep the terminal window open otherwise the DB will shutdown. The database can be accessed locally using the

Path: jdbc:hsqldb:hsql://localhost
Username: sa
Password: "" (blank, no password).

Configure the HSqlDB connection in iReports

In iReports the setup is as follows:
  1. Click the new data source connection button:

  2. Click the new connection

  3. Configure connection to the hsqldb datasource

    That is

    JDBC Driver = HSQLDB (server) (org.hsqldb.jdbcDriver)
    JDBC URL = jdbc:hsqldb:hsql://localhost

    Username = sa
    Password =        ([V] Save password)

  4. Test the connection is working.

    After configuring the connection you should click the "Test" button, if everything goes well the following popup windows will confirm this.

Jasper Reports demo documentation project

Jasper Reports is one of several well known and well established open source reporting frameworks.

One thing it lacks badly is good documentation, I believe it's a safe claim that anything beyond the regular most basic report structure will throw you straight into googling, example files and forum posts. iReport will help, documentation will be somewhat helpful as well, but do be prepared for the moment when even these paths fail, that's when you will stand at the face of either commercial support or diving into the code of the engine.

Downloading the demo jrxml files

To help the community a little bit, I'm starting a little documentation project for the examples supplied with Jasper Reports source distribution which can be obtained by checking out the source code or by downloading the latest dist from here. All this in the hope to lower the learning curve and allow easier adoption by casual report dev folks.

Several more source of information for Jasper Report Developers

Jasper Reports Demo files Index

Written guides are hyper-linked - This is work in progress I will be editing this post as more guides are published.

[maximv@mldev2 JasperReports]$ find jasperreports-3.7.0/demo/samples/ -maxdepth 1 -mindepth 1 -type d | sort
  • jasperreports-3.7.0/demo/samples/alterdesign
  • jasperreports-3.7.0/demo/samples/antcompile
  • jasperreports-3.7.0/demo/samples/barbecue
  • jasperreports-3.7.0/demo/samples/barcode4j
  • jasperreports-3.7.0/demo/samples/batchexport
  • jasperreports-3.7.0/demo/samples/beanshell
  • jasperreports-3.7.0/demo/samples/charts
  • jasperreports-3.7.0/demo/samples/chartthemes
  • jasperreports-3.7.0/demo/samples/crosstabs
  • jasperreports-3.7.0/demo/samples/csvdatasource
  • jasperreports-3.7.0/demo/samples/datasource
  • jasperreports-3.7.0/demo/samples/ejbql
  • jasperreports-3.7.0/demo/samples/fonts
  • jasperreports-3.7.0/demo/samples/genericelement
  • jasperreports-3.7.0/demo/samples/groovy
  • jasperreports-3.7.0/demo/samples/hibernate
  • jasperreports-3.7.0/demo/samples/horizontal
  • jasperreports-3.7.0/demo/samples/hyperlink
  • jasperreports-3.7.0/demo/samples/i18n
  • jasperreports-3.7.0/demo/samples/images
  • jasperreports-3.7.0/demo/samples/jasper
  • jasperreports-3.7.0/demo/samples/java1.5
  • jasperreports-3.7.0/demo/samples/javascript
  • jasperreports-3.7.0/demo/samples/jcharts
  • jasperreports-3.7.0/demo/samples/jchartscomponent
  • jasperreports-3.7.0/demo/samples/jexcelapi
  • jasperreports-3.7.0/demo/samples/jfreechart
  • jasperreports-3.7.0/demo/samples/landscape
  • jasperreports-3.7.0/demo/samples/list
  • jasperreports-3.7.0/demo/samples/markup
  • jasperreports-3.7.0/demo/samples/mondrian
  • jasperreports-3.7.0/demo/samples/nopagebreak
  • jasperreports-3.7.0/demo/samples/noreport
  • jasperreports-3.7.0/demo/samples/noxmldesign
  • jasperreports-3.7.0/demo/samples/openflashchart
  • jasperreports-3.7.0/demo/samples/pdfencrypt
  • jasperreports-3.7.0/demo/samples/poi-3.5
  • jasperreports-3.7.0/demo/samples/printservice
  • jasperreports-3.7.0/demo/samples/query
  • jasperreports-3.7.0/demo/samples/rotation
  • jasperreports-3.7.0/demo/samples/scriptlet
  • jasperreports-3.7.0/demo/samples/shapes
  • jasperreports-3.7.0/demo/samples/stretch
  • jasperreports-3.7.0/demo/samples/styledtext
  • jasperreports-3.7.0/demo/samples/subreport
  • jasperreports-3.7.0/demo/samples/table
  • jasperreports-3.7.0/demo/samples/tableofcontents
  • jasperreports-3.7.0/demo/samples/templates
  • jasperreports-3.7.0/demo/samples/text
  • jasperreports-3.7.0/demo/samples/unicode
  • jasperreports-3.7.0/demo/samples/virtualizer
  • jasperreports-3.7.0/demo/samples/webapp
  • jasperreports-3.7.0/demo/samples/xlsdatasource
  • jasperreports-3.7.0/demo/samples/xlsformula
  • jasperreports-3.7.0/demo/samples/xmldatasource

About Me

My photo
Tel Aviv, Israel
I work in one of Israel's Hi-Tech company's. I do 5 nines system development with some system administration. This blog will focus on the technical side of things, with some philosophical strings attached.