Polish SpEL Javadocs and internals

Author: sbrannen

spring-expression/src/main/java/org/springframework/expression/common/CompositeStringExpression.java

@@ -80,7 +80,7 @@ public String getValue() throws EvaluationException {
 	@Override
 	@Nullable
 	public <T> T getValue(@Nullable Class<T> expectedResultType) throws EvaluationException {
-		Object value = getValue();
+		String value = getValue();
 		return ExpressionUtils.convertTypedValue(null, new TypedValue(value), expectedResultType);
 	}
 
@@ -99,7 +99,7 @@ public String getValue(@Nullable Object rootObject) throws EvaluationException {
 	@Override
 	@Nullable
 	public <T> T getValue(@Nullable Object rootObject, @Nullable Class<T> desiredResultType) throws EvaluationException {
-		Object value = getValue(rootObject);
+		String value = getValue(rootObject);
 		return ExpressionUtils.convertTypedValue(null, new TypedValue(value), desiredResultType);
 	}
 
@@ -120,7 +120,7 @@ public String getValue(EvaluationContext context) throws EvaluationException {
 	public <T> T getValue(EvaluationContext context, @Nullable Class<T> expectedResultType)
 			throws EvaluationException {
 
-		Object value = getValue(context);
+		String value = getValue(context);
 		return ExpressionUtils.convertTypedValue(context, new TypedValue(value), expectedResultType);
 	}
 
@@ -141,7 +141,7 @@ public String getValue(EvaluationContext context, @Nullable Object rootObject) t
 	public <T> T getValue(EvaluationContext context, @Nullable Object rootObject, @Nullable Class<T> desiredResultType)
 			throws EvaluationException {
 
-		Object value = getValue(context,rootObject);
+		String value = getValue(context,rootObject);
 		return ExpressionUtils.convertTypedValue(context, new TypedValue(value), desiredResultType);
 	}
 

spring-expression/src/main/java/org/springframework/expression/common/LiteralExpression.java

@@ -64,7 +64,7 @@ public String getValue() {
 	@Override
 	@Nullable
 	public <T> T getValue(@Nullable Class<T> expectedResultType) throws EvaluationException {
-		Object value = getValue();
+		String value = getValue();
 		return ExpressionUtils.convertTypedValue(null, new TypedValue(value), expectedResultType);
 	}
 
@@ -76,7 +76,7 @@ public String getValue(@Nullable Object rootObject) {
 	@Override
 	@Nullable
 	public <T> T getValue(@Nullable Object rootObject, @Nullable Class<T> desiredResultType) throws EvaluationException {
-		Object value = getValue(rootObject);
+		String value = getValue(rootObject);
 		return ExpressionUtils.convertTypedValue(null, new TypedValue(value), desiredResultType);
 	}
 
@@ -87,10 +87,8 @@ public String getValue(EvaluationContext context) {
 
 	@Override
 	@Nullable
-	public <T> T getValue(EvaluationContext context, @Nullable Class<T> expectedResultType)
-			throws EvaluationException {
-
-		Object value = getValue(context);
+	public <T> T getValue(EvaluationContext context, @Nullable Class<T> expectedResultType) throws EvaluationException {
+		String value = getValue(context);
 		return ExpressionUtils.convertTypedValue(context, new TypedValue(value), expectedResultType);
 	}
 
@@ -104,7 +102,7 @@ public String getValue(EvaluationContext context, @Nullable Object rootObject) t
 	public <T> T getValue(EvaluationContext context, @Nullable Object rootObject, @Nullable Class<T> desiredResultType)
 			throws EvaluationException {
 
-		Object value = getValue(context, rootObject);
+		String value = getValue(context, rootObject);
 		return ExpressionUtils.convertTypedValue(context, new TypedValue(value), desiredResultType);
 	}
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * 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.
@@ -21,7 +21,6 @@
 
 import org.springframework.core.convert.TypeDescriptor;
 import org.springframework.lang.Nullable;
-import org.springframework.util.ClassUtils;
 
 /**
  * Utility methods (formatters, etc) used during parsing and evaluation.
@@ -51,10 +50,9 @@ static String formatMethodForMessage(String name, List<TypeDescriptor> argumentT
 	 * <p>A String array will have the formatted name "java.lang.String[]".
 	 * @param clazz the Class whose name is to be formatted
 	 * @return a formatted String suitable for message inclusion
-	 * @see ClassUtils#getQualifiedName(Class)
 	 */
 	static String formatClassNameForMessage(@Nullable Class<?> clazz) {
-		return (clazz != null ? ClassUtils.getQualifiedName(clazz) : "null");
+		return (clazz != null ? clazz.getTypeName() : "null");
 	}
 
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * 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.
@@ -39,16 +39,21 @@
 import org.springframework.util.ReflectionUtils;
 
 /**
- * A function reference is of the form "#someFunction(a,b,c)". Functions may be defined
- * in the context prior to the expression being evaluated. Functions may also be static
- * Java methods, registered in the context prior to invocation of the expression.
+ * A function reference is of the form "#someFunction(a,b,c)".
  *
- * <p>Functions are very simplistic. The arguments are not part of the definition
- * (right now), so the names must be unique.
+ * <p>Functions can be either a {@link Method} (for static Java methods) or a
+ * {@link MethodHandle} and must be registered in the context prior to evaluation
+ * of the expression. See the {@code registerFunction()} methods in
+ * {@link org.springframework.expression.spel.support.StandardEvaluationContext}
+ * for details.
  *
  * @author Andy Clement
  * @author Juergen Hoeller
+ * @author Simon Baslé
+ * @author Sam Brannen
  * @since 3.0
+ * @see org.springframework.expression.spel.support.StandardEvaluationContext#registerFunction(String, Method)
+ * @see org.springframework.expression.spel.support.StandardEvaluationContext#registerFunction(String, MethodHandle)
  */
 public class FunctionReference extends SpelNodeImpl {
 
@@ -72,39 +77,44 @@ public TypedValue getValueInternal(ExpressionState state) throws EvaluationExcep
 		if (value == TypedValue.NULL) {
 			throw new SpelEvaluationException(getStartPosition(), SpelMessage.FUNCTION_NOT_DEFINED, this.name);
 		}
-		Object resolvedValue = value.getValue();
-		if (resolvedValue instanceof MethodHandle methodHandle) {
+		Object function = value.getValue();
+
+		// Static Java method registered via a Method.
+		// Note: "javaMethod" cannot be named "method" due to a bug in Checkstyle.
+		if (function instanceof Method javaMethod) {
 			try {
-				return executeFunctionBoundMethodHandle(state, methodHandle);
+				return executeFunctionViaMethod(state, javaMethod);
 			}
 			catch (SpelEvaluationException ex) {
 				ex.setPosition(getStartPosition());
 				throw ex;
 			}
 		}
-		if (!(resolvedValue instanceof Method function)) {
-			// Possibly a static Java method registered as a function
-			throw new SpelEvaluationException(
-					SpelMessage.FUNCTION_REFERENCE_CANNOT_BE_INVOKED, this.name, value.getClass());
-		}
 
-		try {
-			return executeFunctionJLRMethod(state, function);
-		}
-		catch (SpelEvaluationException ex) {
-			ex.setPosition(getStartPosition());
-			throw ex;
+		// Function registered via a MethodHandle.
+		if (function instanceof MethodHandle methodHandle) {
+			try {
+				return executeFunctionViaMethodHandle(state, methodHandle);
+			}
+			catch (SpelEvaluationException ex) {
+				ex.setPosition(getStartPosition());
+				throw ex;
+			}
 		}
+
+		// Neither a Method nor a MethodHandle?
+		throw new SpelEvaluationException(
+				SpelMessage.FUNCTION_REFERENCE_CANNOT_BE_INVOKED, this.name, value.getClass());
 	}
 
 	/**
-	 * Execute a function represented as a {@code java.lang.reflect.Method}.
+	 * Execute a function represented as a {@link Method}.
 	 * @param state the expression evaluation state
 	 * @param method the method to invoke
 	 * @return the return value of the invoked Java method
 	 * @throws EvaluationException if there is any problem invoking the method
 	 */
-	private TypedValue executeFunctionJLRMethod(ExpressionState state, Method method) throws EvaluationException {
+	private TypedValue executeFunctionViaMethod(ExpressionState state, Method method) throws EvaluationException {
 		Object[] functionArgs = getArguments(state);
 
 		if (!method.isVarArgs()) {
@@ -151,35 +161,33 @@ private TypedValue executeFunctionJLRMethod(ExpressionState state, Method method
 	}
 
 	/**
-	 * Execute a function represented as {@code java.lang.invoke.MethodHandle}.
-	 * Method types that take no arguments (fully bound handles or static methods
-	 * with no parameters) can use {@code #invoke()} which is the most efficient.
-	 * Otherwise, {@code #invokeWithArguments)} is used.
+	 * Execute a function represented as {@link MethodHandle}.
+	 * <p>Method types that take no arguments (fully bound handles or static methods
+	 * with no parameters) can use {@link MethodHandle#invoke()} which is the most
+	 * efficient. Otherwise, {@link MethodHandle#invokeWithArguments()} is used.
 	 * @param state the expression evaluation state
-	 * @param methodHandle the method to invoke
+	 * @param methodHandle the method handle to invoke
 	 * @return the return value of the invoked Java method
 	 * @throws EvaluationException if there is any problem invoking the method
 	 * @since 6.1
 	 */
-	private TypedValue executeFunctionBoundMethodHandle(ExpressionState state, MethodHandle methodHandle) throws EvaluationException {
+	private TypedValue executeFunctionViaMethodHandle(ExpressionState state, MethodHandle methodHandle) throws EvaluationException {
 		Object[] functionArgs = getArguments(state);
 		MethodType declaredParams = methodHandle.type();
 		int spelParamCount = functionArgs.length;
 		int declaredParamCount = declaredParams.parameterCount();
 
 		boolean isSuspectedVarargs = declaredParams.lastParameterType().isArray();
 
-		if (spelParamCount < declaredParamCount || (spelParamCount > declaredParamCount
-				&& !isSuspectedVarargs)) {
-			//incorrect number, including more arguments and not a vararg
+		if (spelParamCount < declaredParamCount || (spelParamCount > declaredParamCount && !isSuspectedVarargs)) {
+			// incorrect number, including more arguments and not a vararg
+			// perhaps a subset of arguments was provided but the MethodHandle wasn't bound?
 			throw new SpelEvaluationException(SpelMessage.INCORRECT_NUMBER_OF_ARGUMENTS_TO_FUNCTION,
 					functionArgs.length, declaredParamCount);
-			//perhaps a subset of arguments was provided but the MethodHandle wasn't bound?
 		}
 
 		// simplest case: the MethodHandle is fully bound or represents a static method with no params:
 		if (declaredParamCount == 0) {
-			//note we consider MethodHandles not compilable
 			try {
 				return new TypedValue(methodHandle.invoke());
 			}
@@ -188,6 +196,7 @@ private TypedValue executeFunctionBoundMethodHandle(ExpressionState state, Metho
 						this.name, ex.getMessage());
 			}
 			finally {
+				// Note: we consider MethodHandles not compilable
 				this.exitTypeDescriptor = null;
 				this.method = null;
 			}
@@ -202,12 +211,11 @@ private TypedValue executeFunctionBoundMethodHandle(ExpressionState state, Metho
 		ReflectionHelper.convertAllMethodHandleArguments(converter, functionArgs, methodHandle, varArgPosition);
 
 		if (isSuspectedVarargs && declaredParamCount == 1) {
-			//we only repack the varargs if it is the ONLY argument
+			// we only repack the varargs if it is the ONLY argument
 			functionArgs = ReflectionHelper.setupArgumentsForVarargsInvocation(
 					methodHandle.type().parameterArray(), functionArgs);
 		}
 
-		//note we consider MethodHandles not compilable
 		try {
 			return new TypedValue(methodHandle.invokeWithArguments(functionArgs));
 		}
@@ -216,6 +224,7 @@ private TypedValue executeFunctionBoundMethodHandle(ExpressionState state, Metho
 					this.name, ex.getMessage());
 		}
 		finally {
+			// Note: we consider MethodHandles not compilable
 			this.exitTypeDescriptor = null;
 			this.method = null;
 		}

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

@@ -180,12 +180,12 @@ else if (target instanceof Collection<?> collection) {
 			}
 			else {
 				this.indexedType = IndexedType.STRING;
-				return new StringIndexingLValue((String) target, idx, targetDescriptor);
+				return new StringIndexingValueRef((String) target, idx, targetDescriptor);
 			}
 		}
 
 		// Try and treat the index value as a property of the context object
-		// TODO: could call the conversion service to convert the value to a String
+		// TODO Could call the conversion service to convert the value to a String
 		TypeDescriptor valueType = indexValue.getTypeDescriptor();
 		if (valueType != null && String.class == valueType.getType()) {
 			this.indexedType = IndexedType.OBJECT;
@@ -226,41 +226,42 @@ public void generateCode(MethodVisitor mv, CodeFlow cf) {
 		}
 
 		if (this.indexedType == IndexedType.ARRAY) {
-			int insn;
-			if ("D".equals(this.exitTypeDescriptor)) {
-				mv.visitTypeInsn(CHECKCAST, "[D");
-				insn = DALOAD;
-			}
-			else if ("F".equals(this.exitTypeDescriptor)) {
-				mv.visitTypeInsn(CHECKCAST, "[F");
-				insn = FALOAD;
-			}
-			else if ("J".equals(this.exitTypeDescriptor)) {
-				mv.visitTypeInsn(CHECKCAST, "[J");
-				insn = LALOAD;
-			}
-			else if ("I".equals(this.exitTypeDescriptor)) {
-				mv.visitTypeInsn(CHECKCAST, "[I");
-				insn = IALOAD;
-			}
-			else if ("S".equals(this.exitTypeDescriptor)) {
-				mv.visitTypeInsn(CHECKCAST, "[S");
-				insn = SALOAD;
-			}
-			else if ("B".equals(this.exitTypeDescriptor)) {
-				mv.visitTypeInsn(CHECKCAST, "[B");
-				insn = BALOAD;
-			}
-			else if ("C".equals(this.exitTypeDescriptor)) {
-				mv.visitTypeInsn(CHECKCAST, "[C");
-				insn = CALOAD;
-			}
-			else {
-				mv.visitTypeInsn(CHECKCAST, "["+ this.exitTypeDescriptor +
-						(CodeFlow.isPrimitiveArray(this.exitTypeDescriptor) ? "" : ";"));
-						//depthPlusOne(exitTypeDescriptor)+"Ljava/lang/Object;");
-				insn = AALOAD;
-			}
+			int insn = switch (this.exitTypeDescriptor) {
+				case "D" -> {
+					mv.visitTypeInsn(CHECKCAST, "[D");
+					yield DALOAD;
+				}
+				case "F" -> {
+					mv.visitTypeInsn(CHECKCAST, "[F");
+					yield FALOAD;
+				}
+				case "J" -> {
+					mv.visitTypeInsn(CHECKCAST, "[J");
+					yield LALOAD;
+				}
+				case "I" -> {
+					mv.visitTypeInsn(CHECKCAST, "[I");
+					yield IALOAD;
+				}
+				case "S" -> {
+					mv.visitTypeInsn(CHECKCAST, "[S");
+					yield SALOAD;
+				}
+				case "B" -> {
+					mv.visitTypeInsn(CHECKCAST, "[B");
+					yield BALOAD;
+				}
+				case "C" -> {
+					mv.visitTypeInsn(CHECKCAST, "[C");
+					yield CALOAD;
+				}
+				default -> {
+					mv.visitTypeInsn(CHECKCAST, "["+ this.exitTypeDescriptor +
+							(CodeFlow.isPrimitiveArray(this.exitTypeDescriptor) ? "" : ";"));
+					yield AALOAD;
+				}
+			};
+
 			SpelNodeImpl index = this.children[0];
 			cf.enterCompilationScope();
 			index.generateCode(mv, cf);
@@ -325,6 +326,7 @@ else if (this.indexedType == IndexedType.OBJECT) {
 
 	@Override
 	public String toStringAST() {
+		// TODO Since we do not support multidimensional arrays, we should be able to return: "[" + getChild(0).toStringAST() + "]"
 		StringJoiner sj = new StringJoiner(",", "[", "]");
 		for (int i = 0; i < getChildCount(); i++) {
 			sj.add(getChild(i).toStringAST());
@@ -744,15 +746,15 @@ public boolean isWritable() {
 	}
 
 
-	private class StringIndexingLValue implements ValueRef {
+	private class StringIndexingValueRef implements ValueRef {
 
 		private final String target;
 
 		private final int index;
 
 		private final TypeDescriptor typeDescriptor;
 
-		public StringIndexingLValue(String target, int index, TypeDescriptor typeDescriptor) {
+		public StringIndexingValueRef(String target, int index, TypeDescriptor typeDescriptor) {
 			this.target = target;
 			this.index = index;
 			this.typeDescriptor = typeDescriptor;