Introduce ValueEvaluationContextProvider and ValueExpressionEvaluator.

CachingValueExpressionEvaluatorFactory is a support utility to replace DefaultSpELExpressionEvaluator with support for Value Expressions.

Deprecate DefaultSpELExpressionEvaluator and SpELExpressionEvaluator.

Revise Parameter type to return value expressions and deprecate getSpel… methods.

Author: mp911de

src/main/java/org/springframework/data/expression/ValueEvaluationContextProvider.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2024 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.expression;
+
+import org.springframework.data.spel.ExpressionDependencies;
+import org.springframework.expression.EvaluationContext;
+
+/**
+ * SPI to provide to access a centrally defined potentially shared {@link ValueEvaluationContext}.
+ *
+ * @author Mark Paluch
+ * @since 3.3
+ */
+public interface ValueEvaluationContextProvider {
+
+	/**
+	 * Return a {@link EvaluationContext} built using the given parameter values.
+	 *
+	 * @param rootObject the root object to set in the {@link EvaluationContext}.
+	 * @return
+	 */
+	ValueEvaluationContext getEvaluationContext(Object rootObject);
+
+	/**
+	 * Return a tailored {@link EvaluationContext} built using the given parameter values and considering
+	 * {@link ExpressionDependencies expression dependencies}. The returned {@link EvaluationContext} may contain a
+	 * reduced visibility of methods and properties/fields according to the required {@link ExpressionDependencies
+	 * expression dependencies}.
+	 *
+	 * @param rootObject the root object to set in the {@link EvaluationContext}.
+	 * @param dependencies the requested expression dependencies to be available.
+	 * @return
+	 */
+	default ValueEvaluationContext getEvaluationContext(Object rootObject, ExpressionDependencies dependencies) {
+		return getEvaluationContext(rootObject);
+	}
+}

src/main/java/org/springframework/data/mapping/Parameter.java

