Reporting Made Easy with JasperReports and Hibernate

JasperReports and Hibernate in Web applications

JasperReports is a valuable and viable reporting solution for Java Web applications. It simplifies report generation through the use of XML report templates that are then compiled using the JasperReports engine for use in reporting modules. These compiled report templates can be filled by data received from a variety of sources including relational databases. JasperReports can be integrated into Web applications and create reports in several file formats including PDF and XLS.

Reporting in Java Applications
Often reporting modules increase in complexity and size during the course of application development. Clients tend to demand more information from report modules when they become aware of the benefits reports offer. The reporting module developed as something of an afterthought in such environments suddenly becomes a much more integral part of the application. Reporting modules often seem to be tacked on to developed applications, rather than being considered and implemented during initial application development.

Recently while working on some applications that made extensive use of report extraction to XLS files using the Apache POI library, it became apparent that these report modules tied up lots of valuable development resources for extended periods of time. When the client requested PDF extraction, initial iText API research led me to discover JasperReports. JasperReports was to change our team approach to report development dramatically.

Prior to implementing JasperReports each report creation required the development of a custom report class using the Apache POI library. This approach expended valuable development time creating aspects of the report such as cell specific formats, styles, and population methods. JasperReports offered our team the ability to get back this valuable development time, while producing the same report because of its embedded use of the Apache POI library.

One of the benefits offered by the introduction of JasperReports is that a single report template implementation can produce reports in a number of formats. This means that templates created for XLS format extraction can also be used to produce PDF files and even CSV, HTML or XML.

How Can JasperReports Help Developers?
JasperReports gives developers the ability to create reports quickly and easily that can be extracted to numerous formats. Developers can also use the JasperReports engine to compile report templates at design or runtime - allowing dynamic report formats. Developers can also inject data into these reports from a number of data sources. Developer time no longer has to be spent creating custom report classes using the Apache POI or iText libraries for formatting and stylizing reports, allowing the code writers to focus on the data retrieval aspect of the report. As a result developers gain valuable flexibility and time savings using JasperReports in application development.

The XML report templates used by JasperReports provide the layout and presentation information required to format the resulting report as well as field, variable, and parameter references. Non-development staff can create these templates using a third-party GUI such as iReport with minimal developer collaboration, so developers don't have to involve themselves in the layout and presentation aspect of report generation.

JasperReports enables developers to concentrate their efforts on the parts of the reporting module where they are required, while relieving them of having to write custom report generation code. A developer's role in the report module can be reduced to template compilation, data source implementation, and actual report creation.

Creating and Compiling an XML Report Template
JasperReports requires a report design defining the layout, presentation, and data fields. This design can be built using the net.sf.jasperreports.engine.design.JasperDesign object, so developers can create report designs dynamically, or by creating a net.sf.jasperreports.engine.design.JasperDesign instance from an XML report template. Unless an application specifically requires a dynamic layout a compiled XML report template is the recommended method. This XML template is usually saved with a .jrxml file extension and compiled using the net.sf.jasperreports.engine.JasperCompileManager.

The JasperReports XML template includes elements for title, pageHeader, columnHeader, pageFooter, columnFooter, and the main data element. Each of these elements has a variety of sub-elements as can be seen in sampleReport.jrxml (see Listing 1).

You can download the code samples used in this article at jdj.sys-con.com. As can be seen in sampleReport.jrxml some elements such as and contain layout information, while others such as and font contain presentation information. The XML templates also contain , , and elements used to include data in the report.

The elements allow non-data source information to be passed into a report, such as a dynamic title; elements are the only way to map report fields to the data source fields, while variables are values generated at runtime for use in the report. The complete Document Type Definition (DTD) for the JasperReports XML report template can be found in the JasperReports Ultimate Guide.

Compilation of the XML template can be done either at runtime or build time as part of an Ant build using the JasperReports Ant task.

