Functions and expressions

A rough guide to Functions and Expressions

Both Expressions and Functions are parametrized as JavaBeans by creating getter and setter methods. Both use the getValue() function to return the computed value and both should create a new fresh instance that does not share any modifiable object whenever the getInstance() method is called. If possible try to prefer Expressions over functions, as expressions are easier to write and consume less resources. Formulas added to a report, are added as "Formula-Expressions" and therefore are stateless computations.

Expressions

Expressions are stateless, that means every call to the expression's getValue() is only dependent on the Expression's parameters and the values read from the datarow. The order in which expressions are called is not guaranteed, so it can be that the expression is called for the first row, then the 10th row and then for any other row. Due to their statelessness, expressions are cheap, as we do not have to clone them all the time to save their state.

Functions

Functions are statefull computations. Functions receive events (@see the Function interface) in a defined order, and maintain and update their state on every event. As the reporting engine iterates over the data multiple time, Functions get called several time. Each iteration has a processing-level, which describes the global state of the report-processing. Processing-levels greater or equal zero are function-processing levels, where functions compute the values. Level -1 (LayoutProcess.LEVEL_COLLECT) is reserved for layout preparations and Level -2 (LayoutProcess.LEVEL_PAGINATE) computes the layout.

The order of the function processing can be controlled via the Dependency-Level property of the Function. Functions with a higher dependency level are executed before functions with a lower dependency level. Functions will not be executed until the processing reached their respective level so that they do not see invalid results.

Functions that perform running computations (like the ItemSumFunction) are easy, as they can rely on the standard clone() functionality for the state management and simply recompute everything from scratch on each processing level.

