Package org.pentaho.reporting.engine.classic.core.filter

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

See: Description

Interface Summary

Interface	Description
DataFilter	A data filter is a combined input-/out target.
DataSource	A DataSource is a producer in the data chain.
DataTarget	A DataTarget is a consumer in the DataProcessing chain.
RawDataSource	The raw data source allows direct access to the filtered raw data.

Class Summary

Class	Description
AnchorFilter	Deprecated The anchor filter is deprecated now.
ComponentDrawableFilter	A filter that wraps AWT- and Swing-components into a Drawable implementation.
DataRowDataSource	A DataSource that can access values from the 'data-row'.
DateFormatFilter	A filter that creates string from dates.
DateFormatParser	Parses a String into a java.util.Date.
DecimalFormatFilter	A filter that formats the numeric value from a data source to a string representation using the decimal number system as base.
DecimalFormatParser	A filter that parses string values from a data source to a number using the decimal numeric system as base.
DrawableLoadFilter	The DrawableLoadFilter is used to load drawable image files (like WMF's) during the report generation process.
EmptyDataSource	A data source that always returns null.
FormatFilter	The base class for filters that format data.
FormatParser	A format parser tries to parse a string into an object.
FormatSpecification	The FormatSpecification classifies a format string into the 4 known classes of format-strings of Java.
ImageLoadFilter	The image load filter is used to load images during the report generation process.
ImageRefFilter	A filter that converts an Image to an ImageReference.
MessageFormatFilter	A filter that formats values from a data source to a string representation.
MessageFormatSupport	The message format support class helps to translate named references to fields in a message format string into numeric index positions.
NumberFormatFilter	A filter that formats the numeric value from a data source to a string representation.
NumberFormatParser	A filter that parses the numeric value from a data source string into a number representation.
ResourceFileFilter	Lookup a key from a datasource using a ResourceBundle.
ResourceMessageFormatFilter	A filter that formats values from the datarow using a message format object.
ShapeFilter	A shape filter.
SimpleDateFormatFilter	A filter that creates string from dates.
SimpleDateFormatParser	Parses a String into a java.util.Date.
StaticDataSource	A data source that returns a constant value.
StringFilter	A filter that returns the value from a data source as a String.
URLFilter	The URLFilter forms URLs from Strings ,Files and URLs.

Package org.pentaho.reporting.engine.classic.core.filter 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.pentaho.reporting.engine.classic.core.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.