Compiling the report at runtime entails loading the report into a JasperDesign object and using the created instance as the parameter to the JasperCompileManager.compileReport(JasperDesign design) method, which returns a JasperReport instance. Alternatively the XML template can be passed into the JasperCompileManager.compileToFileReport(String sourceFileName, which creates a compiled report file (.jasper) available throughout the application.

Compiling the report at build time using the JasperReports Ant task requires the addition of the task definition to the build.xml file and a target making use of this task as seen in Listing 2, which is an extract from the source code build.xml. Using the Ant task results in the creation of a compiled (.jasper) file in the destdir task and offers the opportunity to save the Java source file by passing the keepjava attribute of the target a true value. A more thorough example of how to use the Ant task is included in the sample applications provided in the JasperReports download bundle.

Using Data Sources to Fill JasperReports
Most reports use a database as the data source, but JasperReports can use any available data source. These data sources are passed to a net.sf.jasperreports.engine.JasperFillManager fillReportXXX() method. Two types of data source are provided for by these methods - net.sf.jasperreports.engine.JRDataSource and java.sql.Connection. The source code for this article contains examples of both a static data source that extends the JRDataSource and a JDBC connection data source implementation.

The StaticDataSource class implementation provided implements the net.sf.jasperreports.engine.JRDataSource interface enabling it to fill the report data by calling the JasperFillManager.fillReport(JaperReport report, Map parameters, JRDataSource dataSource) method. The two required methods getFieldValue(JRField jrField) and next() of the JRDataSource interface present in StaticDataSource handle the data passing from the data source into the JasperReport. The data source used by StaticDataSource is a static simple two-dimensional array of bowlers containing their names and scores over three games (see Listing 3). When the fillReport() method containing this data source is processed and a detail section is encountered in the report a call will be made to the next() method. The implementation of this method in StaticDataSource (see Listing 4) returns true if there's another element in the data array, or false if there is no more data. If this method returns true then field elements encountered in the detail section will result in a call to the getFieldValue(JRField jrField) method in StaticDataSource. The implementation of this method in StaticDataSource (see Listing 5) returns the value of the mapped data field name for the current index of the data array. When the end of the detail section is encountered, the next() method is called again and the process repeats until the next() method returns false.

The JDBCDataSourceExample (see Listing 6) implements a fillReport() method that accepts a java.sql.Connection parameter. Through the addition of a element into the XML report template (jdbcSampleReport.jrxml) this fillReport() method enables data to be extracted from a relational database. The element returns the data fields for use in the report data mapping. In this case the query simply returns all records in the sample_data table. A java.sql.ResultSet can be used instead of implementing the element in the report template, allowing dynamic query implementation.

Using Hibernate with JasperReports
Hibernate is one of the most popular ORM tools in use at the moment. Using Hibernate as a data source for JasperReports can be very simple when a collection of objects is returned from a Hibernate query, but when a tuple of objects is returned then a custom JRDataSource implementation is required.

When a Hibernate query returns a collection of objects, a net.sf.jasperreports.engine.data.JRBeanCollection-DataSource can be used to map the Hibernate POJO instance fields to the report fields. All that's required for this simple solution is to use the JRBeanCollectionDataSource(java.util.Collection beanCollection) constructor, passing it the Hibernate Query result set as implemented in SimpleHibernateExample (see Listing 7). In this example the simple Hibernate query used (session.createQuery("from SampleData").list()) is equivalent to that found in the JDBCDataSourceExample. JRBeanCollectionDataSource implements JRDataSource like StaticDataSource but its getFieldValue(JRField jrField) method implementation maps the report template field names to the query result bean properties.

When a Hibernate query returns a tuple of objects it's necessary to write a custom implementation of the JRDataSource similar to HibernateDataSource (see Listing 8). The implementation of the required next() method in this class returns true if there is another list item in the Hibernate query result set, while putting the current list item in a currentValue holder for use in the getFieldValue(JRField jrField) method. The getFieldValue() method implementation gets the field index in the currentValue object via a call to the getFieldIndex(String field) method. This method iterates through the mapped field names passed to the HibernateDataSource constructor until it finds the field name it was passed and then returns the index of this field in the currentValue information. The getFieldValue() method then returns the value at this index in the currentValue result object.

More extensive solutions to using Hibernate with JasperReports, including the use of reflection instead of the name mapping method used in HibernateDataSource, can be found on the Hibernate Web site www.hibernate.org/79.html. Also of interest in this area is the report optimization implementation advocated by John Ferguson Smart in his article "Hibernate Querying 103: Using Hibernate Queries with JasperReports" (see Resources).

Exporting Reports to PDF and XLS Formats in Web Applications
After compiling and filling a JasperReport report exporting it is a fairly simple and straightforward process using the net.sf.jasperreports.engine.JRExporter interface implementations provided. JasperReports can export data to PDF, XLS, CSV, RTF, HTML, and XML from the same report design using the appropriate implementation of the JRExporter interface. The PDF and XLS formats are two of the most common export formats and examples of exporting to these formats from within a Web application can be found in the source code for this article. PrintServlet exports to PDF, while DataExtractServlet exports the same data to an XLS format file.

PrintServlet (see Listing 9) is a an example servlet implementation class using JasperReports to export a report to PDF format. JasperReports makes use of the Open Source iText PDF creation library (see Resources) to generate PDF format files. Once the report is compiled in PrintServlet, the PDF is created and streamed to the Web browser ready for printing using the runReportToPdfStream(InputStream inputStream, OutputStream outputStream, Parameters params, Connection connection) method implemented by the JasperRunManager facade class.

DataExtractServlet (see Listing 10) is an example servlet implementation class using JasperReports to export a report to the XLS format. JasperReports makes use of the Apache POI library (see Resources) to generate XLS format files. Once the report is compiled in DataExtractServlet the XLS file is created in memory and a save dialog is displayed to the user. The servlet uses net.sf.jasperReports.engine.export.JRXlsExporter, one of the concrete implementations of the JRExporter interface provided by JasperReports to export the report. The parameters for exporting the report are initialized using JRXlsExporterParameter variables to set the filled report (JRXlsExporterParameter.JASPER_PRINT) and the output stream (JRXlsExporterParameter.OUTPUT_STREAM) - which is the response object that has had its content type and header set so that the file will be made available to the user for saving rather than displayed as in the PrintServlet example when exportReport() is called.

Useful Hint: By default JasperReport puts page headings at the top of every 'page' of data. When exporting to an XLS format this breaks up the continuous data in a worksheet that contains more than a single 'page' of data. Data continuity can be maintained by passing the type of output format as a parameter to a report template combined with a element based on the passed parameter placed in the element. The below will result in only the page headings being output to a 'page' if the report is processing the first page when the output format isn't PDF and on every 'page' for PDF output formats.


|| $P{REPORT_TYPE}.equals("PDF")
? Boolean.TRUE : Boolean.FALSE]]>


