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.
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/.
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.
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/.
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/.
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/.
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/.
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.
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/.
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.
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:
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.
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/.
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/.
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/.