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:

- PropertyOrFieldReference
- MethodReference
- Indexer
- Projection
- Selection
- Elvis

Specifically, when a null-safe operator is applied to an empty
`Optional`, it will be treated as if the `Optional` were `null`, and
the subsequent operation will evaluate to `null`. However, if a
null-safe operator is applied to a non-empty `Optional`, the subsequent
operation will be applied to the object contained in the `Optional`,
thereby effectively unwrapping the `Optional`.

For example, if `user` is of type `Optional<User>`, the expression
`user?.name` will evaluate to `null` if `user` is either `null` or an
empty `Optional` and will otherwise evaluate to the `name` of the
`user`, effectively `user.get().getName()` for property access.

Note, however, that invocations of methods defined in the `Optional`
API are still supported on an empty `Optional`. For example, if `name`
is of type `Optional<String>`, the expression `name?.orElse('Unknown')`
will evaluate to "Unknown" if `name` is an empty `Optional` and will
otherwise evaluate to the `String` contained in the `Optional` if
`name` is a non-empty `Optional`, effectively `name.get()`.

Closes gh-20433

Author: sbrannen

framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-elvis.adoc

@@ -46,6 +46,17 @@ need to use `name != null && !name.isEmpty()` as the predicate to be compatible
 semantics of the SpEL Elvis operator.
 ====
 
+[TIP]
+====
+As of Spring Framework 7.0, the SpEL Elvis operator supports `java.util.Optional` with
+transparent unwrapping semantics.
+
+For example, given the expression `A ?: B`, if `A` is `null` or an _empty_ `Optional`,
+the expression evaluates to `B`. However, if `A` is a non-empty `Optional` the expression
+evaluates to the object contained in the `Optional`, thereby effectively unwrapping the
+`Optional` which correlates to `A.get()`.
+====
+
 The following listing shows a more complex example:
 
 [tabs]

framework-docs/modules/ROOT/pages/core/expressions/language-ref/operator-safe-navigation.adoc

@@ -350,6 +350,50 @@ Kotlin::
 <2> Use null-safe projection operator on null `members` list
 ======
 
+[[expressions-operator-safe-navigation-optional]]
+== Null-safe Operations on `Optional`
+
+As of Spring Framework 7.0, null-safe operations are supported on instances of
+`java.util.Optional` with transparent unwrapping semantics.
+
+Specifically, when a null-safe operator is applied to an _empty_ `Optional`, it will be
+treated as if the `Optional` were `null`, and the subsequent operation will evaluate to
+`null`. However, if a null-safe operator is applied to a non-empty `Optional`, the
+subsequent operation will be applied to the object contained in the `Optional`, thereby
+effectively unwrapping the `Optional`.
+
+For example, if `user` is of type `Optional<User>`, the expression `user?.name` will
+evaluate to `null` if `user` is either `null` or an _empty_ `Optional` and will otherwise
+evaluate to the `name` of the `user`, effectively `user.get().getName()` or
+`user.get().name` for property or field access, respectively.
+
+[NOTE]
+====
+Invocations of methods defined in the `Optional` API are still supported on an _empty_
+`Optional`. For example, if `name` is of type `Optional<String>`, the expression
+`name?.orElse('Unknown')` will evaluate to `"Unknown"` if `name` is an empty `Optional`
+and will otherwise evaluate to the `String` contained in the `Optional` if `name` is a
+non-empty `Optional`, effectively `name.get()`.
+====
+
+// NOTE: &#8288; is the Unicode Character 'WORD JOINER', which prevents undesired line wraps.
+
+Similarly, if `names` is of type `Optional<List<String>>`, the expression
+`names?.?&#8288;[#this.length > 5]` will evaluate to `null` if `names` is `null` or an _empty_
+`Optional` and will otherwise evaluate to a sequence containing the names whose lengths
+are greater than 5, effectively
+`names.get().stream().filter(s -> s.length() > 5).toList()`.
+
+The same semantics apply to all of the null-safe operators mentioned previously in this
+chapter.
+
+For further details and examples, consult the javadoc for the following operators.
+
+* {spring-framework-api}/expression/spel/ast/PropertyOrFieldReference.html[`PropertyOrFieldReference`]
+* {spring-framework-api}/expression/spel/ast/MethodReference.html[`MethodReference`]
+* {spring-framework-api}/expression/spel/ast/Indexer.html[`Indexer`]
+* {spring-framework-api}/expression/spel/ast/Selection.html[`Selection`]
+* {spring-framework-api}/expression/spel/ast/Projection.html[`Projection`]
 
 [[expressions-operator-safe-navigation-compound-expressions]]
 == Null-safe Operations in Compound Expressions

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;
@@ -50,6 +51,19 @@
  * 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
  * @author Sam Brannen
@@ -93,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 nullTargetException(getArgumentTypes(arguments));
+			}
 			return ValueRef.NullValueRef.INSTANCE;
 		}
 		return new MethodValueRef(state, arguments);
