/* * JasperReports - Free Java Reporting Library. * Copyright (C) 2001 - 2013 Jaspersoft Corporation. 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.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: * *

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: *

*

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 {@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 (teodord@users.sourceforge.net) * @version $Id: JRVariable.java 7045 2014-04-24 14:20:46Z shertage $ */ 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"; /** * 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(); /** * 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 ResetTypeEnum#GROUP}. */ public JRGroup getIncrementGroup(); }