The Pentaho Reporting engine is a small set of open source Java classes that enables programmers to retrieve information from a data source, format and process it according to specified parameters, then generate user-readable output. This guide provides guidance and instructions for using the Pentaho Reporting SDK to embed the Pentaho Reporting engine into a new or existing Java application. There are four sample applications in this guide, all of which are included in the SDK as .java files. Each adds one level of complexity or shows a different kind of output.
Audience: This document is strictly for Java software developers. You must be familiar with importing JARs into a project, and be comfortable reading inline comments in code to figure out advanced functionality on your own. Proficiency in connecting to data sources is a helpful skill for developing your own application around the Pentaho Reporting engine, but is not required to follow the examples.
You should read this content in order, from this point all the way to the end of the second example. The remaining articles contain extra information about the Pentaho Reporting engine's capabilities, licensing details, further examples, and information on where to get help and support.
Get Started with the Pentaho Reporting SDK
You can download the latest Pentaho Reporting software development kit (SDK) from http://reporting.pentaho.com.
The SDK is available as both a .tar.gz and a .zip archive; both contain the same files, but the .zip file format is more Windows-friendly, and .tar.gz is more Mac-, Linux-, and Unix-friendly.
Once downloaded, unpack the Pentaho Reporting SDK archive to a convenient and accessible location. If you use the Eclipse or IntelliJ IDEA development environments, this directory will also serve as your workspace.
In an effort to reduce the size of the SDK, the source code of its constituent libraries is not included. If you need to see the source to any of the software distributed with the Pentaho Reporting SDK, see Source Code Links for instructions.
Use the Included Eclipse Project
If you use the Eclipse or IntelliJ IDEA development environments, you can use the Eclipse project included with the Pentaho Reporting SDK to work directly with the example source code. Simply select the unpacked Pentaho Reporting SDK directory as your workspace.
You can also launch the Sample1.java and Sample2.java example applications directly from the file browser in Eclipse.
SDK Directory Structure
The following elements are delivered in the SDK directory structure:
/ /documentation /licenses /samples /WebContent /../META-INF /../WEB-INF /../../lib /lib /source /../org /../../pentaho /../../../reporting /../../../../engine /../../../../../classic /../../../../../../samples /sql
|Documentation||Where the Embedding the Pentaho Reporting Engine PDF is located|
|Licenses||Contains text files with licensing information|
|Samples||The eclipse project directory, which contains the samples shown in this guide|
|Samples/WebContent||WebContent information used with Sample 4 (mainly the WEB-INF/web.xml)|
|Samples/lib||The lib directory which makes up the Reporting Engine SDK|
|Samples/source||The source files used to make up the four reporting samples|
|Samples/sql||The file-based HSQLDB instance used with the samples|
Content of the Samples Directory
The following files appear in the Samples directory:
|build.properties||Ant properties used with the build script|
|build.xml||Ant build script|
|common_build.xml||Ant Build Script|
|ivysettings.xml||Settings for Ivy (used with build)|
|ivy.xml||Dependencies for project (used with Ivy – used with build)|
|.project||Eclipse project file|
|.classpath||Eclipse classpath file|
|samples.iml||IntelliJ project file|
|Sample*.bat||Runs the sample (1/2/3) program on Windows|
|Sample *.launch||Runs the sample (1/2/3) program from within Eclipse|
|Sample*.sh||Runs the sample (1/2/3) project on linux|
|Sample4.war||The WAR that can be dropped in a Servlet Container (Tomcat) and executed|
Embed the Reporting Engine into a Java Application
Build a simple reporting application around the Pentaho Reporting engine in a Java application.
Other Embedding Scenarios
Besides the reporting engine, you can embed or extend the Pentaho Analysis engine (Mondrian), the Pentaho BI Platform, part or all of Pentaho Data Integration (Kettle), and the Weka data mining engine.
The examples in this section are simple and easy to follow, but with more complex requirements come more advanced programs. While reading the source code comments can help quite a bit, you may still need help to develop an application within a reasonable time-frame. Should you need personal assistance, you can have direct access to the most knowledgeable support resources through a Pentaho Enterprise Edition software vendor annual subscription:
If phone and email support are not enough, Pentaho can also arrange for an on-site consulting engagement:
The entire Pentaho Reporting SDK is freely redistributable. Most of it is open source software, but its constituent JARs are under a few different licenses. If you intend to embed and distribute any part of this SDK, you must be familiar with the licensing requirements of the pieces you use.
You can read all of the relevant licenses in text files in the licenses subdirectory in the Pentaho Reporting SDK.
The following topics help to extend your knowledge of embedding reporting functionality beyond basic setup and use:
- JAR Reference
Review a list of the Pentaho-authored and third-party JARs that make up the Pentaho Reporting SDK.
- Source Code Links
Review a list of individual and modular projects for Pentaho Reporting.
- Sample 3: Dynamically Generated, JDBC Input, Swing Output
Use this sample to render a report in a Swing preview window.
- Sample 4: Dynamically Generated, JDBC Input, Java Servlet Output
Use this sample to dynamically generate an HTML reports.