Versions Compared

Old Version 7

changes.mady.by.user Former user

Saved on

compared with

New Version 8

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Wiki Markup
{scrollbar}\\

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

h2. 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|01. Bundle distribution] section.
{code}
# 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
{code}\\

Running the demo application is meaningless but it shows you how to specify classpath entries, all you have to do in your applications is to append your 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}
$> java -jar jfreereport-demo-<version>.jar
{code}\\

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.

h3. 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 an 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}
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
{code}\\

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}
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
{code}\\
{note:title=TODO}these manifest define too much libraries, check if it is a problem or not.
{note}
\\

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

Here is a little reminder on how about to create a jar using the *jar* command:
{code}
$> jar cf <filename>.jar <files and directories to package>
{code}\\

Or this one if you want to specify a manifest file:
{code}
$> jar cfm <manifestfile> <filename>.jar <files and directories to package>
{code}\\

If you want more information about Jars you should perhaps have a look at [Sun Jar tutorial|http://java.sun.com/docs/books/tutorial/deployment/jar/] page.

h3. Using Eclipse IDE


h3. Using IntelliJ IDE


h3. Using Netbeans IDE


h3. Using Borland IDE


h3. Webapp


h3. 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 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. Within the web server it must be embedded into an HTML page as the following using the applet tag:
{code}
<applet code="my.package.MyApplet.class" width="200" height="200" codebase="applet/">
</applet>
{code}\\

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:
{code}
<applet code="my.package.MyApplet.class" width="200" height="200" codebase="applet/"
archive="jfree/jfreereport-0.8.7-10.jar">
</applet>
{code}\\

If you need more informations about using applets you should have a look at [Sun applet|http://java.sun.com/docs/books/tutorial/deployment/applet] page.

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.
First of all you will need a certificate and as I guess you are in a development "phase", and you don't want to bother with a real paid certificate, I will show you how to create a self signed certificate.
{code}
 c c:\temp>"c:\Program Files\Java\jdk1.6.0\bin\keytool.exe" -genkey -keyalg rsa -keystore MyKeystore.jks -alias MyAlias
Tapez le mot de passe du Keystore : <pass1>
Ressaisissez le nouveau mot de passe : <pass1>
Quels sont vos prÚnom et nom ?
  [Unknown] :  MyName
Quel est le nom de votre unitÚ organisationnelle ?
  [Unknown] :  MyOrg
Quelle est le nom de votre organisation ?
  [Unknown] :  MyCorp
Quel est le nom de votre ville de rÚsidence ?
  [Unknown] :  MyCity
Quel est le nom de votre Útat ou province ?
  [Unknown] :  MyCountry
Quel est le code de pays Ó deux lettres pour cette unitÚ ?
  [Unknown] :  FR
Est-ce CN=MyName, OU=MyOrg, O=MyCorp, L=MyCity, ST=MyCountry, C=FR ?
  [non] :  oui

SpÚcifiez le mot de passe de la clÚ pour <pass2>
        (appuyez sur EntrÚe s'il s'agit du mot de passe du Keystore) :
Ressaisissez le nouveau mot de passe : <pass2>
{code}\\
{code}
 cc:\temp>"c:\Program Files\Java\jdk1.6.0\bin\keytooljarsigner.exe" -list -keystore MyKeystore
Tapez le mot de passe du Keystore : <pass1>

Type Keystore : JKS
Fournisseur Keystore : SUN

Votre Keystore contient 1 entrÚe(s)

mykey, 18 dÚc. 2006, PrivateKeyEntry,
Empreinte du certificat (MD5) : 40:BA:53:53:02:6D:04:4F:1F:B9:95:F4:9D:5A:B9:83
{code}.jks d:\temp\jfreereport-0.8.7-10\jfreereport-0.8.7-10\jfreereport-0.8.7-10.jar MyAlias
Enter Passphrase for keystore: <pass1>
Enter key password for MyAlias: <pass2>

Warning:
The signer certificate will expire within six months
{code}\\
{code}
c:\temp>"c:\Program Files\Java\jdk1.6.0\bin\keytool.exe" -keystore MyKeystore.jks -alias MyAlias -export -file MyCert.crt
Tapez le mot de passe du Keystore : <pass1>
Certificat enregistrÚ dans le fichier <MyCert.crt> 
{code}
Signing itself is simple, you just have to use that *jarsigner* command like the following:
{code}
$> jarsigner MyApplet.jar MyCert.crt
Enter Passphrase for keystore: \********
{code}
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.crt>
{code}\\

Signing itself is simple, you just have to use that *jarsigner* command like the following:
{code}
$> jarsigner MyApplet.jar MyCert.crt
Enter Passphrase for keystore: \********
{code}\\

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}
c:\temp>"c:\Program Files\Java\jdk1.6.0\bin\jarsigner.exe" -keystore MyKeystore.jks -verify -verbose -certs d:\temp\jfreereport-0.8.7-10\jfreereport-0.8.7-10\jfreereport-0.8.7-10.jar
      146106 Mon Dec 18 22:56:22 CET 2006 META-INF/MANIFEST.MF
      145992 Tue Dec 19 21:27:30 CET 2006 META-INF/MYALIAS.SF
         913 Tue Dec 19 21:27:30 CET 2006 META-INF/MYALIAS.RSA
           0 Thu Nov 02 14:36:40 CET 2006 META-INF/
smk      298 Thu Nov 02 14:36:36 CET 2006 loader.properties

      X.509, CN=MyName, OU=MyOrg, O=MyCorp, L=MyCity, ST=MyCountry, C=FR (myalias)
      [certificate will expire on 19/03/07 21:25]

           0 Thu Nov 02 14:36:12 CET 2006 org/
           0 Thu Nov 02 14:36:12 CET 2006 org/jfree/
           0 Thu Nov 02 14:36:36 CET 2006 org/jfree/report/
smk      886 Thu Nov 02 14:36:12 CET 2006 org/jfree/report/Anchor.class

      X.509, CN=MyName, OU=MyOrg, O=MyCorp, L=MyCity, ST=MyCountry, C=FR (myalias)
      [certificate will expire on 19/03/07 21:25]

smk      487 Thu Nov 02 14:36:12 CET 2006 org/jfree/report/AnchorElement.class

      X.509, CN=MyName, OU=MyOrg, O=MyCorp, L=MyCity, ST=MyCountry, C=FR (myalias)
      [certificate will expire on 19/03/07 21:25]

...

  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

jar verified.
{code}\\ \\
{code}
$> 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_pass

Parameters :
- 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_pass

Parameters :
- 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.
{code}\\

h2. 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}
ClassLoader.getSystemClassLoader().getResource("/jfreereport.properties");
{code}\\

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|http://java.sun.com/j2se/1.4.2/docs/api/java/util/Properties.html] 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}
JFreeReportBoot.getInstance().setConfigProperty("somekey", "somevalue");
...
JFreeReportBoot.getInstance().start();  // boot is done later in your program
{code}\\ \\
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 verify a single file not to verify all your code.

{color:#ff0000}//property files loading{color}
{color:#ff0000}//gui tool to configure keys{color}

h2. 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.

{color:#ff0000}//You will see in the following lists the modules...{color}

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}
# 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=
{code}\\

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

h3. Optimizations

{color:#ff0000}// use less BeanShell{color}
{color:#ff0000}// use less dynamic fields{color}
{color:#ff0000}// scrollableresultset{color}
{color:#ff0000}// try to use clones of a report to not reparse its definition{color}
{color:#ff0000}// boot one time{color}