Creating Reports Is Easy and Fun with JasperReports
Hopefully this article has whetted your appetite for exploring the world of report generation using JasperReports, or if you've already discovered JasperReports, that it's provided some ideas on how to delve into creating custom data sources or using new export formats. Understanding and mastering the implementation of the required JRDataSource methods next() and getFieldValue(JRField jrField) opens up any data source for use in generating reports with JasperReports.

Creating reports with JasperReports is made even simpler by some useful tools. iReport (see Resources), an excellent JasperReports template creation tool that allows visual report designs in a GUI application can be used by non-developers to create the JasperReport designs. It also offers substantial developer-focused functionality such as data source connectivity to create report previews outside of an application. JasperAssistant (see Resources), while not Open Source has the advantage of being an Eclipse plug-in for developing JasperReport templates in a similar GUI manner, albeit more developer-oriented. Both offer the benefit of being able to prepare a report design, which can then be provided to a developer for filling, relieving him of the tedious presentation aspect of report generation.

This article has barely scratched the surface of JasperReports' extensive use and functionality but hopefully it's introduced some developers to an extremely useful tool in any Java developer's arsenal. JasperReports can even produce charts and graphs, as well as including images in reports that increase the richness and presentation of an applications reporting system. JasperReports is a powerful API that can take a reporting system to the next level.