JasperReports

From InstallationWiki

JasperReports

Official Page

Project Documentation

Download

Source Book ISBN 978-1-904811-90-9 Publisher Packt Publishing Author(s) David Heffelfinger

JasperReports is an open source Java reporting tool that can write to screen, to a printer or into PDF, HTML, Microsoft Excel, Comma-separated values and XML files.

It can be used in Java-enabled applications, including J2EE or Web applications, to generate dynamic content. It reads its instructions from an XML or .jasper file.

We can easily add reporting capabilities to Java applications by taking advantage of the classes included in the JasperReports class library. JasperReports can be easily embedded into both client and server-side Java applications, simply by adding the required libraries to our CLASSPATH and calling the appropriate methods in the JasperReports API.

By the end of this tutorial, we will be able to:

• Identify the purpose of the several downloads that can be found at the JasperReports website
• Identify required libraries for adding reporting capabilities to Java applications
• Identify optional libraries that can be used to enhance the reporting capabilities of Java applications
• Set up our development and execution environment to successfully add reporting capabilities to Java applications

Contents 1 Downloading JasperReports 1.1 Setting Up Our Environment 2 JasperReports Class Library 2.1 Required Libraries for Report Compilation 2.1.1 Jakarta Commons 2.1.1.1 Jakarta Commons Digester 2.1.1.2 Jakarta Commons Collections 2.1.1.3 Jakarta Commons Logging 2.1.1.4 Jakarta Commons BeanUtils 2.2 Optional Libraries and Tools 2.2.1 Apache ANT 2.2.2 JDT Compiler 2.2.3 JDBC Driver 2.2.4 iText 2.2.5 JFreeChart 2.2.6 Jakarta POI 3 Summary 4 Source

[edit] Downloading JasperReports

JasperReports can be downloaded from http://www.sourceforge.net/projects/jasperreports. When visiting the JasperReports download page, you should see an image similar to the following around the middle of the page:

JasperReports can be downloaded by clicking on this image. Once you click on the image, you should see a window similar to the following on your browser:

Clicking on the JasperReports 1.2.2 link at the top left cell should take you to a page containing a tree displaying current and previous versions of JasperReports.

Each node in the tree contains three download links. It is not always clear what exactly is downloaded by clicking on these links. For this reason, a brief explanation for each link is given next.

The first link is to download a JAR file containing a subset of the JasperReports functionality. Specifically, it contains classes that can be used to display jrprint files, which are reports in JasperReports' native format. This file is offered as a separate download as a convenience for developers. It can be used for applications or applets that do not require full reporting capabilities, but which need to display generated reports. The file name has a suffix of applet. However, there is nothing preventing us from using it with standalone applications. This file is approximately 187 KB in size.

The second link is the complete JasperReports class library. It contains all the classes necessary to compile, fill, and export reports, but does not include any additional libraries JasperReports depends upon. This is the minimum file we need to add full reporting capabilities to our Java applications. This file is approximately 1.3 MB in size. If we choose to download this file, then we need to download JasperReports dependencies separately. These dependencies are listed in the following table:

Dependency		Version		Download URL		Comments
Commons Logging		1.0 or later		http://jakarta.apache.org/commons/logging/		Used for sending output to a log.
Commons Collections		2.1 or later		http://jakarta.apache.org/commons/collections/		Used to manage collections of data.
Commons BeanUtils		1.4 or later		http://jakarta.apache.org/commons/beanutils/		Used for JavaBeans introspection.
Commons Digester		1.7 or later		http://jakarta.apache.org/commons/digester/		Used for XML parsing.
JFreeChart		1.0 or later		http://www.jfree.org/jfreechart/		Only required when the report contains charts.
iText		1.01 or later		http://www.lowagie.com/iText/		Only required when exporting reports to PDF or RTF.
Jakarta POI		2.0 or later		http://jakarta.apache.org/poi/		Only required when exporting reports to Excel format.
JExcelApi		2.5.7 or later		http://jexcelapi.sourceforge.net/		Only required when exporting reports to Excel format.
Hibernate		3.0 or later		http://www.hibernate.org/		Only required when writing report queries using the Hibernate Query Language (HQL).

The third and the last link is a ZIP file containing the complete JasperReports class library along with all the required and optional libraries. The ZIP file also includes the JasperReports source code, as well as a lot of source code providing examples demonstrating JasperReports' functionality. This file is approximately 24 MB in size. Unless internet connectivity speed is an issue, downloading this file is recommended since it includes everything we need to create reports with JasperReports. Moreover, the included examples are a great way to learn how to implement the different JasperReports features. All of the examples in the file come with an ANT build file containing targets to compile and execute. We will refer to this file as the JasperReports project file, or, more succinctly, as the project ZIP file.

Note: Detailed instructions on installing ANT can be found in the online ANT manual at http://ant.apache.org/manual/index.html.

Once we have downloaded the appropriate file for our purpose, we need to set up our environment to be able to start creating reports. In the next section, we discuss how to do this, assuming that the project ZIP file was downloaded.

[edit] Setting Up Our Environment

