Expressions

Many settings in a report are defined by formulas, such as conditions that can hide an element, special calculations, or text processing that requires knowledge of a scripting language.

Formulas can be written in at least three languages, two of which (JavaScript and Groovy) can be used without knowledge of programming methods.

All formulas in JasperReports are defined through expressions. The default expression language is Java, but if you're not a programmer, we recommend JavaScript or Groovy, because those languages hide a lot of the Java complexity. The language is a property of the document. To set it, select the document root node in the Outline view and choose your language in the Language property in the Properties view.

An expression is a formula that operates on some values and returns a result, like a formula in a spreadsheet cell. A cell can have a simple value or a complex formula that refers to other values. In a spreadsheet you refer to values contained in other cells; in JasperReports you use the report fields, parameters, and variables. Whatever is in your expression, when it's computed, it returns a value (which can be null).

 

This chapter contains the following sections:

•

Expression Types

•

Expression Operators and Object Methods

•

Using an If-Else Construct in an Expression

•

Using Unicode Characters in Expressions

•

Using Java as a Language for Expressions

•

Using Groovy as a Language for Expressions

•

Using JavaScript as a Language for Expressions

Expression Types

An expression's type is determined by the context in which the expression is used. For example, if your expression is used to evaluate a condition, the expression should be Boolean (true or false); if you're creating an expression to display in a text field, it's probably a String or a number (Integer or Double). Using the right type is crucial; JasperReports requires precision when choosing an expression type.

Some of the most important Java types are:

java.lang.Boolean	Defines an Object that represents a Boolean value such as true and false
java.lang.Byte	Defines an Object that represents a byte
java.lang.Short	Defines an Object that represents an short integer
java.lang.Integer	Defines an Object that represents integer numbers
java.lang.Long	Defines an Object that represents long integer numbers
java.lang.Float	Defines an Object that represents floating point numbers
java.lang.Double	Defines an Object that represents real numbers
java.lang.String	Defines an Object that represents a text
java.util.Date	Defines an Object that represents a date or a timestamp
java.lang.Object	A generic java Object

If an expression is used to determine the value of a condition that determines, for instance, whether an element should be printed, the return type is java.lang.Boolean. To create it, you need an expression that returns an instance of a Boolean object. Similarly, if an expression shows a number in a text field, the return type is java.lang.Integer or java.lang.Double.

Neither JavaScript nor Groovy is particularly formal about types, since they are not typed languages; the language itself treats a value in the best way by trying to guess the value type or by performing implicit casts (conversion of the type).

Expression Operators and Object Methods

Operators in Java, Groovy and JavaScript are similar because these languages share the same basic syntax. Operators can be applied to a single operand (unary operators) or on two operands (binary operators). The following table shows a number of operators, but it is not a complete list. For example, there is a unary operator to add 1 to a variable (++), but it is easier to use x + 1.

Expression operators

Operator	Description	Example
+	Sum (it can be used to sum two numbers or to concatenate two strings)	A + B
-	Subtraction	A - B
/	Division	A / B
%	Rest, it returns the rest of an integer division	A % B
||	Boolean operator OR	A || B
&&	Boolean operator AND	A && B
==	Equals	A == B
!=	Not equals	A != B
!	Boolean operator NOT	!A

	Regarding the Equals operator: in Java, the == operator can only be used to compare two primitive values. With objects, you need to use the special method “equals”; for example, you cannot write an expression like "test" == "test", you need to write "test".equals("test").
	Regarding the Equals operator: in Java, the != operator can only be used to compare two primitive values.

Within an expression, you can use the syntax summarized in Syntax for referring to report objects to refer to the parameters, variables, and fields defined in the report.

Syntax for referring to report objects

Syntax	Description
$F{name_field}	Specifies the name_field field ("F" means field).
$V{name_variable}	Specifies the name_variable variable.
$P{name_parameter}	Specifies the name_parameter parameter.
$P!{name_parameter}	Special syntax used in the report SQL query to indicate that the parameter does not have to be dealt as a value to transfer to a prepared statement, but that it represents a little piece of the query.
$R{resource_key}	Special syntax for localization of strings.
$X{functionName, col_name, param1,[param2]}	Syntax for complex queries, such as comparing a column value to a parameter value. Based on the function in the first argument, JasperReports constructs a SQL clause. The following functions are available: • Functions expecting three arguments for $X{} – EQUAL, NOTEQUAL, LESS, LESS] (less than or equal to), GREATER, [GREATER (greater than or equal to), IN, NOTIN. For example: $X{EQUAL, order_date, date_parameter} • Functions expecting four arguments for $X{} – BETWEEN (excludes both endpoints) BETWEEN] (includes right endpoint) [BETWEEN (includes left endpoint) [BETWEEN] (includes both endpoints) For example: $X{BETWEEN, order_date, start_date_param, end_date_param}

In summary, fields, variables and parameters represent objects; specify their type when you declare them within a report.

Although expressions can be complicated, usually it is a simple operation that returns a value. There is a simple if-else expression that is very useful in many situations. An expression is just an arbitrary operation that any stage must represent a value. In Java, these operators can be applied only to primitive values, except for the sum operator (+). The sum operator can be applied to a String expression with the special meaning of concatenate. For example:

$F{city} + “, ” + $F{state}

results in a string like:

San Francisco, California

Some examples:

Expression	Result
“test”.length()	4
“test”.substring(0, 3)	“tes”
“test”.startsWith(“A”)	false
“test”.substring(1, 2).startsWith(“e”)	true

The methods of each object are usually explained in the JasperReports Library Javadocs, which are available at http://jasperreports.sourceforge.net/api/.

You can use parentheses to isolate expressions and make the overall expression more readable.

Using an If-Else Construct in an Expression

A way to create an if-else-like expression is by using the special question mark operator. For example:

(($F{name}.length() > 50) ? $F{name}.substring(0,50) : $F{name})

The syntax is (<condition>) ? <value on true> : <value on false>. It is extremely useful, and can be recursive, meaning that the value on true and false can be represented by another expression which can be a new condition:

(($F{name}.length() > 50) ?

(($F{name}.startsWith(“A”)) ? “AAAA” : “BBB”)

:

$F{name})

This expression returns the String AAAA when the value of the field name is longer than 50 characters and starts with A, returns BBB if it is longer than 50 characters but does not start with A, and, finally, returns the original field value if neither of these conditions is true.

Despite the possible complexity of an expression, it can be insufficient to define a needed value. For example, if you want to print a number in Roman numerals or return the name of the weekday of a date, it is possible to transfer the elaborations to an external Java class method, which must be declared as static, as shown in the following example:

MyFormatter.toRomanNumber( $F{MyInteger}.intValue() )

The function operand toRomanNumber is a static method of the MyFormatter class, which takes an int as argument (the conversion from Integer to int is done by means of the intValue() method; it is required only when using Java as language) and gives back the Roman version of a number in a lace.

This technique can be used for many purposes; for example, to read the text from a CLOB field or to add a value into a HashMap (a Java object that represents a set of key/value pairs).