Please don't blame Thomas for any wrong things yet. I (Mimil) is the author till any review.

Getting JFreeReport

In this section you will see that JFreeReport can be retrieved in different ways but the standard users will certainly choose to download the bundle whereas contributors will choose to grab the sources from the versioning system.
JFreeReport team and support can be reached either on JFree or on SourceForge. You can also get it from Pentaho but we will talk about them later in this article.
As you should know if you planned to use this reporting library you need a Java platform properly installed. It requires at least a version compatible Java 1.2.2. You can dowload the lastest version from the Sun web site.
Whatever type of JFreeReport download you choose, you will get the following layout:

the Java sources of JFreeReport, located in the sources/ directory.
a set of libraries that may be used, located in the lib/ directory.
the building system configuration based on Ant, located in the ant/ directory.
the code conventions used by the contributors based on Checkstyle, located in the checkstyle/ directory.
ressource directory

Bundled distribution

Versioning System

Building

The different libraries

In this section you will discover the libraries JFreeReport is based on many free and open source libraries for its core and for extending its functionnalities. JFree, from JFreeChart and JFreeReport, also released some opensource libraries out of their projets : JCommon, Pixie, LibFont and LibLoader.

...

JCommon [~302KB plus ~180KB]
JCommon is a collection of useful classes used by JFreeChart, JFreeReport and other projects. This library contains common classes which provide some global utility functionality for both GUI and non-GUI applications.
You must include in any case its library, jcommon-1.0.6.jar, because it is part of JFreeReport core. If you planned to use the XML report definitions or XML export facilities you also have to include jcommon-xml-1.0.6.jar.
Pixie [~170KB]
Pixie is a free Java library for loading WMF images.
You must include its library, pixie-0.8.6.jar, if you planned to use Microsoft WMF Image files.
LibFonts [~130KB]
LibFonts is a font reading library, which grants easy to use access to font raw data. It creates a generic wrapper around the various font systems (AWT, TrueType, Type1, iText) to allow high-performance access to the glyph and font-metrics information.
You must include in any case its library, libfonts-0.2.1.jar, because it is part of JFreeReport core.
LibLoader [~70KB]
LibLoader is a Java resource loading and caching framework.
You must in any case include its library, libloader-0.1.5.jar, because it is part of JFreeReport core.
GnuJAXP [~230KB]
GNU JAXP is a free implementation of the standard XML processing APIs for Java.
You have to use this library for old JDK, prior to 1.4, to allow the XML parsing and writing. Once it is included in your path it will replace your JDK XML implementations and may produce problems in some existing project.
Do not include it if you do not need it, it will save you precious time, else include its library gnujaxp.jar.
//org.jfree.xml.ParserFrontend
iText [~1250KB]
iText is a library that allows you to generate PDF files on the fly.
You must include its library, itext-1.4.jar, if you planned to use Adobe PDF export facility. You will also need the following modules :
- org.jfree.report.modules.output.pageable.pdf.PDFPageableModule, the PDF output support module: jfreereport-output-pageable-pdf-<version>.jar.
- org.jfree.report.modules.output.pageable.base.PageableBaseModule, the pageable output support module: jfreereport-output-pageable-base-<version>.jar.
- org.jfree.report.modules.output.support.itext.BaseFontModule, the itext font processing module: jfreereport-output-support-itext-<version>.jar.
- org.jfree.report.modules.output.support.pagelayout.PageLayoutModule, the pagelayout module: jfreereport-output-support-pagelayout-<version>.jar.
- org.jfree.report.modules.misc.configstore.base.ConfigStoreBaseModule, the configuration storage module: jfreereport-misc-configstore-base-<version>.jar. (.......FileConfigStoreModule......)
- org.jfree.report.JFreeReportCoreModule, the core module needed by every other module: jfreereport-core-<version>.jar.
POI [~840KB]
POI project consists of APIs for manipulating various file formats based upon Microsoft's OLE 2 Compound Document format using pure Java.
You must include its library, poi-3.0-alpha1-20050704.jar, if you planned to use the Microsoft Excel and Microsoft Word export facilities. You will also need the following modules:
...
Bean Scripting Framework[~170KB]
Bean Scripting Framework is a set of Java classes which provides scripting language support within Java applications, and access to Java objects and methods from scripting languages. The scipting languages supported are Javascript, Python, Groovy, Ruby, ObjectScript, Java, NetRexx, ...
You must include it library, bsf-2.3.0.jar, if you planned to use scripting expressions directly written in the XML report definitions or from script files. You will also need the following modules:
...