@@ -39,11 +39,11 @@ public class Parameter<T, P extends PersistentProperty<P>> {
 	private final @Nullable String name;
 	private final TypeInformation<T> type;
 	private final MergedAnnotations annotations;
-	private final String key;
+	private final @Nullable String expression;
 	private final @Nullable PersistentEntity<T, P> entity;
 
 	private final Lazy<Boolean> enclosingClassCache;
-	private final Lazy<Boolean> hasSpelExpression;
+	private final Lazy<Boolean> hasExpression;
 
 	/**
 	 * Creates a new {@link Parameter} with the given name, {@link TypeInformation} as well as an array of
@@ -64,7 +64,7 @@ public Parameter(@Nullable String name, TypeInformation<T> type, Annotation[] an
 		this.name = name;
 		this.type = type;
 		this.annotations = MergedAnnotations.from(annotations);
-		this.key = getValue(this.annotations);
+		this.expression = getValue(this.annotations);
 		this.entity = entity;
 
 		this.enclosingClassCache = Lazy.of(() -> {
@@ -77,7 +77,7 @@ public Parameter(@Nullable String name, TypeInformation<T> type, Annotation[] an
 			return ClassUtils.isInnerClass(owningType) && type.getType().equals(owningType.getEnclosingClass());
 		});
 
-		this.hasSpelExpression = Lazy.of(() -> StringUtils.hasText(getSpelExpression()));
+		this.hasExpression = Lazy.of(() -> StringUtils.hasText(getValueExpression()));
 	}
 
 	@Nullable
@@ -128,21 +128,62 @@ public Class<T> getRawType() {
 	}
 
 	/**
-	 * Returns the key to be used when looking up a source data structure to populate the actual parameter value.
+	 * Returns the expression to be used when looking up a source data structure to populate the actual parameter value.
 	 *
-	 * @return
+	 * @return the expression to be used when looking up a source data structure.
+	 * @deprecated since 3.3, use {@link #getValueExpression()} instead.
 	 */
+	@Nullable
 	public String getSpelExpression() {
-		return key;
+		return getValueExpression();
+	}
+
+	/**
+	 * Returns the expression to be used when looking up a source data structure to populate the actual parameter value.
+	 *
+	 * @return the expression to be used when looking up a source data structure.
+	 * @since 3.3
+	 */
+	@Nullable
+	public String getValueExpression() {
+		return expression;
+	}
+
+	/**
+	 * Returns the required expression to be used when looking up a source data structure to populate the actual parameter
+	 * value or throws {@link IllegalStateException} if there's no expression.
+	 *
+	 * @return the expression to be used when looking up a source data structure.
+	 * @since 3.3
+	 */
+	public String getRequiredValueExpression() {
+
+		if (!hasValueExpression()) {
+			throw new IllegalStateException("No expression associated with this parameter");
+		}
+
+		return getValueExpression();
 	}
 
 	/**
 	 * Returns whether the constructor parameter is equipped with a SpEL expression.
 	 *
-	 * @return
+	 * @return {@literal true}} if the parameter is equipped with a SpEL expression.
+	 * @deprecated since 3.3, use {@link #hasValueExpression()} instead.
 	 */
+	@Deprecated(since = "3.3")
 	public boolean hasSpelExpression() {
-		return this.hasSpelExpression.get();
+		return hasValueExpression();
+	}
+
+	/**
+	 * Returns whether the constructor parameter is equipped with a value expression.
+	 *
+	 * @return {@literal true}} if the parameter is equipped with a value expression.
+	 * @since 3.3
+	 */
+	public boolean hasValueExpression() {
+		return this.hasExpression.get();
 	}
 
 	@Override
@@ -157,12 +198,12 @@ public boolean equals(@Nullable Object o) {
 		}
 
 		return Objects.equals(this.name, that.name) && Objects.equals(this.type, that.type)
-				&& Objects.equals(this.key, that.key) && Objects.equals(this.entity, that.entity);
+				&& Objects.equals(this.expression, that.expression) && Objects.equals(this.entity, that.entity);
 	}
 
 	@Override
 	public int hashCode() {
-		return Objects.hash(name, type, key, entity);
+		return Objects.hash(name, type, expression, entity);
 	}
 
 	/**

src/main/java/org/springframework/data/mapping/model/CachingValueExpressionEvaluatorFactory.java

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2024 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.mapping.model;
+
+import org.springframework.core.env.EnvironmentCapable;
+import org.springframework.data.expression.ValueEvaluationContext;
+import org.springframework.data.expression.ValueEvaluationContextProvider;
+import org.springframework.data.expression.ValueExpression;
+import org.springframework.data.expression.ValueExpressionParser;
+import org.springframework.data.spel.EvaluationContextProvider;
+import org.springframework.data.spel.ExpressionDependencies;
+import org.springframework.expression.ExpressionParser;
+import org.springframework.util.Assert;
+import org.springframework.util.ConcurrentLruCache;
+
+/**
+ * Factory to create a ValueExpressionEvaluator
+ *
+ * @author Mark Paluch
+ * @since 3.3
+ */
+public class CachingValueExpressionEvaluatorFactory implements ValueEvaluationContextProvider {
+
+	private final ConcurrentLruCache<String, ValueExpression> expressionCache;
+	private final EnvironmentCapable environmentProvider;
+	private final EvaluationContextProvider evaluationContextProvider;
+
+	public CachingValueExpressionEvaluatorFactory(ExpressionParser expressionParser,
+			EnvironmentCapable environmentProvider, EvaluationContextProvider evaluationContextProvider) {
+		this(expressionParser, environmentProvider, evaluationContextProvider, 256);
+	}
+
+	public CachingValueExpressionEvaluatorFactory(ExpressionParser expressionParser,
+			EnvironmentCapable environmentProvider, EvaluationContextProvider evaluationContextProvider, int cacheSize) {
+
+		Assert.notNull(expressionParser, "ExpressionParser must not be null");
+
+		ValueExpressionParser parser = ValueExpressionParser.create(() -> expressionParser);
+		this.expressionCache = new ConcurrentLruCache<>(cacheSize, parser::parse);
+		this.environmentProvider = environmentProvider;
+		this.evaluationContextProvider = evaluationContextProvider;
+	}
+
+	@Override
+	public ValueEvaluationContext getEvaluationContext(Object rootObject) {
+		return ValueEvaluationContext.of(environmentProvider.getEnvironment(),
+				evaluationContextProvider.getEvaluationContext(rootObject));
+	}
+
+	@Override
+	public ValueEvaluationContext getEvaluationContext(Object rootObject, ExpressionDependencies dependencies) {
+		return ValueEvaluationContext.of(environmentProvider.getEnvironment(),
+				evaluationContextProvider.getEvaluationContext(rootObject, dependencies));
+	}
+
+	/**
+	 * Creates a new {@link ValueExpressionEvaluator} using the given {@code source} as root object.
+	 *
+	 * @param source the root object for evaluating the expression.
+	 * @return a new {@link ValueExpressionEvaluator} to evaluate the expression in the context of the given
+	 *         {@code source} object.
+	 */
+	public ValueExpressionEvaluator create(Object source) {
+
+		return new ValueExpressionEvaluator() {
+			@SuppressWarnings("unchecked")
+			@Override
+			public <T> T evaluate(String expression) {
+				ValueExpression valueExpression = expressionCache.get(expression);
+				return (T) valueExpression.evaluate(getEvaluationContext(source, valueExpression.getExpressionDependencies()));
+			}
+		};
+	}
+
+}

src/main/java/org/springframework/data/mapping/model/DefaultSpELExpressionEvaluator.java

@@ -28,7 +28,9 @@
  * {@link SpelExpressionParser} and {@link EvaluationContext}.
  *
  * @author Oliver Gierke
