JRVariable (JasperReports 6.1.1 API)

All Superinterfaces:

Cloneable, JRCloneable

All Known Implementing Classes:

JRBaseVariable, JRDesignVariable, JRFillVariable
```
public interface JRVariable
extends JRCloneable
```
An interface for implementing classes that deal with report variables. This interface defines constants for names of built-in variables and for reset, increment and calculation types.
Report Variables
Report variables are special objects built on top of a report expression. They can simplify the report template by isolating in one place an expression that is heavily used throughout the report template, and they can perform various calculations based on the corresponding expression.
In its expression, a variable can reference other report variables, fields, or parameters. With every iteration through the data source, variables are evaluated/incremented in the same order as they are declared. Therefore, the order of variables as they appear in the report template is very important.
Variable Name
Just as for parameters and fields, the name attribute of the <variable> element is mandatory and allows referencing the variable by its declared name in report expressions.
Variable Class
The class attribute contains the name of the class to which the variable values belong. The default is java.lang.String, but you can declare report variables of any class as long as the class is available in the classpath, both at report-compilation time and report-filling time.
Reset Type
The value of a report variable can change with every iteration, but it can be brought back to the value returned by its initial value expression at specified times during the report filling process. This behavior is controlled using the resetType attribute, which indicates when the variable should be reinitialized during the report-filling process. There are five reset types for a variable:
- None - The variable will never be initialized using its initial value expression and will only contain values obtained by evaluating the variable's expression
- Report - The variable is initialized only once, at the beginning of the report-filling process, with the value returned by the variable's initial value expression
- Page - The variable is reinitialized at the beginning of each new page.
- Column - The variable is reinitialized at the beginning of each new column
- Group - The variable is reinitialized every time the group specified by the resetGroup attributes breaks
Reset Group
If present, the resetGroup attribute contains the name of a report group and works only in conjunction with the resetType attribute, whose value must be resetType="Group".
Increment Type
This property lets you choose the exact moment to increment the variable. By default, variables are incremented with each record in the data source, but in reports with multiple levels of data grouping, some variables might calculate higher-level totals and would need to be incremented only occasionally, not with every iteration through the data source.
This attribute uses the same values as the resetType attribute, as follows:
- None - The variable is incremented with every record during the iteration through the data source
- Report - The variable never gets incremented during the report filling process.
- Page - The variable is incremented with each new page.
- Column - The variable is incremented with each new column.
- Group - The variable is incremented every time the group specified by the incrementGroup attributes breaks
Increment Group
If present, the incrementGroup attribute contains the name of a report group. It works only in conjunction with the incrementType attribute, whose value must be incrementType="Group".
Calculations
As mentioned, variables can perform built-in types of calculations on their corresponding expression values. Following are described all the possible values for the calculation attribute of the <variable> element.

Nothing

This is the default calculation type that a variable performs. It means that the variable's value is recalculated with every iteration in the data source and that the value returned is obtained by simply evaluating the variable's expression.

Count

A count variable includes in the count the non-null values returned after evaluating the variable's main expression, with every iteration in the data source. Count variables must always be of a numeric type. However, they can have non-numeric expressions as their main expression since the engine does not care about the expression type, but only counts for the non-null values returned, regardless of their type.
Only the variable's initial value expression should be numeric and compatible with the variable's type, since this value will be directly assigned to the count variable when initialized.

DistinctCount

This type of calculation works just like the Count calculation, the only difference being that it ignores repeating values and counts only for distinct non-null values.

Sum

The reporting engine can sum up the values returned by the variable's main expression if this type of calculation is chosen; but make sure the variable has a numeric type. One cannot calculate the sum of a java.lang.String or java.util.Date type of report variable unless a customized variable incrementer is used.

Average

The reporting engine can also calculate the average for the series of values obtained by evaluating the variable's expression for each record in the data source. This type of calculation can be performed only for numeric variables.

Lowest and Highest

Choose this type of calculation when you want to obtain the lowest or highest value in the series of values obtained by evaluating the variable's expression for each data source record.

StandardDeviation and Variance

In some special reports, you might want to perform more advanced types of calculations on numeric expressions. JasperReports has built-in algorithms to obtain the standard deviation and the variance for the series of values returned by evaluation of a report variable's expression.

System

This type of calculation can be chosen only when you don't want the engine to calculate any value for the variable. That means you are calculating the value for that variable yourself, almost certainly using the scriptlets functionality of JasperReports. For this type of calculation, the only thing the engine does is to conserve the calculated value from one iteration in the data source to the next.

