Mastering Spring Expression Language (SpEL): Syntax, Features, and Usage

SpEL

Spring Expression Language (SpEL) is the expression language of the Spring Framework, abbreviated as SpEL.

Supported Expressions

Basic expressions : literal expressions, relational, logical and arithmetic operations, string concatenation and substring, ternary and Elvis operators, regular‑expression support, and parenthesis‑based precedence.

Class‑related expressions : class‑type expressions, class instantiation, instanceof, variable definition and reference, assignment, custom functions, object property access, safe‑navigation expressions, method invocation, and Bean references.

Collection‑related expressions : inline List, inline arrays, collection and map access, list, map and array modification, collection projection and selection; multi‑dimensional inline arrays and inline map definitions are not supported.

Other expressions : template expressions.

Note : keywords in SpEL expressions are case‑insensitive.

SpEL Usage Flow

Create parser : the ExpressionParser interface represents a parser; the default implementation is SpelExpressionParser.

Parse expression : use ExpressionParser.parseExpression to obtain an Expression object.

Construct evaluation context : prepare variables, root object, etc., via an EvaluationContext implementation.

Evaluate : call Expression.getValue with the context to obtain the result.

// create parser
ExpressionParser parser = new SpelExpressionParser();
// define expression
Expression expression = parser.parseExpression("('Hello' + ' World').concat(#end)");
// build context
EvaluationContext context = new StandardEvaluationContext();
context.setVariable("end", "!");
// evaluate
System.out.println(expression.getValue(context));

ExpressionParser Interface

The default implementation SpelExpressionParser provides two parseExpression methods that convert a string into an Expression object.

Expression parseExpression(String expressionString) throws ParseException;
Expression parseExpression(String expressionString, ParserContext context) throws ParseException;

ParserContext

defines whether a string is a template and the characters that delimit the expression.

boolean isTemplate();
String getExpressionPrefix();
String getExpressionSuffix();

Example of a custom ParserContext that treats #{…} as a template:

ExpressionParser parser = new SpelExpressionParser();
ParserContext parserContext = new ParserContext() {
    @Override
    public boolean isTemplate() { return true; }
    @Override
    public String getExpressionPrefix() { return "#{"; }
    @Override
    public String getExpressionSuffix() { return "}"; }
};
String template = "hello  #{ #Hello}";
EvaluationContext context = new StandardEvaluationContext();
context.setVariable("Hello", "HELLO");
Expression expression = parser.parseExpression(template, parserContext);
System.out.println(expression.getValue(context));

EvaluationContext Interface

Represents the evaluation environment; the default implementation is StandardEvaluationContext. Use setRootObject to set the root object, setVariable to register custom variables, and registerFunction to add custom functions.

Expression Interface

Represents an expression object; the default implementation is SpelExpression. It provides getValue to retrieve the expression result and setValue to modify object properties.

SpEL Syntax

Literal expressions : strings (must be quoted), numeric types (int, long, float, double), boolean, and null.

ExpressionParser parser = new SpelExpressionParser();
System.out.println(parser.parseExpression("'Hello World!'").getValue(String.class));
System.out.println(parser.parseExpression("1").getValue(Integer.class));

Arithmetic expressions : +, -, *, /, %, ^.

ExpressionParser parser = new SpelExpressionParser();
System.out.println(parser.parseExpression("1 + 1").getValue(Integer.class));
System.out.println(parser.parseExpression("1 - 1").getValue(Integer.class));
System.out.println(parser.parseExpression("1 * 2").getValue(Integer.class));
System.out.println(parser.parseExpression("6 / 2").getValue(Integer.class));

Relational expressions : ==, !=, >, >=, <, <=, between; also EQ, NE, GT, GE, LT, LE (case‑insensitive).

ExpressionParser parser = new SpelExpressionParser();
System.out.println(parser.parseExpression("1 == 1").getValue(Boolean.class));
System.out.println(parser.parseExpression("1 != 1").getValue(Boolean.class));
System.out.println(parser.parseExpression("1 eq 1").getValue(Boolean.class));
System.out.println(parser.parseExpression("6 NE 2").getValue(Boolean.class));

Logical expressions : and (&&), or (||), not (! or NOT).

ExpressionParser parser = new SpelExpressionParser();
System.out.println(parser.parseExpression("1 == 1 and 1 == 2").getValue(Boolean.class));
System.out.println(parser.parseExpression("1 == 1 or 1 == 2").getValue(Boolean.class));
System.out.println(parser.parseExpression("1 == 1 && 1 == 2").getValue(Boolean.class));
System.out.println(parser.parseExpression("1 == 1 AND 1 == 2").getValue(Boolean.class));

String concatenation and substring : use + for concatenation; 'String'[index] to extract a single character.

ExpressionParser parser = new SpelExpressionParser();
System.out.println(parser.parseExpression("'Hello' + 'World!'").getValue());
System.out.println(parser.parseExpression("'Hello'[0]").getValue());

Ternary operator : condition ? expr1 : expr2.

ExpressionParser parser = new SpelExpressionParser();
System.out.println(parser.parseExpression("1 > 2 ? true : false").getValue(Boolean.class));

Elvis operator : expr1 ?: expr2 returns expr1 if it is non‑null, otherwise expr2.

ExpressionParser parser = new SpelExpressionParser();
System.out.println(parser.parseExpression("null?:true").getValue(Boolean.class));
System.out.println(parser.parseExpression("true?:true").getValue(Boolean.class));

Variable definition and reference : define variables via EvaluationContext.setVariable(name, value) and reference them with #variableName. Root object is accessed with #root, current context object with #this.

ExpressionParser parser = new SpelExpressionParser();
EvaluationContext context = new StandardEvaluationContext();
context.setVariable("name", "John");
String name = parser.parseExpression("#name").getValue(context, String.class);
System.out.println(name);

Object property access and safe navigation : use dot notation a.property (case‑insensitive) and safe‑navigation operator ?. to avoid NullPointerException.

// Assuming person may be null
ExpressionParser parser = new SpelExpressionParser();
EvaluationContext ctx = new StandardEvaluationContext();
ctx.setVariable("person", null);
Object result = parser.parseExpression("#person?.age").getValue(ctx);
System.out.println(result); // prints null instead of throwing NPE

For more details, refer to the official Spring documentation and the Zhihu article linked at the end of the original source.