To set up our environment to get ready to start creating reports, we need to extract the JasperReports project ZIP file to a location of our choice. Once we extract the project ZIP file, we should see a jasperreports-1.2.2 directory containing the following files and directories:

• build: A directory containing the compiled JasperReports class files.
• build.xml: An ANT build file to build the JasperReports source code. If we don't intend to modify JasperReports, we don't need to use this file since JasperReports is distributed in compiled form.
• changes.txt: A text document explaining the differences between the current and previous versions of the JasperReports class library.
• demo: A directory containing various examples demonstrating several aspects of JasperReports functionality.
• dist: A directory containing a JAR file that contains the JasperReports library. We should add this JAR file to our CLASSPATH to take advantage of JasperReports.
• docs: A directory that contains a local copy of the JasperReports website.
• lgpl.txt: A text document that contains the full text of the LGPL license.
• lib: A directory containing all libraries needed, both to build JasperReports and to use it in our applications.
• readme.txt: A text document containing instructions on how to build and execute the supplied examples.
• src: A directory containing the JasperReports source code.

Getting Up and Running Quickly. To get up and running quickly, the files to be added to the CLASSPATH are the JasperReports JAR file (its file name should be jasperreports-1.2.2.jar or similar, depending on the exact JasperReports version) which can be found under the dist subdirectory of the directory created while extracting the project ZIP file, or downloaded directly as described above, and all the JAR files under the lib subdirectory of the directory created while extracting the project ZIP file. By adding these files to the CLASSPATH, we don't have to worry about the CLASSPATH when implementing additional functionality (e.g. exporting to PDF or producing charts).

[edit] JasperReports Class Library

JasperReports is distributed as a JAR file that needs to be added to the CLASSPATH of any application for which we wish to add reporting capabilities. The JasperReports library requires a Java Runtime Environment (JRE) 1.3 or newer. For all JasperReports -related tasks, we need to add the JasperReports library to our CLASSPATH. The JasperReports library can be found under the dist subdirectory of the directory created while extracting the project ZIP file. It is named jasperreports-1.2.2.jar. The exact file name will vary depending on the version of JasperReports we are working with.

[edit] Required Libraries for Report Compilation

The project ZIP file, described in the previous section, contains all the required supporting libraries. If that file is downloaded, all the required libraries can be found

under the lib subdirectory of the directory created when extracting the ZIP file. JasperReports uses these required files for XML parsing. Therefore, they are needed when compiling JRXML files. However, programmatically they are not needed for filling or displaying reports. JRXML files can be compiled via a custom ANT task provided by JasperReports. If we choose to compile our JRXML files via this custom ANT target, these required libraries need to be added to the CLASSPATH variable of the ANT build file. There are build file examples included in the project file as well as in this book's website: http://www.packtpub.com/jasper_reports/book/.

[edit] Jakarta Commons

Jakarta Commons is a collection of Java libraries developed and distributed by the Apache Software Foundation. Jakarta Commons includes libraries and utility classes that provide commonly used functionality, freeing developers from the task of re-implementing them. Before implementing a piece of functionality that is frequently needed, we should make sure there isn't a Jakarta Commons library that implements it. Jakarta Commons includes libraries for logging, XML parsing, sending and receiving email, I/O, network utility classes, and many others. For more information, visit the Jakarta Commons website at http://jakarta.apache.org/commons/. The following list of libraries highlights the fact that JasperReports makes extensive use of Jakarta Commons.

[edit] Jakarta Commons Digester

The Commons Digester library includes utility classes used to initialize Java objects from XML files. JasperReports takes advantage of the Digester component of the Jakarta Commons repository to implement its XML parsing functionality. Version 1.2.2 of the JasperReports project ZIP file includes version 1.7 of Commons Digester. The file name is commons-digester-1.7.jar and it must be on your CLASSPATH for your JasperReports application to work correctly.

If you download the bare JasperReports class library, you will need to download Commons Digester separately from http://jakarta.apache.org/commons/digester/.

[edit] Jakarta Commons Collections

Another component of the Jakarta Commons suite is Commons Collections. This component provides the functionality to complement and augment the Java Collections Framework. JasperReports takes advantage of the Collections component to implement some of its functionality. Like all other required libraries, the Commons Collections library can be found under the lib subdirectory of the directory created when extracting the project ZIP file. The JasperReports project file, version 1.2.2, includes version 2.1 of Commons Collections, distributed as a JAR file named commons-collections-2.1.jar.

If you download the bare JasperReports class library, you will need to download Commons Collections separately from http://jakarta.apache.org/commons/collections/.

[edit] Jakarta Commons Logging

The Commons Logging library includes components that aid developers with sending data to log files. JasperReports takes advantage of this component, which can be found under the lib subdirectory of the directory created when extracting the project ZIP file. The version included with JasperReports version 1.2.2 is version 1.0.2. The file to be added to your CLASSPATH is commons-logging-1.0.2.jar.

If you download the bare JasperReports class library, you will need to download Commons Logging separately from http://jakarta.apache.org/commons/logging/.

[edit] Jakarta Commons BeanUtils

