Jasper Reports - working with beans and sub report

Introduction

I recently had to research how to use JasperReports (refer. 1) to produce PDF, rich text format (RTF), and Excel reports using an ArrayList collection of Java objects as the source for the data in the report. The main Java class has as one of its attributes an ArrayList collection of another Java object. I had the challenge of figuring out how to include all the data from the nested ArrayList collection in the report. After several frustrating hours researching this issue in the very limited JasperReports documentation and on the JasperReports forums I found a hint that lead me to a solution.

Since there does not appear to be very good documentation on how to use complex collections as the data source for a JasperReport, I decided to write a blog entry that will hopefully help others in the future (and of course remind me how I did this when I have to do it again in six months).

JasperReports

If you visit the JasperReports website you can find information about what JasperReports does. Basically it's a comprehensive package of Java classes that enables you to use various sources as data used to create a variety of report types including PDF, Excel, and RTF. There is an open-source community edition of JasperReports that you can download (refer. 2). As of July 6, the version was JasperReports 3.0.0.

After you download and unzip the community edition of JasperReports you'll have a folder named JasperReports-3.0.0. In this folder are sample applications, quick start documentation, and the jar files needed to use JasperReports. The main jar you'll need to include in your Java project is jasperreports-3.0.0.jar, located in the sub-folder dist.

There is some documentation for JasperReports available at reference 3.

iReport

In conjunction with JasperReports you can use iReport to graphically design your reports (instead of writing the report XML manually [the .jrxml file]). iReport gives you the ability to specify a data source and then drag-and-drop the fields from that data source onto the report. You can download iReport at reference 4. iReport is free to download and use. There is a Windows installer version and as of July 6, the iReport version is also 3.0.0.

There is some documentation for iReport available at reference 5.

Learning How To Use JasperReports and iReport

From my research there is limited free documentation available (references 3 and 5) on the JasperReport website. There are some books you can purchase for learning how to use JasperReports and iReport at the JasperReport website. You can also Google JasperReports tutorial for a list of tutorials that may help you get started.

The general steps to creating a report are

1. In iReport specify a source of the data that will be used to fill the report.
2. Once iReport has access to this data source, you design the report.
3. User iReport to compile that report design into a file of type.jasper.
4. The .jasper file can then be used by JasperReports to be filled with data which creates a .jrprint file type.
5. The .jrprint file type can then be used by JasperReports to create a PDF, RTF, or Excel version of the file.

An Example of Using An ArrayList As A Data Source For JasperReports

JasperReports and iReport can use data from various sources including databases and collections. For my current project, the data source is a collection of objects. To give you an example of how to use JasperReports and iReport to create a report that uses an ArrayList of objects as the data source I've prepared the following example. Example source code in Eclipse project.

Model Classes:

We have two model classes: Person and Phone. A Person has a firstName and lastName. Since a Person may have multiple phones, a Person also has an ArrayList of Phone objects.

A Phone has a phoneType (for example "work" or "mobile") and a phoneNumber.

You can download an Eclipse Java project with the source code for Person and Phone and a test class from reference 6.

Setup the Data Source in iReport

If you examine the source code in test.TestPerson class (reference 6) you'll see that I've created a static method named getBeanCollection that returns an ArrayList of Person objects. This method is used in iReport to specify the data source and then will be used to fill the report with Person objects.

To create our report in iReport, we need to give iReport access to our class files for Person and Phone so that iReport can find their fields. Then we can drag-and-drop the fields onto a report design. So I created a jar of the model package (which includes the Person and Phone classes) and placed the jar in the iReport lib folder, which on my system is located at: C:\Program Files\JasperSoft\iReport-3.0.0\lib\.

Now after restarting iReport, iReport will have access to the attributes of the Person and Phone class.

After starting up iReport we also need to specify the path to the class that has the getBeanCollection method, in this case that class is test.TestPerson and on my system the path to the test package is C:\coursecatalogtest\TestJasperReport\bin. So I put that path in iReport - Options - ClassPath - Add Folder.

To setup the data source in iReport go to Data - Connections/Data Sources - New. Select JavaBeans set data source. Then specify the following:

Name: PersonDataSource

Factory class: test.TestPerson

The static method to call to retrieve... getBeanCollection

You should be able to click on the Test button and get the message "Connection Test Successful." Click on Save to save this data source.

Create A Report in iReport

Use File - New Document and give the report a name of contacts. The click on OK

You'll now have a blank report with areas for title, pageHeader, columnHeader, detail, columnFooter, pageFooter, lastPageFooter, and summary. For our example we will just be placing static text in the title and columnHeader's area and then our Person fields in the detail area. For each Person object in the ArrayList, there will be a corresponding section in the detail area.

Accessing the Person Class Fields

To access the model class fields (in our example Person and Phone) in the report, click on Data - Report Query. The click on the JavaBean Data Source tab and enter the class name with path: model.Person. Because you created a jar file of the model package and placed it in iReport's lib folder earlier iReport can find the class and its attributes.

Click on the firstName, lastName, and phones attributes and then click on Add Selected Fields. Then click on OK.

Next click on View - Fields and you'll see these attributes. Drag the firstName and lastName fields to the detail area of the report. In the detail area you should see two boxes, one with $F{firstName} and one with $F{lastName}. The firstName and lastName fields (F) from each Person object in the collection will be placed into the detail area.

Save your report.

Accessing the Phone Class Fields

Because the phones attribute of the Person class is an ArrayList containing Phone objects, we will need to handle displaying all the Phone objects for each Person by using a sub-report. Click on Edit - Insert Element - Subreport. Use the cross-hair cursor to drag a rectangle in the detail area below where you placed the firstName and lastName fields.

With the create new report option checked click on Next. The Connection/Data Source should be PersonDataSource and the JavaBean class is model.Phone. Click next.