BeanShell [~240KB]
BeanShell is a small embeddable Java source interpreter with object scripting language features, written in Java.
You must include its library, bsh-1.3.0.jar, if you planned to use Java expressions directly written in the XML report definitions. You will also need the following modules:
...
Each BeanShell expression have to extend the class org.jfree.report.modules.misc.beanshell.BSHExpression or ... and redefine the getObject method:

Code Block


<expression name="rawDate" class="org.jfree.report.modules.misc.beanshell.BSHExpression">
  <properties>
    <property name="expression">
      // This declaration is important. The script-method getValue is called by the
      // BSHExpression to evaluate the expression. We override the default implementation
      // and perform own calculations here ...
      Object getValue()
      {
        java.util.Date date = dataRow.get("group-date");
        return new Long (date.getTime());
      }
    </property>
  </properties>
</expression>

As you could see in the above example the object nammed dataRow as been implicitly declared to reference the current row of data. It allows you to access all the other data by column name or column number whithin the current raw of data.
That is all the informations you will get about how to define BeanShell expressions in this article. It will certainly be part of a further one.

Installation

In this section we will discuss how to install and configure JFreeReport and you will see that installing it is mainly a matter of setuping the classpath of your application and a little bit of handy configuration.

Classpath setup

First a little definition of what is the classpath : The class path tells to java tools and applications where to find third party and user classes or libraries. Most of the time it is a suite of path to your file system separated by a ; character.

The classpath is used for two steps : the compilation step (using javac command) and the running step (using java command).

The following shell extract shows you how to run the demo application with full features and specifying classpath elements. Therefore we didn't choose to specify each module libraries one by one, we just included the monolithic build. If you do not remember what I mean by the monolitic build and the module libraries, scroll back to Bundled distribution section.

Code Block


# On Unix environments
$> cd /path/to/jfreereport/
$> java -classpath="jfreereport-.jar; lib/bsf-2.3.0.jar; lib/bsh-1.3.0.jar; lib/itext-1.4.jar; lib/jcommon-1.0.6.jar; lib/jcommon-xml-1.0.6.jar;
lib/libfonts-0.2.1.jar; lib/libloader-0.1.5.jar; lib/pixie-0.8.6.jar; lib/poi-3.0-alpha1-20050704.jar" org.jfree.report.demo.DemoFrontend
# On Windows environments
$> cd drive:\path\to\jfreereport\
$> java -classpath="jfreereport-.jar; lib\bsf-2.3.0.jar; lib\bsh-1.3.0.jar; lib\itext-1.4.jar; lib\jcommon-1.0.6.jar; lib\jcommon-xml-1.0.6.jar;
lib\libfonts-0.2.1.jar; lib\libloader-0.1.5.jar; lib\pixie-0.8.6.jar; lib\poi-3.0-alpha1-20050704.jar" org.jfree.report.demo.DemoFrontend

Running the demo application is meaningless but it shows you how to specify classpath entries, all you have to do in you applications is to append you libraries and classes and run your Main class instead of the demo one (the last part of previous java commands).

You can also run the demo application using the following statement:

Code Block
$> java -jar jfreereport-demo-<version>.jar

The javac command is a little bit different because the -classpath option is named -cp and you don't have to specify the Main class to run. However, on newest version of Java JDK, java and javac commands have both options -classpath and -cp to specify the classpath.

Jar

A Jar file is a compressed archive containing a set of files, ressources and directories. If its manifest file contains an attribute named Main-Class, the attribute value (a canonical class name without the leading .class extension) will be launched at startup. Then it will be considered as executable archive.

A manifest is a simple text file at a specified place in the archive (META-INF/MANIFEST.MF) used to set metadata describing the content of the archive.

As you saw on the previous section running the demo application with the java -jar command, we didn't specify the classpath entries at all. If you wonder why it is working, just have a look to the manifest of this jar archive. You can specify classpath entries in this file, here it is the manifest of the demo archive:

Code Block


Manifest-Version: 1.0
Ant-Version: Apache Ant 1.6.2
Created-By: 1.2.2 (Sun Microsystems Inc.)
Main-Class: org.jfree.report.demo.DemoFrontend
Class-Path: jfreereport-core-0.8.7-10.jar jfreereport-parser-ext-0.8.7-10.jar
  jfreereport-parser-simple-0.8.7-10.jar jfreereport-gui-csv-0.8.7-10.jar
  jfreereport-gui-html-0.8.7-10.jar jfreereport-gui-pdf-0.8.7-10.jar
  jfreereport-gui-plaintext-0.8.7-10.jar jfreereport-gui-print-0.8.7-10.jar
  jfreereport-gui-xls-0.8.7-10.jar jfreereport-misc-bsf-0.8.7-10.jar
  jfreereport-misc-beanshell-0.8.7-10.jar jfreereport-misc-configstore-filesystem-0.8.7-10.jar
  jfreereport-misc-logging-base-0.8.7-10.jar jfreereport-output-xml-0.8.7-10.jar
  jfreereport-gui-rtf-0.8.7-10.jar jfreereport-misc-survey-0.8.7-10.jar jfreereport-0.8.7-10.jar

