net.sf.jasperreports.engine

Interface JRExpression

All Superinterfaces:

Cloneable, JRCloneable

All Known Implementing Classes:

JRBaseExpression, JRDesignExpression

public interface JRExpression
extends JRCloneable

Provides the JasperReports expressions functionality.

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, JavaScript or BeanShell script, 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 (JasperReport object) information that it will use at report-filling time to build an instance of the JRCalculator class.

Author:

Teodor Danciu (teodord@users.sourceforge.net)

See Also:

JRCalculator

Field Summary

Fields

Modifier and Type	Field and Description
static byte	EVALUATION_DEFAULT
static byte	EVALUATION_ESTIMATED
static byte	EVALUATION_OLD
static Integer	NOT_USED_ID Dummy ID that is assigned to expression that are not used (and not collected).

Method Summary

Modifier and Type	Method and Description
JRExpressionChunk[]	getChunks()
int	getId()
String	getText()
Class<?>	getValueClass() Deprecated. To be removed.
String	getValueClassName() Deprecated. To be removed.

Methods inherited from interface net.sf.jasperreports.engine.JRCloneable

clone

Field Detail

EVALUATION_OLD

static final byte EVALUATION_OLD

See Also:

Constant Field Values

EVALUATION_ESTIMATED

static final byte EVALUATION_ESTIMATED

See Also:

Constant Field Values

EVALUATION_DEFAULT

static final byte EVALUATION_DEFAULT

See Also:

Constant Field Values

NOT_USED_ID

static final Integer NOT_USED_ID

Dummy ID that is assigned to expression that are not used (and not collected).

Method Detail

getValueClass

Class<?> getValueClass()

Deprecated. To be removed.

Returns the expression return value class.

getValueClassName

String getValueClassName()

Deprecated. To be removed.

Returns the expression return value class.

getId

int getId()

getChunks

JRExpressionChunk[] getChunks()

getText

String getText()