spring-projects/spring-framework

spring-expression

Active contributors: Juergen Hoeller, Sam Brannen

Purpose

spring-expression is SpEL — the Spring Expression Language. It's a small, embeddable expression language used inside annotations (@Value, @PreAuthorize), XML config, conditional bean wiring, and template engines. SpEL is not a scripting language for general use; it's a focused query/expression evaluator that integrates tightly with the Spring container.

Directory layout

spring-expression/
└── src/main/java/org/springframework/expression/
    ├── Expression.java
    ├── ExpressionParser.java
    ├── EvaluationContext.java
    ├── BeanResolver.java
    ├── PropertyAccessor.java
    ├── TypeLocator.java
    ├── common/                                     # parser exception support
    └── spel/
        ├── SpelExpression.java
        ├── SpelExpressionParser.java
        ├── ast/                                    # AST node types
        ├── support/                                # StandardEvaluationContext, …
        └── ...

Key abstractions

Type	File	Role
`ExpressionParser`	`spring-expression/src/main/java/org/springframework/expression/ExpressionParser.java`	Parses an expression string into an `Expression`
`Expression`	`spring-expression/src/main/java/org/springframework/expression/Expression.java`	A parsed, reusable expression
`EvaluationContext`	`spring-expression/src/main/java/org/springframework/expression/EvaluationContext.java`	Variables, root object, bean/property/type resolvers
`SpelExpressionParser`	`spring-expression/src/main/java/org/springframework/expression/spel/SpelExpressionParser.java`	Default parser (recursive-descent)
`StandardEvaluationContext`	`spring-expression/src/main/java/org/springframework/expression/spel/support/StandardEvaluationContext.java`	Default context with reflection-based resolvers
`SimpleEvaluationContext`	`spring-expression/src/main/java/org/springframework/expression/spel/support/SimpleEvaluationContext.java`	Restricted context for untrusted expressions
`BeanResolver`	`spring-expression/src/main/java/org/springframework/expression/BeanResolver.java`	Resolves `@bean` references in expressions

What SpEL can do

A representative cross-section of supported syntax:

Expression	Meaning
`'Hello, ' + name`	String concatenation
`T(java.lang.Math).PI`	Static field access (`T(...)` is the type expression)
`members.?[age > 18]`	Collection selection
`members.![name]`	Collection projection
`users[0].address?.city`	Indexer + safe navigation
`@userService.find(#id)`	Bean reference + variable
`someProp instanceof T(String)`	Type check
`{1, 2, 3, 4}`	List literal
`#{ 'a' : 1, 'b' : 2 }`	Map literal

How it works

graph LR
    SRC[Expression string] -->|"parse"| PARSER[SpelExpressionParser]
    PARSER -->|"AST"| EXPR[SpelExpression]
    EXPR -->|"getValue(EvaluationContext, root)"| AST[AST traversal]
    AST --> RESOLVERS[PropertyAccessors, BeanResolver, TypeLocator, MethodResolvers]
    RESOLVERS --> RESULT[Result value]

The parser produces an AST under org.springframework.expression.spel.ast. Evaluation walks the tree in interpretive mode by default, with optional compilation to bytecode for hot expressions (spel.compiler.mode=immediate).

Where SpEL plugs into the container

@Value("#{...}") — Expression-resolved values are injected at runtime.
@Cacheable(condition = "#user.active") — SpEL gates caching decisions.
@PreAuthorize("hasRole('ADMIN')") — Spring Security uses SpEL for method security.
XML config — <bean class="..."><property name="..." value="#{...}"/></bean>.
@EventListener(condition = "#event.priority > 5") — SpEL filters events.
WebFlux/MVC routing — @RequestMapping-attribute SpEL is rare but supported.

Security considerations

StandardEvaluationContext exposes full reflection — invoking arbitrary methods, accessing static fields. Never evaluate untrusted expressions with StandardEvaluationContext. Use SimpleEvaluationContext (which restricts to a property-access-only subset) when expressions might come from user input.

Integration points

A peer of spring-context. Most users encounter SpEL transparently through annotations rather than directly.
spring-context wires up SpEL by default (StandardBeanExpressionResolver).

Entry points for modification

New AST node — Adding a new operator means adding a node class under org.springframework.expression.spel.ast and updating the parser.
Custom property accessor — Implement PropertyAccessor and add it to your EvaluationContext to expose a non-bean type.
Custom function — Register via EvaluationContext.setVariable("funcName", method) so it can be called as #funcName(...).