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 <detail> 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 <band> and <reportElement> contain layout information, while others such as <textElement> and <font> contain presentation information. The XML templates also contain <parameter>, <field>, and <variable> elements used to include data in the report.

The <parameter> elements allow non-data source information to be passed into a report, such as a dynamic title; <field> 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 <queryString> element into the XML report template (jdbcSampleReport.jrxml) this fillReport() method enables data to be extracted from a relational database. The <queryString> 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 <queryString> 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.