You should see the Phone class fields, phoneNumber and phoneType. Select both of those and click on the arrow to move them from the left box to the right box. Click Next.

Select either columnar layout or tabular layout and report format (I choose Tabular layout and classicT.xml). Click Next.

Click Finish.

You should see a subreport with the $F{phoneNumber} and $F(phoneType) fields in the detail area and the static text phoneNumber and phoneType in the columnHeader area of the subreport.

Save your reports.

Specify the Data Source for the Sub Report

Double click on the contacts.jrxml in the Files window to return to the main report. In the main report will be a sub-report icon inside the rectangle you drew earlier. Right click on the sub-report icon and select properties. Click on the Subreport tab.

In the Connection/Data Source Expression drop down box select "Use data source expression."

Click on the "open expression editor button" that is just below the drop down box. In the expression editor, delete any text in the window and type in the following: new JRBeanCollectionDataSource($F{phones}). What this means is that for the sub-report you want to use a new bean collection with the phones field of the Person class as the source of the beans.

Click on Check Expression button and you should get the message: "Expression successfully validated."

Click on Apply and then close the sub-report properties window.

Add Title and Column Headings

You can add static text to any area of the report by clicking on Edit - Insert Element - Static Text. Do so and then using the cross-hair cursor draw a rectangle text area in the title area of the report. Then double click on the rectangle and type in a title (eg "Contacts"). You can then use teh font family and size drop downs to style the text. Do the same procedure to add static text to the column headings area (eg "Name and Phones").

Test the Report

To test the report, you need to compile the main and sub-report and then execute the report.

Before compiling the report, set the location of where you want the compiled files to be placed. Click on Options and then settings and then click on the compiler tab. Click on the browse button and select a folder where you want the to save the compiled .jrxml report files (which are the .jasper files). I choose "C:\JasperReports".

Click on Build - Compile to compile the main contacts.jrxml file and then do the same after double-clicking on the subreport file. If you look inside the folder where you told iReport to place the compiled files you should see two files: contacts.jasper and contacts_subreport0.jasper. The .jasper files are the ones JasperReports can use to fill with data from the data source.

Double click on contacts.jrxml in iReport to open that file back up. The click on Build - Execute (with active connection). In the surreport_dir parameter window enter the folder where you told iReport to save the compiled files (in my example "c:\JasperReports\").

The iReport Jasper viewer should open up with all the Person objects displayed in the report. For each Person object there should be Phone objects displayed.

Summary

We created a very simple main and sub reports using an ArrayList of Person objects. The sub-report is tied to each Person object through the phones ArrayList (a collection of Phone objects) that is an attribute of each Person object.

iReport can be used to create very complex reports. Each report element can be styled with a specifc font, size, color, etc.

What's Next?

In part 1, I covered how to create a JasperReport report using iReport. That report's data source is an ArrayList of Person objects. Each Person object also has an ArrayList of Phone objects. In part 2, I explain how to use the JasperReport report in a Java application. You can download all the source code (Eclipse Java project).

Creating A Filled Report

In part 1, I created a main and sub-report and then compiled those reports into two .jasper files stored in c:\jasperreports\. JasperReports uses the .jasper files to fill with data and create a .jrprint file.

To give your Java application access to the JasperReport classes, you'll need to include these jar files:

jasperreports-3.0.0.jar (located in \jasperreports-3.0.0\dist\ folder)

commons-beanutils-1.7.jar (located in \jasperreports-3.0.0\lib\ folder)

commons-collections-2.1.jar (located in \jasperreports-3.0.0\lib\ folder)

commons-logging-1.0.2.jar (located in \jasperreports-3.0.0\lib\ folder)

itext-1.3.1.jar (located in \jasperreports-3.0.0\lib\ folder)

poi-3.0.1-FINAL-20070705.jar (located in \jasperreports-3.0.0\lib\ folder)

So step 1 is to fill the .jasper file with data. These statements do that:

The first two statements create a Map containing the parameter name (the key) and the parameter's value (the value). For this JasperReport we need to send it the value of the subreport_dir (the directory where the sub-report is stored).

The we can use the JasperFillManager class's fillReportToFile method to fill the .jasper file with data. This method takes three arguments, the .jasper file (we created this using iReport), the parameters to send to that .jasper file, and the data source.

Note that our data source is using the JRBeanCollectionDataSource class, which has a constructor that takes an ArrayList of bean objects. We create that ArrayList by calling the static getBeanCollection method of our class TestPerson. This was the same data source we used in part 1 to create our report in iReport.

Converting A Filled Report to A PDF

The following code uses the filled report, which is stored in contact.jrprint, to create a PDF.

In folder c:\jasperreports\ should now be a PDF named contacts.pdf containing all the data returned by the TestPerson.getBeanCollection method.

Converting A Filled Report to An Rich Text Format (RTF) File

To create an RTF file (which can be opened by Word or other word-processing software) use the following statements.

The above code creates a JasperPrint object using our .jrprint file (which is filled with data from our data source). Then using a JRRtfExporter object it exports the .jrprint file to a RTF file with the same name but extension of .rtf.

After running the above code you should have a contacts.rtf file in the c:\jasperreports\ folder.

Converting A Filled Report to An Excel File

To create an Excel file use the following statements.

The code above is similar to how we created the RTF file, except it uses class xlsExporter to export the .jrprint file to an Excel file type.

Summary

The hardest part of using JasperReports is creating the report. Once you have a report created, you can fill that report with data from a data source. In this example the data source is a collection of Person objects. There are other types of data sources including databases.

Once you have filled your .jasper report (which was created by compiling the .jrxml file in iReport) and created the .jrprint file, you can use JasperReport to convert that .jrprint file to various file types including PDF, RTF, and Excel.