03. Configuration

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 :

getClass().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 previously:

1. The main configuration file: /org/jfree/report/jfreereport.properties
2. The configuration file of JFreeReport extenstions subproject: /org/jfree/report/ext/jfreereport-ext.properties
3. Each module configuration file using the following pattern: <path/to/module>/configuration.properties
4. The user configuration file we talked earlier: /jfreereport.properties
5. Every system properties are collected during the initialization time. It gives an easy way to configure properties without editing a file, generaly for test purposes.
   Using the java command line:

   java -D<property>=<value> ...
   

   Using the bash interpreter:

   # On Windows environments
   $> set <property>=<value>
   # On Unix environments
   $> export <property>=<value>
   # Then run your command
   
   # On Unix environments you can also define per command system properties
   $> <property>=<value> yourCommand
   

   Using the java API:

   System.setProperty("somekey", "somevalue");
   

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

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

7. Per report user configuration properties which can be setted using the following code:

   report.getReportConfiguration().setConfigProperty("somekey", "somevalue");
   

   This kind of configuration can also be feeded from the XML report definition:

   // Simple XML definition
   <report>
   ...
     <configuration>
       <!-- <property name="property">value</property> -->
       <property name="org.jfree.report.modules.output.pageable.pdf.Encoding">Identity-H</property>
       <property name="org.jfree.report.modules.output.pageable.pdf.EmbedFonts">true</property>
       <property name="org.jfree.report.targets.table.TableWriter.SheetNameFunction">sheetNameExpression</property>
       ...
     </configuration>
   ...
   </report>
   
   // Extended XML defintion
   <report-definition>
   ...
     <report-config>
     ...
       <configuration>
         <property name="org.jfree.report.modules.output.pageable.pdf.Author">Darkwing Duck</property>
         <property name="org.jfree.report.modules.output.pageable.pdf.Encoding">iso-8859-15</property>
         ...
       </configuration>
     ...
     </report-config>
     ...
   </report-definition>
   

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.