The last library that JasperReports requires for compiling reports is Commons BeanUtils. BeanUtils is a library that provides easy-to-use wrappers around the Java reflection and introspection APIs. Version 1.2.2 of the JasperReports project ZIP file includes BeanUtils version 1.5. The file to be added to your CLASSPATH is commons-beanutils-1.5.jar.

If you download the bare JasperReports class library, you will need to download Commons BeanUtils separately from http://jakarta.apache.org/commons/beanutils/.

[edit] Optional Libraries and Tools

There are a number of libraries that are required only if we wish to take advantage of some of JasperReports' features. These optional libraries and their uses are listed next.

[edit] Apache ANT

JasperReports comes bundled with some custom ANT targets for previewing report designs and for viewing reports serialized in JasperReports' native format. Although not mandatory, it is very helpful to have ANT available to take advantage of these custom targets.

Throughout this book, we will be using JasperReports-specific ANT targets. Therefore, ANT is required when following the examples. ANT can be downloaded from http://ant.apache.org/.

[edit] JDT Compiler

JDT stands for Java Development Tools. The JDT compiler is the Java compiler included with the Eclipse IDE (Integrated Development Environment). The JDT compiler is needed only when the JasperReports application is running under a Java Runtime Environment (JRE), and not under a full JDK.

When compiling reports, JasperReports creates temporary Java files and compiles them. When using a JDK, JasperReports takes advantage of tools.jar for this functionality. Since a JRE does not include tools.jar, the JDT compiler is needed. The JasperReports project ZIP file version 1.2.2 includes the JDT compiler. It can be found under the lib subdirectory of the directory created when extracting the project ZIP file. The file to be added to your CLASSPATH is jdt-compiler.jar.

This file cannot be downloaded separately. Therefore, if we need to execute our code under a JRE, we need to download the JasperReports project ZIP file, since it includes the file, which is needed for report compilation.

JasperReports requires either tools.jar or the JDT when compiling JRXML templates into binary JasperReports templates. A JRE is sufficient if our Java application does not compile reports.

[edit] JDBC Driver

When using a JDBC datasource, the appropriate JDBC driver for our specific RDBMS is needed. The following table lists popular relational database systems and the required JAR files to be added to the CLASSPATH (exact file names may vary depending on the version). The names shown in the table reflect the latest stable versions at the time of writing:

RDBMS		Driver JAR Files
Firebird		firebirdsql-full.jar
HSQLDB		hsqldb.jar
MySQL		mysql-connector-java-3.1.10-bin.jar
Oracle		classes12dms.jar
DB2		db2java.zip
PostgreSQL		postgresql-8.0-312.jdbc3.jar
SQL Server		mssqlserver.jar, msbase.jar, msutil.jar
Sybase		j conn3.jar

The JasperReports project ZIP file includes the JDBC driver for HSQLDB. Consult your RDBMS documentation for information on where to download the appropriate JDBC driver for your RDBMS.

[edit] iText

iText is an open-source library for creation and manipulation of PDF files. iText is needed only if you want to export your reports to PDF or RTF format. Version 1.2.2 of the JasperReports project ZIP file includes iText version 1.3.1. The file to be added to your CLASSPATH is itext-1.3.1.jar.

iText can be downloaded separately from http://www.lowagie.com/iText/.

Useful code snippet for merging reports using iText can be found here [1]

[edit] JFreeChart

JFreeChart is an open-source library for creating professional-looking charts including, but not limited to 2-D and 3-D pie charts, 2-D and 3-D bar charts, and line charts. JFreeChart is needed in our CLASSPATH only if you intend to add charts to your reports. JFreeChart version 1.0 RC1 can be found in the lib directory inside the JasperReports project ZIP file version 1.1. The file to be added to the CLASSPATH is jfreechart-1.0.0-rc1.jar.

JFreeChart can be downloaded separately from http://www.jfree.org/jfreechart/.

[edit] Jakarta POI

Jakarta POI is a Java library that allows Java applications to read and write Microsoft Office files. We need POI in our CLASSPATH only if we need to export our reports to XLS format. Version 1.1 of the JasperReports project ZIP file includes POI version 2.0. To add XLS exporting capabilities to your reports, the file you need to add to your CLASSPATH is poi-2.0-final-20040126.jar.

POI can be downloaded separately from http://jakarta.apache.org/poi/.

[edit] Summary

This tutorial covered the required and optional libraries needed to add reporting capabilities to Java applications. All the libraries covered in this tutorial are needed both at compile time and at run time.

The tutorial provided an explanation of the different files available for download on JasperReports' website and in which conditions it is appropriate to use them. We saw which libraries are required for report compilation under a Java Development Kit as well as which additional libraries are required when compiling JRXML templates under a Java Runtime Environment (JRE). Besides, this tutorial also covered which libraries are required when using JDBC datasources for our reports, and finally the libraries required when exporting our reports to several formats.

Now that we have seen the libraries needed to work with JasperReports, we are ready to create our first report.

[edit] Source

The source of this content is Chapter 2: Adding Reporting Capabilities to Java Applications of JasperReports for Java Developers by David Heffelfinger (Packt Publishing, 2007).