• Home
• net.sf.jasperreports
• jasperreports
• 6.16.0
• source code
• JRVariable.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

net.sf.jasperreports.engine.JRVariable Maven / Gradle / Ivy

/*
 * 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();
		
}