Support Optional with null-safe and Elvis operators in SpEL expressions

This commit introduces null-safe support for java.util.Optional in the
following SpEL operators:

- Elvis
- Indexer
- MethodReference
- PropertyOrFieldReference
- Projection

TODOs:

- Support the Selection operator.
- Update the SpEL chapter of the reference manual.

Closes spring-projectsgh-20433

Author: sbrannen

spring-expression/src/main/java/org/springframework/expression/spel/ast/Elvis.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,6 +16,8 @@
 
 package org.springframework.expression.spel.ast;
 
+import java.util.Optional;
+
 import org.springframework.asm.Label;
 import org.springframework.asm.MethodVisitor;
 import org.springframework.expression.EvaluationException;
@@ -26,9 +28,13 @@
 import org.springframework.util.ObjectUtils;
 
 /**
- * Represents the Elvis operator <code>?:</code>. For an expression <code>a?:b</code> if <code>a</code> is neither null
- * nor an empty String, the value of the expression is <code>a</code>.
- * If <code>a</code> is null or the empty String, then the value of the expression is <code>b</code>.
+ * Represents the Elvis operator {@code ?:}.
+ *
+ * <p>For the expression "{@code A ?: B}", if {@code A} is neither {@code null},
+ * an empty {@link Optional}, nor an empty {@link String}, the value of the
+ * expression is {@code A}, or {@code A.get()} for an {@code Optional}. If
+ * {@code A} is {@code null}, an empty {@code Optional}, or an
+ * empty {@code String}, the value of the expression is {@code B}.
  *
  * @author Andy Clement
  * @author Juergen Hoeller
@@ -43,18 +49,32 @@ public Elvis(int startPos, int endPos, SpelNodeImpl... args) {
 
 
 	/**
-	 * Evaluate the condition and if neither null nor an empty String, return it.
-	 * If it is null or an empty String, return the other value.
+	 * If the left-hand operand is neither neither {@code null}, an empty
+	 * {@link Optional}, nor an empty {@link String}, return its value, or the
+	 * value contained in the {@code Optional}. If the left-hand operand is
+	 * {@code null}, an empty {@code Optional}, or an empty {@code String},
+	 * return the other value.
 	 * @param state the expression state
-	 * @throws EvaluationException if the condition does not evaluate correctly
-	 * to a boolean or there is a problem executing the chosen alternative
+	 * @throws EvaluationException if the null/empty check does not evaluate correctly
+	 * or there is a problem evaluating the alternative
 	 */
 	@Override
 	public TypedValue getValueInternal(ExpressionState state) throws EvaluationException {
-		TypedValue value = this.children[0].getValueInternal(state);
+		TypedValue leftHandTypedValue = this.children[0].getValueInternal(state);
+		Object leftHandValue = leftHandTypedValue.getValue();
+
+		if (leftHandValue instanceof Optional<?> optional) {
+			// Compilation is currently not supported for Optional with the Elvis operator.
+			this.exitTypeDescriptor = null;
+			if (optional.isPresent()) {
+				return new TypedValue(optional.get());
+			}
+			return this.children[1].getValueInternal(state);
+		}
+
 		// If this check is changed, the generateCode method will need changing too
-		if (value.getValue() != null && !"".equals(value.getValue())) {
-			return value;
+		if (leftHandValue != null && !"".equals(leftHandValue)) {
+			return leftHandTypedValue;
 		}
 		else {
 			TypedValue result = this.children[1].getValueInternal(state);

spring-expression/src/main/java/org/springframework/expression/spel/ast/Indexer.java

@@ -20,6 +20,7 @@
 import java.util.Collection;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.function.Supplier;
 
 import org.jspecify.annotations.Nullable;
@@ -67,7 +68,12 @@
  * <p>As of Spring Framework 6.2, null-safe indexing is supported via the {@code '?.'}
  * operator. For example, {@code 'colors?.[0]'} will evaluate to {@code null} if
  * {@code colors} is {@code null} and will otherwise evaluate to the 0<sup>th</sup>
- * color.
+ * color. As of Spring Framework 7.0, null-safe indexing also applies when
+ * indexing into a structure contained in an {@link Optional}. For example, if
+ * {@code colors} is of type {@code Optional<Colors>}, the expression
+ * {@code 'colors?.[0]'} will evaluate to {@code null} if {@code colors} is
+ * {@code null} or {@link Optional#isEmpty() empty} and will otherwise evaluate
+ * to the 0<sup>th</sup> color, effectively {@code colors.get()[0]}.
  *
  * @author Andy Clement
  * @author Phillip Webb
@@ -165,11 +171,20 @@ private ValueRef getValueRef(ExpressionState state, AccessMode accessMode) throw
 		TypedValue context = state.getActiveContextObject();
 		Object target = context.getValue();
 
-		if (target == null) {
-			if (isNullSafe()) {
+		if (isNullSafe()) {
+			if (target == null) {
 				return ValueRef.NullValueRef.INSTANCE;
 			}
-			// Raise a proper exception in case of a null target
+			if (target instanceof Optional<?> optional) {
+				if (optional.isEmpty()) {
+					return ValueRef.NullValueRef.INSTANCE;
+				}
+				target = optional.get();
+			}
+		}
+
+		// Raise a proper exception in case of a null target
+		if (target == null) {
 			throw new SpelEvaluationException(getStartPosition(), SpelMessage.CANNOT_INDEX_INTO_NULL_VALUE);
 		}
 

spring-expression/src/main/java/org/springframework/expression/spel/ast/MethodReference.java

@@ -23,6 +23,7 @@
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
+import java.util.Optional;
 import java.util.StringJoiner;
 
 import org.jspecify.annotations.Nullable;
@@ -47,7 +48,21 @@
 import org.springframework.util.ObjectUtils;
 
 /**
- * Expression language AST node that represents a method reference.
+ * Expression language AST node that represents a method reference (i.e., a
+ * method invocation other than a simple property reference).
+ *
+ * <h3>Null-safe Invocation</h3>
+ *
+ * <p>Null-safe invocation is supported via the {@code '?.'} operator. For example,
+ * {@code 'counter?.incrementBy(1)'} will evaluate to {@code null} if {@code counter}
+ * is {@code null} and will otherwise evaluate to the value returned from the
+ * invocation of {@code counter.incrementBy(1)}. As of Spring Framework 7.0,
+ * null-safe invocation also applies when invoking a method on an {@link Optional}
+ * target. For example, if {@code counter} is of type {@code Optional<Counter>},
+ * the expression {@code 'counter?.incrementBy(1)'} will evaluate to {@code null}
+ * if {@code counter} is {@code null} or {@link Optional#isEmpty() empty} and will
+ * otherwise evaluate the value returned from the invocation of
+ * {@code counter.get().incrementBy(1)}.
  *
  * @author Andy Clement
  * @author Juergen Hoeller
@@ -92,7 +107,9 @@ public final String getName() {
 	protected ValueRef getValueRef(ExpressionState state) throws EvaluationException {
 		@Nullable Object[] arguments = getArguments(state);
 		if (state.getActiveContextObject().getValue() == null) {
-			throwIfNotNullSafe(getArgumentTypes(arguments));
+			if (!isNullSafe()) {
+				throw nullTargetObjectException(getArgumentTypes(arguments));
+			}
 			return ValueRef.NullValueRef.INSTANCE;
 		}
 		return new MethodValueRef(state, arguments);
@@ -109,19 +126,32 @@ public TypedValue getValueInternal(ExpressionState state) throws EvaluationExcep
 		return result;
 	}
 
-	private TypedValue getValueInternal(EvaluationContext evaluationContext,
-			@Nullable Object value, @Nullable TypeDescriptor targetType, @Nullable Object[] arguments) {
+	private TypedValue getValueInternal(EvaluationContext evaluationContext, final @Nullable Object value,
+			@Nullable TypeDescriptor targetType, @Nullable Object[] arguments) {
 
+		Object target = value;
 		List<TypeDescriptor> argumentTypes = getArgumentTypes(arguments);
-		if (value == null) {
-			throwIfNotNullSafe(argumentTypes);
-			return TypedValue.NULL;
+
+		if (isNullSafe()) {
+			if (target == null) {
+				return TypedValue.NULL;
+			}
+			if (target instanceof Optional<?> optional) {
+				if (optional.isEmpty()) {
+					return TypedValue.NULL;
+				}
+				target = optional.get();
+			}
 		}
 
-		MethodExecutor executorToUse = getCachedExecutor(evaluationContext, value, targetType, argumentTypes);
+		if (target == null) {
+			throw nullTargetObjectException(argumentTypes);
+		}
+
+		MethodExecutor executorToUse = getCachedExecutor(evaluationContext, target, targetType, argumentTypes);
 		if (executorToUse != null) {
 			try {
-				return executorToUse.execute(evaluationContext, value, arguments);
+				return executorToUse.execute(evaluationContext, target, arguments);
 			}
 			catch (AccessException ex) {
 				// Two reasons this can occur:
@@ -135,7 +165,7 @@ private TypedValue getValueInternal(EvaluationContext evaluationContext,
 				// To determine the situation, the AccessException will contain a cause.
 				// If the cause is an InvocationTargetException, a user exception was
 				// thrown inside the method. Otherwise the method could not be invoked.
-				throwSimpleExceptionIfPossible(value, ex);
+				throwSimpleExceptionIfPossible(target, ex);
 
 				// At this point we know it wasn't a user problem so worth a retry if a
 				// better candidate can be found.
@@ -144,27 +174,25 @@ private TypedValue getValueInternal(EvaluationContext evaluationContext,
 		}
 
 		// either there was no accessor or it no longer existed
-		executorToUse = findAccessorForMethod(argumentTypes, value, evaluationContext);
+		executorToUse = findAccessorForMethod(argumentTypes, target, evaluationContext);
 		this.cachedExecutor = new CachedMethodExecutor(
-				executorToUse, (value instanceof Class<?> clazz ? clazz : null), targetType, argumentTypes);
+				executorToUse, (target instanceof Class<?> clazz ? clazz : null), targetType, argumentTypes);
 		try {
-			return executorToUse.execute(evaluationContext, value, arguments);
+			return executorToUse.execute(evaluationContext, target, arguments);
 		}
 		catch (AccessException ex) {
 			// Same unwrapping exception handling as above in above catch block
-			throwSimpleExceptionIfPossible(value, ex);
+			throwSimpleExceptionIfPossible(target, ex);
 			throw new SpelEvaluationException(getStartPosition(), ex,
 					SpelMessage.EXCEPTION_DURING_METHOD_INVOCATION, this.name,
-					value.getClass().getName(), ex.getMessage());
+					(value != null ? value.getClass().getName() : "null"), ex.getMessage());
 		}
 	}
 
-	private void throwIfNotNullSafe(List<TypeDescriptor> argumentTypes) {
-		if (!isNullSafe()) {
-			throw new SpelEvaluationException(getStartPosition(),
-					SpelMessage.METHOD_CALL_ON_NULL_OBJECT_NOT_ALLOWED,
-					FormatHelper.formatMethodForMessage(this.name, argumentTypes));
-		}
+	private SpelEvaluationException nullTargetObjectException(List<TypeDescriptor> argumentTypes) {
+		return new SpelEvaluationException(getStartPosition(),
+				SpelMessage.METHOD_CALL_ON_NULL_OBJECT_NOT_ALLOWED,
+				FormatHelper.formatMethodForMessage(this.name, argumentTypes));
 	}
 
 	private @Nullable Object[] getArguments(ExpressionState state) {

spring-expression/src/main/java/org/springframework/expression/spel/ast/Projection.java

@@ -21,6 +21,7 @@
 import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 
 import org.jspecify.annotations.Nullable;
 
@@ -33,12 +34,25 @@
 import org.springframework.util.ObjectUtils;
 
 /**
- * Represents projection, where a given operation is performed on all elements in some
- * input sequence, returning a new sequence of the same size.
+ * Represents projection, where a given operation is performed on all elements in
+ * some input sequence, returning a new sequence of the same size.
  *
  * <p>For example: <code>{1,2,3,4,5,6,7,8,9,10}.![#isEven(#this)]</code> evaluates
  * to {@code [n, y, n, y, n, y, n, y, n, y]}.
  *
+ * <h3>Null-safe Projection</h3>
+ *
+ * <p>Null-safe projection is supported via the {@code '?.!'} operator. For example,
+ * {@code 'names?.![#this.length]'} will evaluate to {@code null} if {@code names}
+ * is {@code null} and will otherwise evaluate to a sequence containing the lengths
+ * of the names. As of Spring Framework 7.0, null-safe projection also applies when
+ * performing projection on an {@link Optional} target. For example, if {@code names}
+ * is of type {@code Optional<List<String>>}, the expression
+ * {@code 'names?.![#this.length]'} will evaluate to {@code null} if {@code names}
+ * is {@code null} or {@link Optional#isEmpty() empty} and will otherwise evaluate
+ * to a sequence containing the lengths of the names, effectively
+ * {@code names.get().stream().map(String::length).toList()}.
+ *
  * @author Andy Clement
  * @author Mark Fisher
  * @author Juergen Hoeller
@@ -72,8 +86,24 @@ public TypedValue getValueInternal(ExpressionState state) throws EvaluationExcep
 
 	@Override
 	protected ValueRef getValueRef(ExpressionState state) throws EvaluationException {
-		TypedValue op = state.getActiveContextObject();
-		Object operand = op.getValue();
+		TypedValue contextObject = state.getActiveContextObject();
+		Object operand = contextObject.getValue();
+
+		if (isNullSafe()) {
+			if (operand == null) {
+				return ValueRef.NullValueRef.INSTANCE;
+			}
+			if (operand instanceof Optional<?> optional) {
+				if (optional.isEmpty()) {
+					return ValueRef.NullValueRef.INSTANCE;
+				}
+				operand = optional.get();
+			}
+		}
+
+		if (operand == null) {
+			throw new SpelEvaluationException(getStartPosition(), SpelMessage.PROJECTION_NOT_SUPPORTED_ON_TYPE, "null");
+		}
 
 		// When the input is a map, we push a Map.Entry on the stack before calling
 		// the specified operation. Map.Entry has two properties 'key' and 'value'
@@ -130,15 +160,9 @@ protected ValueRef getValueRef(ExpressionState state) throws EvaluationException
 			return new ValueRef.TypedValueHolderValueRef(new TypedValue(result),this);
 		}
 
-		if (operand == null) {
-			if (isNullSafe()) {
-				return ValueRef.NullValueRef.INSTANCE;
-			}
-			throw new SpelEvaluationException(getStartPosition(), SpelMessage.PROJECTION_NOT_SUPPORTED_ON_TYPE, "null");
-		}
-
+		Object value = contextObject.getValue();
 		throw new SpelEvaluationException(getStartPosition(), SpelMessage.PROJECTION_NOT_SUPPORTED_ON_TYPE,
-				operand.getClass().getName());
+				(value != null ? value.getClass().getName() : "null"));
 	}
 
 	@Override

spring-expression/src/main/java/org/springframework/expression/spel/ast/PropertyOrFieldReference.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,6 +21,7 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.function.Supplier;
 
 import org.jspecify.annotations.Nullable;
@@ -43,7 +44,19 @@
 import org.springframework.util.ReflectionUtils;
 
 /**
- * Represents a simple property or field reference.
+ * Represents a simple public property or field reference.
+ *
+ * <h3>Null-safe Navigation</h3>
+ *
+ * <p>Null-safe navigation is supported via the {@code '?.'} operator. For example,
+ * {@code 'user?.name'} will evaluate to {@code null} if {@code user} is {@code null}
+ * and will otherwise evaluate to the name of the user. As of Spring Framework 7.0,
+ * null-safe navigation also applies when accessing a property or field on an
+ * {@link Optional} target. For example, if {@code user} is of type
+ * {@code Optional<User>}, the expression {@code 'user?.name'} will evaluate to
+ * {@code null} if {@code user} is {@code null} or {@link Optional#isEmpty() empty}
+ * and will otherwise evaluate to the name of the user, effectively
+ * {@code user.get().getName()} or {@code user.get().name}.
  *
  * @author Andy Clement
  * @author Juergen Hoeller
@@ -180,8 +193,17 @@ private TypedValue readProperty(TypedValue contextObject, EvaluationContext eval
 			throws EvaluationException {
 
 		Object targetObject = contextObject.getValue();
-		if (targetObject == null && isNullSafe()) {
-			return TypedValue.NULL;
+
+		if (isNullSafe()) {
+			if (targetObject == null) {
+				return TypedValue.NULL;
+			}
+			if (targetObject instanceof Optional<?> optional) {
+				if (optional.isEmpty()) {
+					return TypedValue.NULL;
+				}
+				targetObject = optional.get();
+			}
 		}
 
 		PropertyAccessor accessorToUse = this.cachedReadAccessor;