Merge SpEL IndexAccessor feature into main

This set of commits introduces a new IndexAccessor SPI for the Spring
Expression Language (SpEL) which allows third parties to customize the
SpEL Indexer.

A custom IndexAccessor implementation can be registered in a
StandardEvaluationContext.

For an example, see the JacksonArrayNodeIndexAccessor in IndexingTests
in the spring-expression module.

See gh-26409
Closes gh-26478

Author: sbrannen

spring-expression/spring-expression.gradle

@@ -8,4 +8,5 @@ dependencies {
 	testImplementation(testFixtures(project(":spring-core")))
 	testImplementation("org.jetbrains.kotlin:kotlin-reflect")
 	testImplementation("org.jetbrains.kotlin:kotlin-stdlib")
+	testImplementation("com.fasterxml.jackson.core:jackson-databind")
 }

spring-expression/src/main/java/org/springframework/expression/EvaluationContext.java

@@ -16,6 +16,7 @@
 
 package org.springframework.expression;
 
+import java.util.Collections;
 import java.util.List;
 import java.util.function.Supplier;
 
@@ -56,6 +57,16 @@ public interface EvaluationContext {
 	 */
 	List<PropertyAccessor> getPropertyAccessors();
 
+	/**
+	 * Return a list of index accessors that will be asked in turn to access or
+	 * set an indexed value.
+	 * <p>The default implementation returns an empty list.
+	 * @since 6.2
+	 */
+	default List<IndexAccessor> getIndexAccessors() {
+		return Collections.emptyList();
+	}
+
 	/**
 	 * Return a list of resolvers that will be asked in turn to locate a constructor.
 	 */

spring-expression/src/main/java/org/springframework/expression/IndexAccessor.java

@@ -0,0 +1,110 @@
+/*
+ * Copyright 2002-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.expression;
+
+import org.springframework.lang.Nullable;
+
+/**
+ * An index accessor is able to read from (and possibly write to) an indexed
+ * structure of an object.
+ *
+ * <p>This interface places no restrictions on what constitutes an indexed
+ * structure. Implementors are therefore free to access indexed values any way
+ * they deem appropriate.
+ *
+ * <p>An index accessor can optionally specify an array of target classes for
+ * which it should be called. However, if it returns {@code null} or an empty
+ * array from {@link #getSpecificTargetClasses()}, it will be called for all
+ * indexing operations and given a chance to determine if it can read from or
+ * write to the indexed structure.
+ *
+ * <p>Index accessors are considered to be ordered, and each will be called in
+ * turn. The only rule that affects the call order is that any index accessor
+ * which specifies explicit support for the target class via
+ * {@link #getSpecificTargetClasses()} will be called first, before other
+ * generic index accessors.
+ *
+ * @author Jackmiking Lee
+ * @author Sam Brannen
+ * @since 6.2
+ * @see PropertyAccessor
+ */
+public interface IndexAccessor extends TargetedAccessor {
+
+	/**
+	 * Get the set of classes for which this index accessor should be called.
+	 * <p>Returning {@code null} or an empty array indicates this is a generic
+	 * index accessor that can be called in an attempt to access an index on any
+	 * type.
+	 * @return an array of classes that this index accessor is suitable for
+	 * (or {@code null} or an empty array if a generic index accessor)
+	 */
+	@Override
+	@Nullable
+	Class<?>[] getSpecificTargetClasses();
+
+	/**
+	 * Determine if this index accessor is able to read a specified index on a
+	 * specified target object.
+	 * @param context the evaluation context in which the access is being attempted
+	 * @param target the target object upon which the index is being accessed
+	 * @param index the index being accessed
+	 * @return {@code true} if this index accessor is able to read the index
+	 * @throws AccessException if there is any problem determining whether the
+	 * index can be read
+	 */
+	boolean canRead(EvaluationContext context, Object target, Object index) throws AccessException;
+
+	/**
+	 * Read an index from a specified target object.
+	 * <p>Should only be invoked if {@link #canRead} returns {@code true} for the
+	 * same arguments.
+	 * @param context the evaluation context in which the access is being attempted
+	 * @param target the target object upon which the index is being accessed
+	 * @param index the index being accessed
+	 * @return a TypedValue object wrapping the index value read and a type
+	 * descriptor for the value
+	 * @throws AccessException if there is any problem reading the index
+	 */
+	TypedValue read(EvaluationContext context, Object target, Object index) throws AccessException;
+
+	/**
+	 * Determine if this index accessor is able to write to a specified index on
+	 * a specified target object.
+	 * @param context the evaluation context in which the access is being attempted
+	 * @param target the target object upon which the index is being accessed
+	 * @param index the index being accessed
+	 * @return {@code true} if this index accessor is able to write to the index
+	 * @throws AccessException if there is any problem determining whether the
+	 * index can be written to
+	 */
+	boolean canWrite(EvaluationContext context, Object target, Object index) throws AccessException;
+
+	/**
+	 * Write to an index on a specified target object.
+	 * <p>Should only be invoked if {@link #canWrite} returns {@code true} for the
+	 * same arguments.
+	 * @param context the evaluation context in which the access is being attempted
+	 * @param target the target object upon which the index is being accessed
+	 * @param index the index being accessed
+	 * @param newValue the new value for the index
+	 * @throws AccessException if there is any problem writing to the index
+	 */
+	void write(EvaluationContext context, Object target, Object index, @Nullable Object newValue)
+			throws AccessException;
+
+}

spring-expression/src/main/java/org/springframework/expression/PropertyAccessor.java

@@ -34,21 +34,24 @@
  * <p>Property accessors are considered to be ordered, and each will be called in
  * turn. The only rule that affects the call order is that any property accessor
  * which specifies explicit support for the target class via
- * {@link #getSpecificTargetClasses()} will be called first, before the general
+ * {@link #getSpecificTargetClasses()} will be called first, before the generic
  * property accessors.
  *
  * @author Andy Clement
  * @since 3.0
+ * @see IndexAccessor
  */
-public interface PropertyAccessor {
+public interface PropertyAccessor extends TargetedAccessor {
 
 	/**
-	 * Return an array of classes for which this property accessor should be called.
-	 * <p>Returning {@code null} indicates this is a general property accessor that
-	 * can be called in an attempt to access a property on any type.
+	 * Get the set of classes for which this property accessor should be called.
+	 * <p>Returning {@code null} or an empty array indicates this is a generic
+	 * property accessor that can be called in an attempt to access a property on
+	 * any type.
 	 * @return an array of classes that this property accessor is suitable for
-	 * (or {@code null} if a general property accessor)
+	 * (or {@code null} if a generic property accessor)
 	 */
+	@Override
 	@Nullable
 	Class<?>[] getSpecificTargetClasses();
 

spring-expression/src/main/java/org/springframework/expression/TargetedAccessor.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2002-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.expression;
+
+import org.springframework.lang.Nullable;
+
+/**
+ * Strategy for types that access elements of specific target classes.
+ *
+ * <p>This interface places no restrictions on what constitutes an element.
+ *
+ * <p>A targeted accessor can specify a set of target classes for which it should
+ * be called. However, if it returns {@code null} or an empty array from
+ * {@link #getSpecificTargetClasses()}, it will typically be called for all
+ * access operations and given a chance to determine if it supports a concrete
+ * access attempt.
+ *
+ * <p>Targeted accessors are considered to be ordered, and each will be called
+ * in turn. The only rule that affects the call order is that any accessor which
+ * specifies explicit support for a given target class via
+ * {@link #getSpecificTargetClasses()} will be called first, before other generic
+ * accessors that do not specify explicit support for the given target class.
+ *
+ * @author Sam Brannen
+ * @since 6.2
+ * @see PropertyAccessor
+ * @see IndexAccessor
+ */
+public interface TargetedAccessor {
+
+	/**
+	 * Get the set of classes for which this accessor should be called.
+	 * <p>Returning {@code null} or an empty array indicates this is a generic
+	 * accessor that can be called in an attempt to access an element on any
+	 * type.
+	 * @return an array of classes that this accessor is suitable for
+	 * (or {@code null} or an empty array if a generic accessor)
+	 */
+	@Nullable
+	Class<?>[] getSpecificTargetClasses();
+
+}

spring-expression/src/main/java/org/springframework/expression/spel/SpelMessage.java

@@ -291,7 +291,16 @@ public enum SpelMessage {
 
 	/** @since 6.0.13 */
 	NEGATIVE_REPEATED_TEXT_COUNT(Kind.ERROR, 1081,
-			"Repeat count ''{0}'' must not be negative");
+			"Repeat count ''{0}'' must not be negative"),
+
+	/** @since 6.2 */
+	EXCEPTION_DURING_INDEX_READ(Kind.ERROR, 1082,
+			"A problem occurred while attempting to read index ''{0}'' in ''{1}''"),
+
+	/** @since 6.2 */
+	EXCEPTION_DURING_INDEX_WRITE(Kind.ERROR, 1083,
+			"A problem occurred while attempting to write index ''{0}'' in ''{1}''");
+
 
 
 	private final Kind kind;

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

@@ -17,63 +17,104 @@
 package org.springframework.expression.spel.ast;
 
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
 
 import org.springframework.expression.PropertyAccessor;
+import org.springframework.expression.TargetedAccessor;
 import org.springframework.lang.Nullable;
 import org.springframework.util.ObjectUtils;
 
 /**
  * Utility methods for use in the AST classes.
  *
  * @author Andy Clement
+ * @author Sam Brannen
  * @since 3.0.2
  */
 public abstract class AstUtils {
 
 	/**
-	 * Determine the set of property accessors that should be used to try to
-	 * access a property on the specified target type.
+	 * Determine the set of accessors that should be used to try to access an
+	 * element on the specified target type.
 	 * <p>The accessors are considered to be in an ordered list; however, in the
 	 * returned list any accessors that are exact matches for the input target
-	 * type (as opposed to 'general' accessors that could work for any type) are
+	 * type (as opposed to 'generic' accessors that could work for any type) are
 	 * placed at the start of the list. In addition, if there are specific
 	 * accessors that exactly name the class in question and accessors that name
 	 * a specific class which is a supertype of the class in question, the latter
 	 * are put at the end of the specific accessors set and will be tried after
 	 * exactly matching accessors but before generic accessors.
-	 * @param targetType the type upon which property access is being attempted
-	 * @param propertyAccessors the list of property accessors to process
-	 * @return a list of accessors that should be tried in order to access the property
+	 * @param targetType the type upon which element access is being attempted
+	 * @param accessors the list of element accessors to process
+	 * @return a list of accessors that should be tried in order to access the
+	 * element on the specified target type, or an empty list if no suitable
+	 * accessor could be found
+	 * @since 6.2
 	 */
-	public static List<PropertyAccessor> getPropertyAccessorsToTry(
-			@Nullable Class<?> targetType, List<PropertyAccessor> propertyAccessors) {
+	public static <T extends TargetedAccessor> List<T> getAccessorsToTry(
+			@Nullable Class<?> targetType, List<T> accessors) {
+
+		if (accessors.isEmpty()) {
+			return Collections.emptyList();
+		}
 
-		List<PropertyAccessor> specificAccessors = new ArrayList<>();
-		List<PropertyAccessor> generalAccessors = new ArrayList<>();
-		for (PropertyAccessor accessor : propertyAccessors) {
+		List<T> exactMatches = new ArrayList<>();
+		List<T> inexactMatches = new ArrayList<>();
+		List<T> genericMatches = new ArrayList<>();
+		for (T accessor : accessors) {
 			Class<?>[] targets = accessor.getSpecificTargetClasses();
 			if (ObjectUtils.isEmpty(targets)) {
 				// generic accessor that says it can be used for any type
-				generalAccessors.add(accessor);
+				genericMatches.add(accessor);
 			}
 			else if (targetType != null) {
 				for (Class<?> clazz : targets) {
 					if (clazz == targetType) {
-						// add exact matches to the specificAccessors list
-						specificAccessors.add(accessor);
+						exactMatches.add(accessor);
 					}
 					else if (clazz.isAssignableFrom(targetType)) {
-						// add supertype matches to the front of the generalAccessors list
-						generalAccessors.add(0, accessor);
+						inexactMatches.add(accessor);
 					}
 				}
 			}
 		}
-		List<PropertyAccessor> accessors = new ArrayList<>(specificAccessors.size() + generalAccessors.size());
-		accessors.addAll(specificAccessors);
-		accessors.addAll(generalAccessors);
-		return accessors;
+
+		int size = exactMatches.size() + inexactMatches.size() + genericMatches.size();
+		if (size == 0) {
+			return Collections.emptyList();
+		}
+		else {
+			List<T> result = new ArrayList<>(size);
+			result.addAll(exactMatches);
+			result.addAll(inexactMatches);
+			result.addAll(genericMatches);
+			return result;
+		}
+	}
+
+	/**
+	 * Determine the set of property accessors that should be used to try to
+	 * access a property on the specified target type.
+	 * <p>The accessors are considered to be in an ordered list; however, in the
+	 * returned list any accessors that are exact matches for the input target
+	 * type (as opposed to 'generic' accessors that could work for any type) are
+	 * placed at the start of the list. In addition, if there are specific
+	 * accessors that exactly name the class in question and accessors that name
+	 * a specific class which is a supertype of the class in question, the latter
+	 * are put at the end of the specific accessors set and will be tried after
+	 * exactly matching accessors but before generic accessors.
+	 * @param targetType the type upon which property access is being attempted
+	 * @param propertyAccessors the list of property accessors to process
+	 * @return a list of accessors that should be tried in order to access the
+	 * property on the specified target type, or an empty list if no suitable
+	 * accessor could be found
+	 * @see #getAccessorsToTry(Class, List)
+	 */
+	public static List<PropertyAccessor> getPropertyAccessorsToTry(
+			@Nullable Class<?> targetType, List<PropertyAccessor> propertyAccessors) {
+
+		return getAccessorsToTry(targetType, propertyAccessors);
 	}
 
 }