+ * @deprecated since 3.3, use {@link CachingValueExpressionEvaluatorFactory} instead.
  */
+@Deprecated(since = "3.3")
 public class DefaultSpELExpressionEvaluator implements SpELExpressionEvaluator {
 
 	private final Object source;

src/main/java/org/springframework/data/mapping/model/PersistentEntityParameterValueProvider.java

@@ -45,6 +45,7 @@ public PersistentEntityParameterValueProvider(PersistentEntity<?, P> entity, Pro
 		this.parent = parent;
 	}
 
+	@Override
 	@Nullable
 	@SuppressWarnings("unchecked")
 	public <T> T getParameterValue(Parameter<T, P> parameter) {

src/main/java/org/springframework/data/mapping/model/SpELContext.java

@@ -17,6 +17,7 @@
 
 import org.springframework.beans.factory.BeanFactory;
 import org.springframework.context.expression.BeanFactoryResolver;
+import org.springframework.data.spel.EvaluationContextProvider;
 import org.springframework.expression.EvaluationContext;
 import org.springframework.expression.ExpressionParser;
 import org.springframework.expression.PropertyAccessor;
@@ -30,7 +31,7 @@
  *
  * @author Oliver Gierke
  */
-public class SpELContext {
+public class SpELContext implements EvaluationContextProvider {
 
 	private final SpelExpressionParser parser;
 	private final PropertyAccessor accessor;
@@ -90,6 +91,7 @@ public ExpressionParser getParser() {
 		return this.parser;
 	}
 
+	@Override
 	public EvaluationContext getEvaluationContext(Object source) {
 
 		StandardEvaluationContext evaluationContext = new StandardEvaluationContext(source);

src/main/java/org/springframework/data/mapping/model/SpELExpressionEvaluator.java

@@ -15,21 +15,12 @@
  */
 package org.springframework.data.mapping.model;
 
-import org.springframework.lang.Nullable;
-
 /**
  * SPI for components that can evaluate Spring EL expressions.
  *
  * @author Oliver Gierke
  */
-public interface SpELExpressionEvaluator {
+@Deprecated(since = "3.3")
+public interface SpELExpressionEvaluator extends ValueExpressionEvaluator {
 
-	/**
-	 * Evaluates the given expression.
-	 *
-	 * @param expression
-	 * @return
-	 */
-	@Nullable
-	<T> T evaluate(String expression);
 }

src/main/java/org/springframework/data/mapping/model/SpELExpressionParameterValueProvider.java

@@ -16,53 +16,24 @@
 package org.springframework.data.mapping.model;
 
 import org.springframework.core.convert.ConversionService;
-import org.springframework.data.mapping.Parameter;
 import org.springframework.data.mapping.PersistentProperty;
-import org.springframework.lang.Nullable;
 
 /**
  * {@link ParameterValueProvider} that can be used to front a {@link ParameterValueProvider} delegate to prefer a SpEL
  * expression evaluation over directly resolving the parameter value with the delegate.
  *
  * @author Oliver Gierke
  * @author Mark Paluch
+ * @deprecated since 3.3, use {@link ValueExpressionParameterValueProvider} instead.
  */
+@Deprecated(since = "3.3")
 public class SpELExpressionParameterValueProvider<P extends PersistentProperty<P>>
-		implements ParameterValueProvider<P> {
-
-	private final SpELExpressionEvaluator evaluator;
-	private final ConversionService conversionService;
-	private final ParameterValueProvider<P> delegate;
+		extends ValueExpressionParameterValueProvider<P> implements ParameterValueProvider<P> {
 
 	public SpELExpressionParameterValueProvider(SpELExpressionEvaluator evaluator, ConversionService conversionService,
 			ParameterValueProvider<P> delegate) {
 
-		this.evaluator = evaluator;
-		this.conversionService = conversionService;
-		this.delegate = delegate;
-	}
-
-	@Nullable
-	public <T> T getParameterValue(Parameter<T, P> parameter) {
-
-		if (!parameter.hasSpelExpression()) {
-			return delegate == null ? null : delegate.getParameterValue(parameter);
-		}
-
-		Object object = evaluator.evaluate(parameter.getSpelExpression());
-		return object == null ? null : potentiallyConvertSpelValue(object, parameter);
+		super(evaluator, conversionService, delegate);
 	}
 
-	/**
-	 * Hook to allow to massage the value resulting from the Spel expression evaluation. Default implementation will
-	 * leverage the configured {@link ConversionService} to massage the value into the parameter type.
-	 *
-	 * @param object the value to massage, will never be {@literal null}.
-	 * @param parameter the {@link Parameter} we create the value for
-	 * @return
-	 */
-	@Nullable
-	protected <T> T potentiallyConvertSpelValue(Object object, Parameter<T, P> parameter) {
-		return conversionService.convert(object, parameter.getRawType());
-	}
 }