org.jfree.report.filter

Basic flow of data in JFreeReport

DataSource

DataTarget

DataFilter

FormatFilter and FormatParser

A FormatFilter implementation will try to create a string representation of an object using the parse method of its assigned java.text.Format object. It is guaranteed that a FormatFilter will return a default not null String in case that getValue() returns invalid values. This default string is defined by setNullString (String).

A FormatParser implementation will try to parse a String read from its DataSource into an object. The actual work of parsing is delegated to the java.text.Formats parse method. If the string was null or invalid, and parsing was unable to create an object, a predefined value can be returned instead of null.

Common use cases of Filters

• label

  The label prints predefined text in the report and is mostly used to name fields and columns

  The label uses a StaticDataSource to contain its datavalue. This DataSource is contained in the default StringFilter of org.jfree.report.TextElement. The TextElements StringFilter will convert the static value into a string before it gets printed in the report.

• number-field

  The number field reads its value from the reports datasource and formats the value using a decimal format, before the string representation is printed.

  The number-field uses a ReportDataSource to obtain values from the reports datamodel. These values are fed into a NumberFormatFilter, where they get formated using the java.text.DecimalFormat, resulting in a string. The TextElement will check the returned value, as this is a string, nothing is done and the string is printed.
  In case the NumberFormat failed to format the value read from the source, it would return a null value to the TextElement to be printed. Now the TextElement's StringFilter will check the value, and return the predefined NullValue-String instead of null.

• date-function

  The date function field queries the results of a function, and formats the function's return value into a string. The contents of this string can be defined using a format pattern as defined in java.text.SimpleDateFormat.

  The date-function uses a FunctionDataSource to obtain values from the reports function collection. These values are fed into a SimpleDateFormatFilter, where they get formated using the java.text.SimpleDateFormat, resulting in a string. The TextElement will check the returned value, as this is a string, nothing is done and the string is printed.
  In case the DateFormat failed to format the value read from the source, it would return a null value to the TextElement to be printed. Now the TextElement's StringFilter will check the value, and return the predefined NullValue-String instead of null.

These examples should give an idea what can be done with the filters. As filters can contain other filters, you are free to create any combination and put them into the elements.

DataRowConnectable

Elements are connected to the Report's DataSources using a DataRow as connector. The DataRow unifies the access to functions, expressions and the tablemodel. DataSources that need to access one of these sources should use the DataRowDataSource as primary datasource. The specialized sources for accessing Functions and the Reports TableModel should not be used.

This filter will parse strings using a java.text.DecimalFormat to create the numeric value for the string from the datasource.