net.sf.jasperreports.engine.JRExpression Maven / Gradle / Ivy
Show all versions of jasperreports Show documentation
/*
* JasperReports - Free Java Reporting Library.
* Copyright (C) 2001 - 2022 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 Expressions in JasperReports
* Expressions are a powerful feature of JasperReports. They can be used to declare report
* variables that perform various calculations, group data on the report, specify report text
* field content, or further customize the appearance of report objects.
*
* By default, the Java language is used for writing report expressions, but other scripting
* languages can be used if a corresponding report compiler able to produce the information
* needed for expression evaluation at runtime is available. Currently, JasperReports ships
* with report compilers that can compile report templates using the Groovy scripting
* language or JavaScript, inside report expressions.
*
* For simplicity's sake, in the next paragraphs we'll assume that expressions
* have been written using the Java language.
*
* Since all JasperReports expressions are (or are assumed to be) real Java expressions, then
* any valid java class can be used inside them, as long as they are referred to by using the complete class
* name (including the package), or are adding the proper imports to your report template. We also have to
* make sure that the classes we are using in the report expressions are available in the classpath when
* the report is compiled and filled with data.
*
* In a JRXML report template, there are several elements that define expressions,
* including <variableExpression>, <initialValueExpression>,
* <groupExpression>, <printWhenExpression>,
* <imageExpression>, <textFieldExpression>...
*
* Expression Syntax
* Report expressions would be useless if there were no way to reference in them the report
* parameters, report fields, or declared report variables. For this reason, a special
* JasperReports syntax on top of the scripting language allows introducing such
* references in the report expressions created in the JRXML report template.
*
* Report parameter references are introduced using the $P{} character sequence, as in the
* following example:
*
* <textFieldExpression>
* $P{ReportTitle}
* </textFieldExpression>
* This example assumes that the report design declares a report parameter named
* ReportTitle, whose class is java.lang.String. The text field will display the value
* of this parameter when the report is filled.
*
* To use a report field reference in an expression, one must put the name of the field
* between the $F{ and } character sequences. For example, to display the concatenated
* values of two data source fields in a text field, define an expression like this one:
*
* <textFieldExpression>
* $F{FirstName} + " " + $F{LastName}
* </textFieldExpression>
* The expression can be even more complex, as in the following example:
*
* <textFieldExpression>
* $F{FirstName} + " " + $F{LastName} + " was hired on " +
* (new SimpleDateFormat("MM/dd/yyyy")).format($F{HireDate}) + "."
* </textFieldExpression>
* To reference a report variable in an expression, you must put the name of the variable
* between $V{ and }, as in this example:
*
* <textFieldExpression>
* "Total quantity : " + $V{QuantitySum} + " kg."
* </textFieldExpression>
* As you can see, the parameter, field, and variable references introduced by the special
* JasperReports syntax are in fact real Java objects. Knowing their class from the
* parameter, field or variable declaration made in the report template, you can even call
* methods on those object references in your expressions.
*
* Here's one way to extract and display the first letter from a java.lang.String report
* field:
*
* <textFieldExpression>
* $F{FirstName}.substring(0, 1)
* </textFieldExpression>
* When support for internationalization was added to JasperReports, a new token was
* introduced in the JasperReports syntax to allow access to the locale-specific resources
* inside the report's associated resource bundle. The $R{} character syntax extracts the
* locale-specific resource from the resource bundle based on the key that must be put
* between the brackets:
*
* <textFieldExpression>
* $R{report.title}
* </textFieldExpression>
* The preceding text field displays the title of the report by extracting the String value
* from the resource bundle associated with the report template based on the runtime supplied
* locale and the report.title key.
*
* In some rare cases (for example, debugging), there is the need to escape an expression
* token like the ones described previously. The escape syntax for the tokens requires
* duplicating the $ character. Escaping a $P{paramName} token is achieved by writing
* $$P{paramName} in the expression. When escaped, an expression token is preserved as-is
* in the resulting expression, and no attempt to parse the token is made.
*
* Conditional Expressions
* As the Java language documentation states, an expression is a series of variables,
* operators, and method calls (constructed according to the syntax of the language) that
* evaluate to a single value.
*
* So even if we rely on the Java language for writing report expressions, we cannot use
* Java statements like if else, for, or while.
*
* However, quite often an expression must return a value that is calculated based on a
* condition or even multiple conditions. To accomplish this, use the conditional operator
* ?:. One can even nest this operator inside a Java expression to obtain the desired output
* based on multiple conditions.
*
* The following text field displays No data if the value for the quantity field is null:
*
* <textFieldExpression>
* $F{quantity} == null ? "No data" : String.valueOf($F{quantity})
* </textFieldExpression>
* Expressions Calculator
* The expressions calculator is the entity inside JasperReports that evaluates
* expressions and increments variables or datasets at report-filling time. When a report
* template is compiled, the report compiler produces and stores in the compiled report
* template ({@link net.sf.jasperreports.engine.JasperReport} object) information that it will use at report-filling time to
* build an instance of the {@link net.sf.jasperreports.engine.fill.JRCalculator} class.
*
* @see net.sf.jasperreports.engine.fill.JRCalculator
* @author Teodor Danciu ([email protected])
*/
public interface JRExpression extends JRCloneable
{
/**
*
*/
public static final byte EVALUATION_OLD = 1;
public static final byte EVALUATION_ESTIMATED = 2;
public static final byte EVALUATION_DEFAULT = 3;
/**
* Dummy ID that is assigned to expression that are not used (and not collected).
*/
public static final Integer NOT_USED_ID = -1;
/**
* Returns the expression return value class.
* @deprecated To be removed.
*/
public Class getValueClass();
/**
* Returns the expression return value class.
* @deprecated To be removed.
*/
public String getValueClassName();
/**
*
*/
public int getId();
/**
*
*/
public JRExpressionChunk[] getChunks();
/**
*
*/
public String getText();
/**
*
*/
public ExpressionTypeEnum getType();
}