First

When using the calculation type First, the variable will keep the value obtained after the first incrementation and will not change it until the reset event occurs.

Here is a simple report variable declaration that calculates the sum for a numeric report field called Quantity:
```
   <variable name="QuantitySum" class="java.lang.Double" calculation="Sum">
     <variableExpression>$F{Quantity}</variableExpression>
   </variable>
```
If you want the sum of this field for each page, here's the complete variable declaration:
```
   <variable name="QuantitySum" class="java.lang.Double" resetType="Page" calculation="Sum">
     <variableExpression>$F{Quantity}</variableExpression>
     <initialValueExpression>new Double(0)</initialValueExpression>
   </variable>
```
In this example, the page sum variable will be initialized with zero at the beginning of each new page.
Incrementers
All calculations in the JasperReports engine are performed incrementally. This is obvious for variables that calculate counts, sums, or the highest and lowest value of a series, but is also true for more complex calculations like average or standard deviation. There are formulas that allow updating the average value of a series when a new element is added, so the average is updated with each iteration through the data source.
JasperReports provides a built-in set of calculations that depend on the type of the data involved. You can also create custom calculation capabilities using simple interfaces.
If a variable needs to perform a certain type of calculation on some special data, implement the JRIncrementer interface and associate that implementation with a report variable that shows the JasperReports engine how to handle that custom calculation.
To associate custom types of calculations with a given report variable, set the incrementerFactoryClass attribute to the name of a class that implements the JRIncrementerFactory interface. The factory class will be used by the engine to instantiate incrementer objects at runtime depending on the calculation attribute set for the variable.
Such customized calculations could be useful for making JasperReports sum up java.lang.String values or for teaching it how to calculate the average value of some custom-made numeric data (third-party optimized implementations of big decimal numbers, for instance).
GroupName_COUNT Built-In Variable
When declaring a report group, the engine will automatically create a count variable that will calculate the number of records that make up the current group (number of records processed between group ruptures).
The name for this variable comes from the name of the group it corresponds to, suffixed with the "_COUNT" sequence. It can be used like any other report variable, in any report expression (even in the current group expression like you can see done in the "BreakGroup" of the jasper sample).
Author:

Teodor Danciu (teodord@users.sourceforge.net)

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`COLUMN_COUNT` This variable contains the number of records that were processed when generating the current column.
`static String`	`COLUMN_NUMBER` Built-in variable containing the current column number.
`static String`	`MASTER_CURRENT_PAGE` A variable that provides the current master report page number.
`static String`	`MASTER_TOTAL_PAGES` A variable that provides the number of master report pages.
`static String`	`PAGE_COUNT` Built-in variable containing the number of records that were processed when generating the current page.
`static String`	`PAGE_NUMBER` Built-in variable containing the current page number.
`static String`	`REPORT_COUNT` Built-in variable that contains the total number of records read from the datasource.

Method Summary

Methods
Modifier and Type	Method and Description
`CalculationEnum`	`getCalculationValue()` Gets the variable calculation type.
`JRExpression`	`getExpression()` Returns the main expression for this variable.
`Class<?>`	`getIncrementerFactoryClass()` Returns the class of the incrementer factory used for choosing the right incrementer for the variable value.
`String`	`getIncrementerFactoryClassName()` Returns the string name of the variable value class.
`JRGroup`	`getIncrementGroup()` Returns the group whose break triggers the variable increment.
`IncrementTypeEnum`	`getIncrementTypeValue()` Gets the variable increment type.
`JRExpression`	`getInitialValueExpression()` Returns the initial value expression for this variable.
`String`	`getName()` Returns the name of the variable.
`JRGroup`	`getResetGroup()` Returns the group whose break triggers the variable reset.
`ResetTypeEnum`	`getResetTypeValue()` Gets the variable reset type.
`Class<?>`	`getValueClass()` Returns the class of the variable value.
`String`	`getValueClassName()` Returns the string name of the variable value class.
`boolean`	`isSystemDefined()` Returns `true` if the variable calculation type is system defined.

Methods inherited from interface net.sf.jasperreports.engine.JRCloneable
clone

- Field Detail
  - REPORT_COUNT
```
static final String REPORT_COUNT
```
    Built-in variable that contains the total number of records read from the datasource. After finishing iterating throught the datasource, it will contain the total number of records that were processed.
    
    See Also:
    Constant Field Values
  - PAGE_COUNT
```
static final String PAGE_COUNT
```
    Built-in variable containing the number of records that were processed when generating the current page.
    
    See Also:
    Constant Field Values
  - COLUMN_COUNT