If you are attentive you perhaps saw that not any libraries we saw on the previous section are present. It is because they are specified in the manifest of the included jfreereport-0-8.7-10.jar library:

Code Block


Manifest-Version: 1.0
Ant-Version: Apache Ant 1.6.2
Created-By: 1.2.2 (Sun Microsystems Inc.)
Class-Path: lib/jcommon-1.0.6.jar lib/libloader-0.1.5.jar lib/libfonts-0.2.1.jar
  lib/pixie-0.8.6.jar lib/bsf-2.3.0.jar lib/bsh-1.3.0.jar
  lib/gnujaxp.jar lib/itext-1.4.jar lib/poi-3.0-alpha1-20050704.jar

You can now make your own executable archive to simplify the running step, however this solution can be restricting if the manifest is hardcoded. Having shell scripts or Ant files could be a good idea in complex cases.

// create a jar

If you want more information about Jars you should perhaps have a look at Sun Jar tutorial page.

Using Eclipse IDE

Using IntelliJ IDE

Using Netbeans IDE

Using Borland IDE

Webapp

Applet

A Java applet is small application served by a web server and running inside the client web browser virtual machine. You also have to know that to prevent illegal accesses from the applet to the client local file system, it must be signed to allow the client to verify the its authenticity.

Before talking about how to sign applets, I will introduce the basis needed to make and run an applet:

An applet use the same technologies as a standard Java application (a JRE/JDK, libraries,...) but its main class must extends java.applet.Applet class. With the web server it must be embedded into an HTML page as the following using the applet tag:

The code attribute is used to define the canonical applet class with the appended .class suffix. The codebase attribut is not mandatory (default set to ".", the calling HTML page) is used to define from where the ressources will be downloaded. As no external libraries are specified, we assume this server layout for the above example : <codebase>/my/package/MyApplet.class

If you need to specify libraries, you must do it using the archive attribute. The archive attribute is a coma separed list of jars also using the codebase attribute value to be retrieved:

If you planned to use Java applets and want to write and read to the client file system, you have to package it into a jar and to sign it with a certificate. If you don't remember how to make a jar from your classes, go back to previous Jar section.

Signing itself is simple, you just have to use that jarsigner command like the following:

Code Block
$> jarsigner MyApplet.jar MyCertificate Enter Passphrase for keystore: \********

This command will append some files and attributes to the manifest of MyApplet.jar. This command may be used more than once if you want your jar to be signed by multiple parties.

Code Block


$> jarsigner -verify -verbose
                -certs d:\TestApplet.jar


         245 Wed Mar 10 11:48:52 PST 2000 META-INF/manifest.mf
         187 Wed Mar 10 11:48:52 PST 2000 META-INF/MYCERT.SF
         968 Wed Mar 10 11:48:52 PST 2000 META-INF/MYCERT.RSA
smk      943 Wed Mar 10 11:48:52 PST 2000 TestApplet.class
smk      163 Wed Mar 10 11:48:52 PST 2000 TestHelper.class

      X.509, CN=XXXXXXX YYY, OU=Java Software,
                O=Sun Microsystems, L=Cupertino,
                ST=CA, C=US (mycert)
      X.509, CN=Sun Microsystems, OU=Java Plug-in QA,
                O=Sun Microsystems, L=Cupertino, ST=CA, C=US
      X.509, EmailAddress=server-certs@thawte.com,
                CN=Thawte Server CA, OU=Certification
                Services Division, O=Thawte Consulting cc,
                L=Cape Town, ST=Western Cape, C=ZA


  s = signature was verified
  m = entry is listed in manifest
  k = at least one certificate was found in keystore
  i = at least one certificate was found in identity scope