Functions that compute global values (like the TotalGroupSumFunction), where function results are available before all data for the processing level has been processed are more complicated. These functions compute the running value in their defined processing level (@see FunctionUtilities#isDefinedPrepareRunLevel(..)) and store the result in a internal storage (usually a Map). On any later processing run, they simply recall the stored value to make it possible to print the value in report- or group-headers.

The event-order functions receive is well-defined. When saving report-states, the reporting engine will clone the function. This way, for a single function-instance, the event-flow always appears linear. The event-order is documented in the Wiki: http://wiki.pentaho.com/display/Reporting/JFR8States

You can monitor the event-flow by adding the EventMonitorFunction to your report. The function computes nothing but it logs all incoming report-processing events. Usually just looking at that log output makes the processing system a lot more understandable.

Using Functions and Expressions

Functions and expression will be configured using a set of properties. Expression-properties are private to the expression instance and will not be shared with other functions. The properties are always design-time properties and cannot change during the report-processing.

Expressions that compute a value that should be reused in a field or other expression must have a name assigned. The name must be unique within the current report and must not be the same as the name of any other expression, parameter or column from the data-source within the same report.

Functions are added to the report before the report processing starts. If you use the API, you will use the MasterReport#addFunction() or MasterReport#addExpression() methods to add the function objects to the report. Functions can be added or configured dynamically by using a Report-Preprocessor.

Function dependencies

Functions may query other functions and user these foreign results for their own computations.

It is guaranteed, that all functions are executed in the order of their dependency level. Functions with an higher dependency are executed before any function with an lower dependency. The execution order of functions with the same dependency level is undefined. Functions within the same dependency level are executed in the order they have been added to the report.

When using the API, the dependency level is read by "getDependencyLevel()" and can be set with "setDependencyLevel(int)".

By default all user functions have the dependency of "0", the lowest possible level. System functions like the page layouter have a dependecy level of -1 or lower to make sure that all user defined expressions are evaluated before we try to create content. You cannot set the dependency of normal functions or expressions lower than '0'.

Dependencies between Expressions are not resolved automatically. The order of the expressions on the report determines the evaluation order in the report. A expression that references an other expression's value that is computed after the current expression will behave non-deterministic, as it will receive an old and invalid value from the datarow.

Implementing Expressions and Functions

Writing the Java Classes

Expressions are simple and easily explained: Expression have the method

Object getValue()

To minimize your implementation effort and to shield you against future changes to any management properties, we recommend that you use "AbstractExpression" as base-class for expressions.

which is called when the expression is queried. All expression have to override this method to perform the calculation and to return the value.

Functions are slightly more complex:
Functions have several notification methods, where the system informs the function that a new event is processed.

public void pageStarted (ReportEvent event);
public void reportStarted (ReportEvent event);
public void groupStarted (ReportEvent event);
public void itemsStarted (ReportEvent event);
public void itemsAdvanced (ReportEvent event);
public void itemsFinished (ReportEvent event);
public void groupFinished (ReportEvent event);
public void reportFinished (ReportEvent event);
public void pageFinished (ReportEvent event);

By using the Event-object, you have access to the ReportState. The state can be used for getting the current group, current item and for gaining access to the dataRow. In case you want to manipulate the ReportElements, you also have access to the MasterReport object.

To minimize your implementation effort and to shield you against future changes to any management properties, we recommend that you use "AbstractFunction" as base-class for your functions.

As with every function, a single function can return one value, something mathematicians express like y = f(x) where x is the data from your report processing.

The expression value is returned by the "getValue()" function. You can return any Object, but make sure, that this object does not get modified anymore after it was returned to the caller. (A simple way to obey to this rule is to create a new object whenever the computed object changes).

The expression implementation is loaded via its default constructor by the report parser, all function implementations that are expected to be used from within the xml-definitions must define a public default constructor. The functions implementation is defined by specifying the "class" attribute of the "function" tag and is loaded by using the default class loader. Your expression implementation must be in the classloaders classpath. To see the expression in the report-designer and to ensure a correct serialization and deserialization to and from XML, make sure you have metadata declared for your expression and injected it into the boot-process.

Declaring an extension module and providing the Meta-data

Todo

The life cycle of functions

Functions are objects and are constructed like any other object using an constructor. The function implementation is loaded via its default constructor by the report parser, all function implementations which should be used from within the xml-definitions must define a public default constructor. The functions implementation is defined by specifiying the "class" attribute of the "function" tag and is loaded by using the default class loader. Your function implementation must be in the classloaders classpath.

After constructing the function or expression, the properties of the function will be set. The xml parsers use calls to the setProperty() method of the function or expression to set the function. The parser will not use any possibly defined accessor method (getter/setter) to set the properties.

Before functions can be used, they need to be initialized. The main purpose of this method is to verify that the function is defined properly and that all required properties are set. During the initialisation of the report function, you won't have access to the report object or the report properties or report configuration. The initialize() method is the place to check whether the functions parameters are correctly set, not to do any work.

Note: The BeanShell expression uses this method to compile the beanshell script, the script has to take care that the dataRow reference is null at this moment.

If you want to initialize certain values depending on the report configuration or the report definition, you will have to relocate your code from the method initialize() into the method reportInitialized(ReportEvent event), At this point you have full access to the report definition and all helper objects.

The method getProperty does not access the report properties, it accesses the functions properties. These properties store the function parameters and are set within the function declaration:

There is a fundamental difference between ReportProperties and function properties: Report properties are bound to the report object, which is accessible via report.getProperties().getProperty(). Be aware that within a function you don't have access to the original JFreeReport object, all report related operations are performed by using the ReportDefinition object from the current report event.

During the event handler methods, you can access the datarow of the current report event to query the current row of the tablemodel, other expressions and functions or the report properties.

Data is fed into the function/expression by using a DataRow object. This object provides the (among others) these methods

Object get(String name);
Object get(int columnName); // DEPRECATED.

to read the values of a function, expression, a column from the tablemodel or a ReportProperty (which must be marked as datasource before).

As with every function, a single function can return one value, something mathematicans express like y = f, where x is the data from your report processing.

The functions or expressions computed value is returned by the "getValue()" function. You can return any Object, but make sure, that this object does not get modified anymore after it was returned to the caller. (A simple way to obey to this rule is to create a new object whenever the computed object changes).

Function specific lifecycle

Functions live in an own environment, separated from the outside world. Changing the original JFreeReport object does not affect the inner JFreeReport-Object. You are also unable to add new Functions or expressions to the report from inside, so all functions and expression have to be set and initialized before the report processing has begun.

All Functions have to be cloneable. It is not guaranteed that the report is processed in an linear order, but it is guaranteed that a single instance of a function does pass a reportstate only once.

That means: When processing the report, the system clones the functions on certain save-points (for instance whenever a page is finished). This saved copy can later be used to restart the report processing on that saved point. The copy-state made will never return to a previous save point, but it can (and certainly will occur) that this copy is used to process the report from that saved point on.

So when saving a state after page 2, it will never happen, that this page-2-copy gets used to process page 2 a second time, but it could happen that copies of this page-2-state process the page 3 again and again.

The best way to avoid cloning problems is to use Unmodifiable objects or primitive datatypes when storing a state. Using java.lang.String, one of the java.lang.Number implementers or any other unmodifiable object type is always save. If you use complex objects, lists or hashtables and you get weird results, try to implement a deep-object-copy in the clone() method of the function for these objects.

Event order for functions

A function receives the following events in the given order:

ReportInitialized event

(pageStarted event)

prepareEvent (ReportStarted)
ReportStarted event

prepareEvent (GroupStarted)
GroupStarted event

prepareEvent (ItemsStarted)
ItemsStarted event

prepareEvent (ItemsAdvanced)
ItemsAdvanced event

prepareEvent (ItemsFinished)
ItemsFinished event

prepareEvent (GroupFinished)
GroupFinished event

prepareEvent (ReportFinished)
ReportFinished event

prepareEvent (ReportDone)
ReportDone event

(PageFinished event)

The prepare events are used to inform the listeners, that the next state is going to be processed. When this event is thrown, no change was done by the state yet. The main purpose of these events is to help the function to clean up its internal states before the new state is beeing processed. The PageLayouter functions starts a new page and print eventually contained spooled bands after a pagebreak was done, when this event is received.

The page events are inserted whenever needed. They are a little bit tricky to handle right now, but this will change with the next release ? then this part of the documentation handling the page events will be completed.

If you want to see, which and when events are fired during the report processing, you may want to include the EventMonitorFunction into your report. This function does not return any values, but prints a lot of log messages whenever an event is sent to that function.

Browser not supported