org.jfree.report.filter.templates

Overview

Package

Class

Use

Deprecated

Index

Home >> All >> org >> jfree >> report >> filter >> [ templates overview ]

PREV PACKAGE NEXT PACKAGE

Package org.jfree.report.filter.templates

Support for the creation of 'filter chains' used to transform data objects into other forms for presentation on reports.

See:
Description

Interface Summary

Template A template defines a common use case for a DataSource and one or more predefined Filters.

Class Summary

AbstractTemplate An abstract base class that implements the Template interface.

DateFieldTemplate A date field template.

DrawableFieldTemplate An drawable field template.

HorizontalLineTemplate Defines a horizontal line template.

ImageFieldTemplate An image field template.

ImageURLElementTemplate An image URL element template, which reads the image from a static URL.

ImageURLFieldTemplate An image URL field template, which reads the image from an URL supplied from a column in the DataRow.

LabelTemplate A label template can be used to describe static text content.

NumberFieldTemplate A number field template.

RectangleTemplate A template to create rectangle elements.

ResourceFieldTemplate A resource field template, which reads a String value from a ResourceBundle.

ResourceLabelTemplate A resource label template.

ShapeFieldTemplate A shape field template.

StringFieldTemplate A string field template.

VerticalLineTemplate Defines a horizontal line template.

Package org.jfree.report.filter.templates Description

Support for the creation of 'filter chains' used to transform data objects into other forms for presentation on reports.

Basic flow of data in JFreeReport

Three interfaces create the abstract way of the dataflow in JFreeReport.

DataSource

By default all data used in the report's elements is read from DataSource implementations. DataSource defines a single function called getValue() which returns the current value of the datasource. DataSources are stateless, and implementations should not maintain a state of the process of querying data. It is not guaranteed that DataSources are in a particular order. If you need to maintain a state or get informed of events, you should implement a function instead of using the DataSource interface.

DataTarget

A DataTarget is a container for a DataSource. A DataTarget queries the DataSource when it needs new data. All elements of the report implement the DataTarget interface and query its assigned DataSource whenever they need to print the data. DataTargets should not rely on the data type of the data returned by the DataSource. If they cannot handle the data returned by the DataSource, DataTargets should perform a controled way of errorhandling instead of just throwing exceptions. Some DataSources can return NullValues, so DataTargets will have to handle this case correctly.

DataFilter

A DataFilter is the conjunction of DataSource and DataTarget. If a DataFilter is queried to return a value, the request if forwareded to the assigned DataSource of the filter. The returned value is then processed and the result is returned.

FormatFilter and FormatParser

FormatFilter and FormatParsers are special implementations of the filter interface. Both of them are using an implementation of java.text.Format to perform parsing and formatting. Commonly used implementation are the SimpleDateFormat to format and parse java.util.Date objects and the DecimalFormat to parse and format Number instances.

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.