7. Spring Expression Language (SpEL)

7.1 Introduction

The Spring Expression Language (SpEL for short) is a powerful
expression language that supports querying and manipulating an object
graph at runtime. The language syntax is similar to Unified EL but offers
additional features, most notably method invocation and basic string
templating functionality.

While there are several other Java expression languages available,
OGNL, MVEL, and JBoss EL, to name a few, the Spring Expression Language
was created to provide the Spring community with a single well supported
expression language that can be used across all the products in the Spring
portfolio. Its language features are driven by the requirements of the
projects in the Spring portfolio, including tooling requirements for code
completion support within the eclipse based SpringSource Tool Suite. That
said, SpEL is based on a technology agnostic API allowing other
expression language implementations to be integrated should the need
arise.

While SpEL serves as the foundation for expression evaluation within
the Spring portfolio, it is not directly tied to Spring and can be used
independently. In order to be self contained, many of the examples in this
chapter use SpEL as if it were an independent expression language. This
requires creating a few bootstrapping infrastructure classes such as the
parser. Most Spring users will not need to deal with this infrastructure
and will instead only author expression strings for evaluation. An example
of this typical use is the integration of SpEL into creating XML or
annotated based bean definitions as shown in the section Expression support for defining bean
definitions.

This chapter covers the features of the expression language, its
API, and its language syntax. In several places an Inventor and Inventor's
Society class are used as the target objects for expression evaluation.
These class declarations and the data used to populate them are listed at
the end of the chapter.

7.2 Feature Overview

The expression language supports the following functionality

Literal expressions

Boolean and relational operators

Regular expressions

Class expressions

Accessing properties, arrays, lists, maps

Method invocation

Relational operators

Assignment

Calling constructors

Bean references

Array construction

Inline lists

Ternary operator

Variables

User defined functions

Collection projection

Collection selection

Templated expressions

7.3 Expression Evaluation using Spring's Expression Interface

This section introduces the simple use of SpEL interfaces and its
expression language. The complete language reference can be found in the
section Language
Reference.

The following code introduces the SpEL API to evaluate the literal
string expression 'Hello World'.

The SpEL classes and interfaces you are most likely to use are
located in the packages org.springframework.expression
and its sub packages and spel.support.

The interface ExpressionParser is
responsible for parsing an expression string. In this example the
expression string is a string literal denoted by the surrounding single
quotes. The interface Expression is
responsible for evaluating the previously defined expression string. There
are two exceptions that can be thrown,
ParseException and
EvaluationException when calling
'parser.parseExpression' and
'exp.getValue' respectively.

SpEL supports a wide range of features, such as calling methods,
accessing properties, and calling constructors.

As an example of method invocation, we call the 'concat' method on
the string literal.

Note the use of the generic method public <T> T
getValue(Class<T> desiredResultType). Using this method
removes the need to cast the value of the expression to the desired result
type. An EvaluationException will be thrown if the
value cannot be cast to the type T or converted using
the registered type converter.

The more common usage of SpEL is to provide an expression string that
is evaluated against a specific object instance (called the root object).
There are two options here and which to choose depends on whether the object
against which the expression is being evaluated will be changing with each
call to evaluate the expression. In the following example
we retrieve the name property from an instance of the
Inventor class.

In the last
line, the value of the string variable 'name' will be set to "Nikola
Tesla". The class StandardEvaluationContext is where you can specify which
object the "name" property will be evaluated against. This is the mechanism
to use if the root object is unlikely to change, it can simply be set once
in the evaluation context. If the root object is likely to change
repeatedly, it can be supplied on each call to getValue,
as this next example shows:

In this case the inventor tesla has been
supplied directly to getValue and the expression
evaluation infrastructure creates and manages a default evaluation context
internally - it did not require one to be supplied.

The StandardEvaluationContext is relatively expensive to construct and
during repeated usage it builds up cached state that enables subsequent
expression evaluations to be performed more quickly. For this reason it is
better to cache and reuse them where possible, rather than construct a new
one for each expression evaluation.