@@ -115,9 +131,26 @@ private TypedValue getValueInternal(EvaluationContext evaluationContext, @Nullab
 			@Nullable TypeDescriptor targetType, @Nullable Object[] arguments) {
 
 		List<TypeDescriptor> argumentTypes = getArgumentTypes(arguments);
+		Optional<?> fallbackOptionalTarget = null;
+		boolean isEmptyOptional = false;
+
+		if (isNullSafe()) {
+			if (target == null) {
+				return TypedValue.NULL;
+			}
+			if (target instanceof Optional<?> optional) {
+				if (optional.isPresent()) {
+					target = optional.get();
+					fallbackOptionalTarget = optional;
+				}
+				else {
+					isEmptyOptional = true;
+				}
+			}
+		}
+
 		if (target == null) {
-			throwIfNotNullSafe(argumentTypes);
-			return TypedValue.NULL;
+			throw nullTargetException(argumentTypes);
 		}
 
 		MethodExecutor executorToUse = getCachedExecutor(evaluationContext, target, targetType, argumentTypes);
@@ -142,31 +175,64 @@ private TypedValue getValueInternal(EvaluationContext evaluationContext, @Nullab
 				// At this point we know it wasn't a user problem so worth a retry if a
 				// better candidate can be found.
 				this.cachedExecutor = null;
+				executorToUse = null;
+			}
+		}
+
+		// Either there was no cached executor, or it no longer exists.
+
+		// First, attempt to find the method on the target object.
+		Object targetToUse = target;
+		MethodExecutorSearchResult searchResult = findMethodExecutor(argumentTypes, target, evaluationContext);
+		if (searchResult.methodExecutor != null) {
+			executorToUse = searchResult.methodExecutor;
+		}
+		// Second, attempt to find the method on the original Optional instance.
+		else if (fallbackOptionalTarget != null) {
+			searchResult = findMethodExecutor(argumentTypes, fallbackOptionalTarget, evaluationContext);
+			if (searchResult.methodExecutor != null) {
+				executorToUse = searchResult.methodExecutor;
+				targetToUse = fallbackOptionalTarget;
+			}
+		}
+		// If we got this far, that means we failed to find an executor for both the
+		// target and the fallback target. So, we return NULL if the original target
+		// is a null-safe empty Optional.
+		else if (isEmptyOptional) {
+			return TypedValue.NULL;
+		}
+
+		if (executorToUse == null) {
+			String method = FormatHelper.formatMethodForMessage(this.name, argumentTypes);
+			String className = FormatHelper.formatClassNameForMessage(
+					target instanceof Class<?> clazz ? clazz : target.getClass());
+			if (searchResult.accessException != null) {
+				throw new SpelEvaluationException(
+						getStartPosition(), searchResult.accessException, SpelMessage.PROBLEM_LOCATING_METHOD, method, className);
+			}
+			else {
+				throw new SpelEvaluationException(getStartPosition(), SpelMessage.METHOD_NOT_FOUND, method, className);
 			}
 		}
 
-		// either there was no accessor or it no longer existed
-		executorToUse = findMethodExecutor(argumentTypes, target, evaluationContext);
 		this.cachedExecutor = new CachedMethodExecutor(
-				executorToUse, (target instanceof Class<?> clazz ? clazz : null), targetType, argumentTypes);
+				executorToUse, (targetToUse instanceof Class<?> clazz ? clazz : null), targetType, argumentTypes);
 		try {
-			return executorToUse.execute(evaluationContext, target, arguments);
+			return executorToUse.execute(evaluationContext, targetToUse, arguments);
 		}
 		catch (AccessException ex) {
 			// Same unwrapping exception handling as in above catch block
-			throwSimpleExceptionIfPossible(target, ex);
+			throwSimpleExceptionIfPossible(targetToUse, ex);
 			throw new SpelEvaluationException(getStartPosition(), ex,
 					SpelMessage.EXCEPTION_DURING_METHOD_INVOCATION, this.name,
-					target.getClass().getName(), ex.getMessage());
+					targetToUse.getClass().getName(), 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 nullTargetException(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) {
@@ -209,7 +275,7 @@ private List<TypeDescriptor> getArgumentTypes(@Nullable Object... arguments) {
 		return null;
 	}
 
-	private MethodExecutor findMethodExecutor(List<TypeDescriptor> argumentTypes, Object target,
+	private MethodExecutorSearchResult findMethodExecutor(List<TypeDescriptor> argumentTypes, Object target,
 			EvaluationContext evaluationContext) throws SpelEvaluationException {
 
 		AccessException accessException = null;
@@ -218,7 +284,7 @@ private MethodExecutor findMethodExecutor(List<TypeDescriptor> argumentTypes, Ob
 				MethodExecutor methodExecutor = methodResolver.resolve(
 						evaluationContext, target, this.name, argumentTypes);
 				if (methodExecutor != null) {
-					return methodExecutor;
+					return new MethodExecutorSearchResult(methodExecutor, null);
 				}
 			}
 			catch (AccessException ex) {
@@ -227,16 +293,7 @@ private MethodExecutor findMethodExecutor(List<TypeDescriptor> argumentTypes, Ob
 			}
 		}
 
-		String method = FormatHelper.formatMethodForMessage(this.name, argumentTypes);
-		String className = FormatHelper.formatClassNameForMessage(
-				target instanceof Class<?> clazz ? clazz : target.getClass());
-		if (accessException != null) {
-			throw new SpelEvaluationException(
-					getStartPosition(), accessException, SpelMessage.PROBLEM_LOCATING_METHOD, method, className);
-		}
-		else {
-			throw new SpelEvaluationException(getStartPosition(), SpelMessage.METHOD_NOT_FOUND, method, className);
-		}
+		return new MethodExecutorSearchResult(null, accessException);
 	}
 
 	/**
@@ -411,6 +468,9 @@ public boolean isWritable() {
 	}
 
 
+	private record MethodExecutorSearchResult(@Nullable MethodExecutor methodExecutor, @Nullable AccessException accessException) {
+	}
+
 	private record CachedMethodExecutor(MethodExecutor methodExecutor, @Nullable Class<?> staticClass,
 			@Nullable TypeDescriptor targetType, List<TypeDescriptor> argumentTypes) {