keytool -genkey -keyalg rsa -dname "cn=Renaud Thirion, ou=Pfouing, o=Pfouing, l=Paris, ST=France, c=FR"
-alias pfouing_key -keypass pfouing_store_pass -keystore PFOUING -storepass pfouing_store_passParameters :
- genkey: parameter used to generate a certificate.
- keyalg: parameter indicating the algorithm used.
- dname: parameter gathering information of the person who created the certificate.
- alias: alias.
- keypass: password protecting the key.
- keystore: name of the keystore.
- storepass: password protecting the keystore.  This command will generate a file named "PFOUING" representing the keystore.  keytool \-export \-alias pfouing_key \-file certif.crt \-keystore PFOUING \-storepass pfouing_store_passParameters :
- export: parameter used to export the certificate.
- alias: alias.
- file: name of the file which will contain the certificate.
- keystore: name of the keystore.
- storepass: password protecting the keystore.  This command will generate a file named "certif.crt" containing the certificate.

Configurations

In this section you will discover the different configuration files, their loading order and why they have been introduced. Talking about all the configuration keys here is far beyond the scope of this article, only a few will be presented to cover JFreeReport core configuration.
JFreeReport is composed of several files which define configuration properties, each of them can be overriden by setting them as environment properties or using a special file made to help users and simplify the configuration process. This file has to be nammed jfreereport.properties and must be at the root of your classpath. It must be reachable for the following java code :

Code Block
ClassLoader.getSystemClassLoader().getResource("/jfreereport.properties");

Properties files (*.properties) are simply text files that expose key=value statements where lines starting with the sharp character '#' are skipped. If you need more accurate informations, have a look to the Properties class javadoc.
As I said, JFreeReport is composed of several configuration files so I will show you the order they get loaded. The last properties loaded override the ones declared by the previous ones:

The main configuration file: /org/jfree/report/jfreereport.properties
The configuration file of JFreeReport extenstions subproject: /org/jfree/report/ext/jfreereport-ext.properties
Each module configuration file using the following pattern: <path/to/module>/configuration.properties
The user configuration file we talked earlier: /jfreereport.properties
Every system properties are collected during the initialization time. (bash, command line, java api.........................)

Before JFreeReport has boot, you can eventualy define manual user properties using the following code:

Code Block
JFreeReportBoot.getInstance().setConfigProperty("somekey", "somevalue"); ... JFreeReportBoot.getInstance().start(); // boot is done later in your program

Report configuration ......

User report configuration ....
We recommand the use if the file nammed jfreereport.properties because it is usualy easier to maintain as it centralizes the user configuration in a known place and should be more resisting to migrations. A migration tool could be envisaged to very a single file not to verify your code.

//property files loading
//gui tool to configure keys

The modules

JFreeReport has been designed by keeping in mind that most of the users will not need the whole features it can provide. So all components are modularized and then configurable, changeable or removable.

//You will see in the following lists the modules...

Each module is defined and configured by two files, module.properties and configuration.properties. Whenever you decided to tune or change the default beahavior of a module, first look at these files to get informed about what is configurable. If you want to remove a module, you have two choices :

First, do not include the module in your classpath, when you are dealing with jfreereport-module-<modulename>-<version>.jar module libraries it is easy. If you do not remember what are these *.jar libraries, go back to Bundled distribution section for more explanations.

Second, desactivate them by empting their Module configuration key. Here is an example :

Code Block


# Excel GUI export module activated
org.jfree.report.modules.gui.xls.Module=org.jfree.report.modules.gui.xls.ExcelExportGUIModule
# Excel GUI export module desactivated
org.jfree.report.modules.gui.xls.Module=

Jump to section Configurations if you want to know where is the right place to put this kind of statments.

Optimizations

// use less BeanShell
// use less dynamic fields
// scrollableresultset
// try to use clones of a report to not reparse its definition
// boot one time

Uses overview

JFreeReport-ext

Pentaho

...

This documentation aims to help you working with JFreeReport 0.8 branch in your projects. Its purpose is to show you how to setup it and configure it.

It is composed of the following parts:

Getting JFreeReport - the different maners to retrieve it.
The different libraries - an overview of the libraries used.
Installation - the most important part of this guide.
Uses overview
JFreeReport-ext

Versions Compared

Old Version 8

New Version Current

Key

Getting JFreeReport

Bundled distribution

Versioning System

Building

The different libraries

Installation

Classpath setup

Jar

Using Eclipse IDE

Using IntelliJ IDE

Using Netbeans IDE

Using Borland IDE

Webapp

Applet

Configurations

The modules

Optimizations

Uses overview

JFreeReport-ext

Pentaho

Page Comparison

Versions Compared

Old Version 8

New Version Current

Key

Getting JFreeReport

Bundled distribution

Versioning System

Building

The different libraries

Installation

Classpath setup

Jar

Using Eclipse IDE

Using IntelliJ IDE

Using Netbeans IDE

Using Borland IDE

Webapp

Applet

Configurations

The modules

Optimizations

Uses overview

JFreeReport-ext

Pentaho