In some cases it can be desirable to use a configured evaluation context and
yet still supply a different root object on each call to getValue.
getValue allows both to be specified on the same call.
In these situations the root object passed on the call is considered to override
any (which maybe null) specified on the evaluation context.

Note

In standalone usage of SpEL there is a need to create the parser,
parse expressions and perhaps provide evaluation contexts and a root
context object. However, more common usage
is to provide only the SpEL expression string as part of a
configuration file, for example for Spring bean or Spring Web Flow
definitions. In this case, the parser, evaluation context, root object
and any predefined variables are all set up implicitly, requiring
the user to specify nothing other than the expressions.

As a final introductory example, the use of a boolean operator is
shown using the Inventor object in the previous example.

7.3.1 The EvaluationContext interface

The interface EvaluationContext is
used when evaluating an expression to resolve properties, methods,
fields, and to help perform type conversion. The out-of-the-box
implementation, StandardEvaluationContext, uses
reflection to manipulate the object, caching
java.lang.reflect's Method,
Field, and Constructor
instances for increased performance.

The StandardEvaluationContext is where you
may specify the root object to evaluate against via the method
setRootObject() or passing the root object into
the constructor. You can also specify variables and functions that
will be used in the expression using the methods
setVariable() and
registerFunction(). The use of variables and
functions are described in the language reference sections Variables and Functions. The
StandardEvaluationContext is also where you can
register custom ConstructorResolvers,
MethodResolvers, and
PropertyAccessors to extend how SpEL evaluates
expressions. Please refer to the JavaDoc of these classes for more
details.

Type Conversion

By default SpEL uses the conversion service available in Spring
core
(org.springframework.core.convert.ConversionService).
This conversion service comes with many converters built in for common
conversions but is also fully extensible so custom conversions between
types can be added. Additionally it has the key capability that it is
generics aware. This means that when working with generic types in
expressions, SpEL will attempt conversions to maintain type
correctness for any objects it encounters.

What does this mean in practice? Suppose assignment, using
setValue(), is being used to set a
List property. The type of the property is actually
List<Boolean>. SpEL will recognize that the
elements of the list need to be converted to
Boolean before being placed in it. A simple
example:

class Simple {
public List<Boolean> booleanList = new ArrayList<Boolean>();
}
Simple simple = new Simple();
simple.booleanList.add(true);
StandardEvaluationContext simpleContext = new StandardEvaluationContext(simple);
// false is passed in here as a string. SpEL and the conversion service will // correctly recognize that it needs to be a Boolean and convert it
parser.parseExpression("booleanList[0]").setValue(simpleContext, "false");
// b will be false
Boolean b = simple.booleanList.get(0);

7.4 Expression support for defining bean definitions

SpEL expressions can be used with XML or annotation based
configuration metadata for defining BeanDefinitions. In both cases the
syntax to define the expression is of the form #{ <expression
string> }.

7.4.1 XML based configuration

A property or constructor-arg value can be set using expressions
as shown below

7.5 Language Reference

7.5.1 Literal expressions

The types of literal expressions supported are strings, dates,
numeric values (int, real, and hex), boolean and null. Strings are
delimited by single quotes. To put a single quote itself in a string use
two single quote characters. The following listing shows simple usage of
literals. Typically they would not be used in isolation like this, but
as part of a more complex expression, for example using a literal on one
side of a logical comparison operator.

Numbers support the use of the negative sign, exponential
notation, and decimal points. By default real numbers are parsed using
Double.parseDouble().

7.5.2 Properties, Arrays, Lists, Maps, Indexers

Navigating with property references is easy, just use a period to
indicate a nested property value. The instances of Inventor class, pupin
and tesla, were populated with data listed in the section Classes used in the
examples. To navigate "down" and get Tesla's year of birth and
Pupin's city of birth the following expressions are used.

{} by itself means an empty list. For performance reasons, if the
list is itself entirely composed of fixed literals then a constant list is created
to represent the expression, rather than building a new list on each evaluation.

7.5.4 Array construction

Arrays can be built using the familiar Java syntax, optionally
supplying an initializer to have the array populated at construction time.

