Other Properties of a Variable

The most complex property of a variable is its temporal value. Since its expression is evaluated at every iteration, it is important to understand which value has a variable, and at which time. This can be complicated, considering that a variable can use other variables inside its expression. For these reasons there are mechanisms that can be used to simplify the evaluation or the reading of the variable value during the iterations.

Evaluation Time

The evaluation time is not an attribute of the variable but of the elements that can use variables in their expressions (like a Text Field) and define the "time" when the value of the variable should be read. A variable can potentially change value at every iteration, so a value read at one time may be different from the one obtained during another time. So for every element that can define an expression is possible to say when evaluate it. And since in the expression could be defined one or more variables this parameter also influences also when these variables are read.

The possible values are:

Report: The value of the expression is evaluated ad the end of the report.
Page: The value of the expression is evaluated at the end of every page of the report.
Column: The value of the expression is evaluated at the end of each column (if the report is composed only of a column this is equivalent to Page).
Group: The value of the expression is evaluated after the break of the specified group. This option is visible only if at least one group is defined.
Band: The value of the expression is evaluated after the end of the band where the element with this evaluation time is placed. This is a very particular case, introduced to wait that the other elements in the band are completely created. Typically the value of the variables are read at the start of the band, but for example suppose to have a subreport with an output parameter to print in the main report. To print this parameter it must be read when the subreport was already computed, so the value could be printed when the band is completely created, in this cases the Band evaluation time is necessary.
Auto: This is used when in the expression of the element there are more variables and fields, that need to be evaluated at different times. The variables are evaluated at a time corresponding to their Reset Type (see below for more information), instead the fields are always evaluated at time -now. This type is useful when report elements have expressions that combine values evaluated at different times (for example, percentage out of a total).
Now: The value of the expression is evaluated after the read of every record, so at every iteration, this is the default behavior.

Calculation Function

A calculation function is an attribute of a variable that defines when the variable can be used in association with the expression to determinate the value of the variable. When using a calculation function, the value of the variable is not determinate directly by its expression. Instead, it is passed to the calculation function that uses it (depending on the function) to calculate the variable value.

There are many functions built-in to Jaspersoft Studio:

Sum: At every iteration the value of the expression is taken it is summed at the value of the variable. This is one of the cases where the initial value is really important.
Count: At every iteration the variable value is incremented by one unit. This only if the expression is different from null, in that case the value of the variable is left unchanged.
Distinct Count: At every iteration the variable value is incremented by one unit, but only if the value of the expression was never returned before.
Average: The value of the variable is the arithmetic average of all values received in input from the expression.
Lowest: The variable take the value of the lowest element received from the expression.
Highest: The variable take the value of the highest element received from the expression.
Standard Deviation: The standard deviation of all the value received from the expression.
First: The variable take the value from the first value returned by the expression.
System: No calculation is done and the expression is not evaluated, the value of this variable is the last value set on it. Useful to store partial results or the final result of a computation.

Increment Type

As stated above, when a calculation function is defined, the value of the expression is passed to the function that calculates the variable. The default behavior is to do this for every record read, but sometimes a different behavior is desired. Using the increment type parameter is possible to change the "time" on which the calculation function is used.

The possible values for this attribute are:

Report: The Calculation Function is called only at the end of the report, passing to it the value of the expression at that moment.
Page: The Calculation Function is called at the end of each page, passing to it the value of the expression at that moments.
Column: The Calculation Function is called at the end of each column (if the report is composed only of a column this is equivalent to Page).
Group: The Calculation Function is called at the start of every occurrence of the specified group. This option is visible only if at least one group is defined.
None: The Calculation Function is called after the read of every record, this is the default behavior.

Remember that the expression is evaluated at every record read, independently from the increment type selected, but the calculation function is used only when the times match those defined in the increment type.

Reset Type

The reset type defines when a variable should be reset to the initial value, or to null if an initial value is undefined. This is useful when the variable is used to compute a partial value, such a sum or an average of only some of the records read.

The possible values for this attribute are:

Report: The variable is initialized only one time at the beginning of the report creation.
Page: The variable is initialized on each page.
Column: The variable is initialized again in each new column (if the report is composed only of a column this is equivalent to Page).
Group: The variable is initialized at the start of every occurrence of the specified group. This option is visible only if at least one group is defined.
None: The variable is never initialized, so the initial value expression is ignored.

Incrementer Factory Class Name

The calculation functions are useful but are also generics and limited at the numeric types. You may have a case where something more specific is needed. Suppose you have a field of type String and you want to concatenate the value read. You can do this by defining a new Incrementer. An incrementer is a piece of java code that extends the interface JRIncrementerFactory, and can build a personalized calculation function to do what you need. Every calculation function receives the expression value and the variable value and returns the result of the increment, so there is everything needed to do the calculation and return the right value.

Version: 
Feedback