net.sf.jasperreports.engine.JRVariable Maven / Gradle / Ivy
/*
* JasperReports - Free Java Reporting Library.
* Copyright (C) 2001 - 2023 Cloud Software Group, Inc. All rights reserved.
* http://www.jaspersoft.com
*
* Unless you have purchased a commercial license agreement from Jaspersoft,
* the following license terms apply:
*
* This program is part of JasperReports.
*
* JasperReports is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* JasperReports is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with JasperReports. If not, see 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 expressionReport - The variable is initialized only once, at the beginning of the
* report-filling process, with the value returned by the variable's initial value
* expressionPage - The variable is reinitialized at the beginning of each new page.Column - The variable is reinitialized at the beginning of each new columnGroup - 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 sourceReport - 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>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 {@link net.sf.jasperreports.engine.fill.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
* {@link net.sf.jasperreports.engine.fill.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 ([email protected])
*/
public interface JRVariable extends JRCloneable
{
/**
* 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.
*/
public static final String REPORT_COUNT = "REPORT_COUNT";
/**
* Built-in variable containing the number of records that were processed when generating the current page.
*/
public static final String PAGE_COUNT = "PAGE_COUNT";
/**
* This variable contains the number of records that were processed when generating the current column.
*/
public static final String COLUMN_COUNT = "COLUMN_COUNT";
/**
* 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.
*/
public static final String PAGE_NUMBER = "PAGE_NUMBER";
/**
* Built-in variable containing the current column number.
*/
public static final String COLUMN_NUMBER = "COLUMN_NUMBER";
/**
* A variable that provides the current master report page number.
*
*
* It can only be used in text elements with {@link EvaluationTimeEnum#MASTER Master} evaluation time,
* it evaluates to null before the moment in which master elements are resolved.
*
*/
public static final String MASTER_CURRENT_PAGE = "MASTER_CURRENT_PAGE";
/**
* A variable that provides the number of master report pages.
*
*
* It can only be used in text elements with {@link EvaluationTimeEnum#MASTER Master} evaluation time,
* it evaluates to null before the moment in which master elements are resolved.
*
*/
public static final String MASTER_TOTAL_PAGES = "MASTER_TOTAL_PAGES";
/**
* Returns the name of the variable. Since all variables are stored in a map, the variable names are the keys in the map.
* @return a string containing the variable name
*/
public String getName();
/**
* Gets the variable optional description.
*/
public String getDescription();
/**
* Sets the variable description.
*/
public void setDescription(String description);
/**
* Returns the class of the variable value. Any class is allowed as long as it is in the classpath at compile and run time.
* @return a Class instance representing the variable value class
*/
public Class getValueClass();
/**
* Returns the string name of the variable value class.
*/
public String getValueClassName();
/**
* Returns the class of the incrementer factory used for choosing the right incrementer for the variable value.
* @return the Class instance of the incrementer factory
* @see net.sf.jasperreports.engine.fill.JRIncrementer
* @see net.sf.jasperreports.engine.fill.JRIncrementerFactory
*/
public Class getIncrementerFactoryClass();
/**
* Returns the string name of the variable value class.
*/
public String getIncrementerFactoryClassName();
/**
* Gets the variable reset type.
* @return a value representing one of the reset type constants in {@link ResetTypeEnum}
*/
public ResetTypeEnum getResetTypeValue();
/**
* Gets the variable increment type.
* @return a value representing one of the reset type constants in {@link IncrementTypeEnum}
*/
public IncrementTypeEnum getIncrementTypeValue();
/**
* Gets the variable calculation type.
* @return a value representing one of the calculation type constants in {@link CalculationEnum}
*/
public CalculationEnum getCalculationValue();
/**
* Returns true if the variable calculation type is system defined.
* @see CalculationEnum#SYSTEM
*/
public boolean isSystemDefined();
/**
* Returns the main expression for this variable. The expression must be numeric for certain calculation types.
* @return a {@link JRExpression} instance containing the expression.
*/
public JRExpression getExpression();
/**
* Returns the initial value expression for this variable. The expression must be numeric for certain calculation types.
* @return a {@link JRExpression} instance containing the initial expression.
*/
public JRExpression getInitialValueExpression();
/**
* Returns the group whose break triggers the variable reset. Only used when {@link JRVariable#getResetTypeValue()} returns
* {@link ResetTypeEnum#GROUP}.
*/
public JRGroup getResetGroup();
/**
* Returns the group whose break triggers the variable increment. Only used when {@link JRVariable#getIncrementTypeValue()} returns
* {@link IncrementTypeEnum#GROUP}.
*/
public JRGroup getIncrementGroup();
}