Each symbolic operator can also be specified as a purely alphabetic equivalent. This avoids
problems where the symbols used have special meaning for the document type in which
the expression is embedded (eg. an XML document). The textual equivalents are shown
here: lt ('<'), gt ('>'), le ('<='), ge ('>='),
eq ('=='), ne ('!='), div ('/'), mod ('%'), not ('!').
These are case insensitive.

Logical operators

The logical operators that are supported are and, or, and not.
Their use is demonstrated below.

Mathematical operators

The addition operator can be used on numbers, strings and dates.
Subtraction can be used on numbers and dates. Multiplication and
division can be used only on numbers. Other mathematical operators
supported are modulus (%) and exponential power (^). Standard operator
precedence is enforced. These operators are demonstrated below.

7.5.8 Types

The special 'T' operator can be used to specify an instance of
java.lang.Class (the 'type'). Static methods are invoked using this
operator as well. The StandardEvaluationContext
uses a TypeLocator to find types and the
StandardTypeLocator (which can be replaced) is
built with an understanding of the java.lang package. This means T()
references to types within java.lang do not need to be fully qualified,
but all other type references must be.

The #this and #root variables

The variable #this is always defined and refers to the current
evaluation object (against which unqualified references are resolved).
The variable #root is always defined and refers to the root
context object. Although #this may vary as components of an expression
are evaluated, #root always refers to the root.

7.5.15 Safe Navigation operator

The Safe Navigation operator is used to avoid a
NullPointerException and comes from the Groovy
language. Typically when you have a reference to an object you might
need to verify that it is not null before accessing methods or
properties of the object. To avoid this, the safe navigation operator
will simply return null instead of throwing an exception.

The Elvis operator can be used to apply default values in
expressions, e.g. in an @Value expression:

@Value("#{systemProperties['pop3.port'] ?: 25}")

This will inject a system property pop3.port if it
is defined or 25 if not.

7.5.16 Collection Selection

Selection is a powerful expression language feature that allows you
to transform some source collection into another by selecting from its
entries.

Selection uses the syntax
?[selectionExpression]. This will filter the
collection and return a new collection containing a subset of the
original elements. For example, selection would allow us to easily get a
list of Serbian inventors:

Selection is possible upon both lists and maps. In the former case
the selection criteria is evaluated against each individual list element
whilst against a map the selection criteria is evaluated against each
map entry (objects of the Java type Map.Entry). Map
entries have their key and value accessible as properties for use in the
selection.

This expression will return a new map consisting of those elements
of the original map where the entry value is less than 27.

Map newMap = parser.parseExpression("map.?[value<27]").getValue();

In addition to returning all the selected elements, it is possible
to retrieve just the first or the last value. To obtain the first entry
matching the selection the syntax is ^[...] whilst to
obtain the last matching selection the syntax is
$[...].

7.5.17 Collection Projection

Projection allows a collection to drive the evaluation of a
sub-expression and the result is a new collection. The syntax for
projection is ![projectionExpression]. Most easily
understood by example, suppose we have a list of inventors but want the
list of cities where they were born. Effectively we want to evaluate
'placeOfBirth.city' for every entry in the inventor list. Using
projection:

A map can also be used to drive projection and in this case the
projection expression is evaluated against each entry in the map
(represented as a Java Map.Entry). The result of a
projection across a map is a list consisting of the evaluation of the
projection expression against each map entry.

7.5.18 Expression templating

Expression templates allow a mixing of literal text with one or
more evaluation blocks. Each evaluation block is delimited with prefix
and suffix characters that you can define, a common choice is to use
#{ } as the delimiters. For example,

String randomPhrase =
parser.parseExpression("random number is #{T(java.lang.Math).random()}",
new TemplateParserContext()).getValue(String.class);
// evaluates to "random number is 0.7038186818312008"

The string is evaluated by concatenating the literal text 'random
number is ' with the result of evaluating the expression inside the #{ }
delimiter, in this case the result of calling that random() method. The
second argument to the method parseExpression() is of
the type ParserContext. The
ParserContext interface is used to
influence how the expression is parsed in order to support the
expression templating functionality. The definition of
TemplateParserContext is shown below.