```
static final String COLUMN_COUNT
```
    This variable contains the number of records that were processed when generating the current column.
    
    See Also:
    Constant Field Values
  - PAGE_NUMBER
```
static final String PAGE_NUMBER
```
    Built-in variable containing the current page number. At the end of the report filling process, it will contain the total number of pages for the resulting document.
    
    See Also:
    Constant Field Values
  - COLUMN_NUMBER
```
static final String COLUMN_NUMBER
```
    Built-in variable containing the current column number.
    
    See Also:
    Constant Field Values
  - MASTER_CURRENT_PAGE
```
static final String MASTER_CURRENT_PAGE
```
    A variable that provides the current master report page number.
    It can only be used in text elements with Master evaluation time, it evaluates to null before the moment in which master elements are resolved.
    
    See Also:
    Constant Field Values
  - MASTER_TOTAL_PAGES
```
static final String MASTER_TOTAL_PAGES
```
    A variable that provides the number of master report pages.
    It can only be used in text elements with Master evaluation time, it evaluates to null before the moment in which master elements are resolved.
    
    See Also:
    Constant Field Values
- Method Detail
  - getName
```
String getName()
```
    Returns the name of the variable. Since all variables are stored in a map, the variable names are the keys in the map.
    
    Returns:
    a string containing the variable name
  - getValueClass
```
Class<?> getValueClass()
```
    Returns the class of the variable value. Any class is allowed as long as it is in the classpath at compile and run time.
    
    Returns:
    a Class instance representing the variable value class
  - getValueClassName
```
String getValueClassName()
```
    Returns the string name of the variable value class.
  - getIncrementerFactoryClass
```
Class<?> getIncrementerFactoryClass()
```
    Returns the class of the incrementer factory used for choosing the right incrementer for the variable value.
    
    Returns:
    the Class instance of the incrementer factory
    See Also:
    JRIncrementer, JRIncrementerFactory
  - getIncrementerFactoryClassName
```
String getIncrementerFactoryClassName()
```
    Returns the string name of the variable value class.
  - getResetTypeValue
```
ResetTypeEnum getResetTypeValue()
```
    Gets the variable reset type.
    
    Returns:
    a value representing one of the reset type constants in ResetTypeEnum
  - getIncrementTypeValue
```
IncrementTypeEnum getIncrementTypeValue()
```
    Gets the variable increment type.
    
    Returns:
    a value representing one of the reset type constants in IncrementTypeEnum
  - getCalculationValue
```
CalculationEnum getCalculationValue()
```
    Gets the variable calculation type.
    
    Returns:
    a value representing one of the calculation type constants in CalculationEnum
  - isSystemDefined
```
boolean isSystemDefined()
```
    Returns true if the variable calculation type is system defined.
    
    See Also:
    CalculationEnum.SYSTEM
  - getExpression
```
JRExpression getExpression()
```
    Returns the main expression for this variable. The expression must be numeric for certain calculation types.
    
    Returns:
    a JRExpression instance containing the expression.
  - getInitialValueExpression
```
JRExpression getInitialValueExpression()
```
    Returns the initial value expression for this variable. The expression must be numeric for certain calculation types.
    
    Returns:
    a JRExpression instance containing the initial expression.
  - getResetGroup
```
JRGroup getResetGroup()
```
    Returns the group whose break triggers the variable reset. Only used when getResetTypeValue() returns ResetTypeEnum.GROUP.
  - getIncrementGroup
```
JRGroup getIncrementGroup()
```
    Returns the group whose break triggers the variable increment. Only used when getIncrementTypeValue() returns IncrementTypeEnum.GROUP.

Interface JRVariable

Report Variables

Variable Name

Variable Class

Reset Type

Reset Group

Increment Type

Increment Group

Calculations

Incrementers

GroupName_COUNT Built-In Variable

Field Summary

Method Summary

Methods inherited from interface net.sf.jasperreports.engine.JRCloneable

Field Detail

REPORT_COUNT

PAGE_COUNT

COLUMN_COUNT

PAGE_NUMBER

COLUMN_NUMBER

MASTER_CURRENT_PAGE

MASTER_TOTAL_PAGES

Method Detail

getName

getValueClass

getValueClassName

getIncrementerFactoryClass

getIncrementerFactoryClassName

getResetTypeValue

getIncrementTypeValue

getCalculationValue

isSystemDefined

getExpression

getInitialValueExpression

getResetGroup

getIncrementGroup