net.sf.jasperreports.engine.JRVariable Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jasperreports Show documentation
Show all versions of jasperreports Show documentation
Free Java Reporting Library
/*
* JasperReports - Free Java Reporting Library.
* Copyright (C) 2001 - 2019 TIBCO Software 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 .
*/
package net.sf.jasperreports.engine;
import net.sf.jasperreports.engine.type.CalculationEnum;
import net.sf.jasperreports.engine.type.EvaluationTimeEnum;
import net.sf.jasperreports.engine.type.IncrementTypeEnum;
import net.sf.jasperreports.engine.type.ResetTypeEnum;
/**
* 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>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();
}