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

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jasperreports Show documentation
JasperReports Library
There is a newer version: 7.0.0
/*
 * 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.EvaluationTimeEnum;


/**
 * Provides support for expressions evaluation.
 * 
 * Normally, all report expressions are evaluated immediately, using the current values of
 * all the parameters, fields, and variables at that particular moment. It is like making a
 * photo of all data for every iteration in the data source during the report-filling process.
 * This means that at any particular time, you won't have access to values that are going to
 * be calculated later in the report-filling process. This makes perfect sense, since all the
 * variables are calculated step by step and reach their final value only when the iteration
 * arrives at the end of the data source range they cover.
 * 

 * For example, a report variable that calculates the sum of a field for each page will not
 * contain the expected sum until the end of the page is reached. That's because the sum is
 * calculated step by step as the data source records are iterated through. At any particular
 * time, the sum will only be partial, since not all the records of the specified range will
 * have been processed.
 * 

 * As a consequence, you cannot display a sum on the page header, since this value will be
 * known only when the end of the page is reached. At the beginning of the page, when
 * generating the page header, the sum variable would contain zero, or its initial value. To
 * address this problem, JasperReports provides a feature (the evaluationTime attribute)
 * that lets you decide the exact moment you want the text field expression to be evaluated,
 * avoiding the default behavior in which the expression is evaluated immediately when the
 * current report section is generated.
 * 

 * The evaluationTime attribute can have one of the following values (see {@link #getEvaluationTimeValue()}):
 * 

 * Now - The expression is evaluated when the current band is filled.
 * Report - The expression is evaluated when the end of the report is reached.
 * Page - The expression is evaluated when the end of the current page is reached
 * Column - The expression is evaluated when the end of the current column is reached
 * Group - The expression is evaluated when the group specified by the evaluationGroup 
 * attribute (see {@link #getEvaluationGroup()}) changes
 * Auto - Each variable participating in the expression is evaluated at a time corresponding 
 * to its reset type. Fields are evaluated Now. This evaluation type should be used for expressions 
 * that combine values evaluated at different times, like the percentage out of a total
 * 
 * The default value for this attribute is Now. In the example
 * presented previously, you could easily specify evaluationTime="Page" for the text
 * field placed in the page header section, so that it displays the value of the sum variable
 * only when reaching the end of the current page.
 * 
 * @author Teodor Danciu ([email protected])
 */
public interface JREvaluation
{

	/**
	 * Gets the evaluation time for this text field.
	 * @return one of the evaluation time constants in {@link JRExpression}
	 */
	public EvaluationTimeEnum getEvaluationTimeValue();

	/**
	 * Gets the evaluation group for this text field. Used only when evaluation time is group.
	 * @see EvaluationTimeEnum#GROUP
	 */
	public JRGroup getEvaluationGroup();

}