Harmonize hint registration

Previously, a shortcut method for the default ExecutableMode was
provided, but we found out that the shortcut makes it harder to
determine the intent.

This commit harmonizes hints registration for types, methods, and
fields. An ExecutableMode is now mandatory to register a method or
constructor. Previous methods that infer a mode or provided a
customizer of the builder are deprecated.

Closes gh-29135

Author: snicoll

spring-beans/src/main/java/org/springframework/beans/factory/annotation/AutowiredAnnotationBeanPostProcessor.java

@@ -1007,7 +1007,7 @@ private CodeBlock generateMethodStatementForMethod(Method method,
 			AccessVisibility visibility = AccessVisibility.forMember(method);
 			if (visibility == AccessVisibility.PRIVATE
 					|| visibility == AccessVisibility.PROTECTED) {
-				hints.reflection().registerMethod(method);
+				hints.reflection().registerMethod(method, ExecutableMode.INVOKE);
 				code.add(".resolveAndInvoke($L, $L)", REGISTERED_BEAN_PARAMETER,
 						INSTANCE_PARAMETER);
 			}

spring-beans/src/main/java/org/springframework/beans/factory/aot/BeanDefinitionPropertiesCodeGenerator.java

@@ -145,7 +145,7 @@ private void addInitDestroyMethods(Builder code,
 	private void addInitDestroyHint(Class<?> beanUserClass, String methodName) {
 		Method method = ReflectionUtils.findMethod(beanUserClass, methodName);
 		if (method != null) {
-			this.hints.reflection().registerMethod(method);
+			this.hints.reflection().registerMethod(method, ExecutableMode.INVOKE);
 		}
 	}
 

spring-beans/src/main/java/org/springframework/beans/factory/aot/InstanceSupplierCodeGenerator.java

@@ -147,7 +147,7 @@ private CodeBlock generateCodeForInaccessibleConstructor(String beanName,
 			Class<?> beanClass, Constructor<?> constructor, boolean dependsOnBean) {
 
 		this.generationContext.getRuntimeHints().reflection()
-				.registerConstructor(constructor);
+				.registerConstructor(constructor, ExecutableMode.INVOKE);
 		GeneratedMethod generatedMethod = generateGetInstanceSupplierMethod(method -> {
 			method.addJavadoc("Get the bean instance supplier for '$L'.", beanName);
 			method.addModifiers(PRIVATE_STATIC);
@@ -240,7 +240,7 @@ private CodeBlock generateCodeForInaccessibleFactoryMethod(String beanName, Clas
 			Method factoryMethod, Class<?> declaringClass) {
 
 		this.generationContext.getRuntimeHints().reflection()
-				.registerMethod(factoryMethod);
+				.registerMethod(factoryMethod, ExecutableMode.INVOKE);
 		GeneratedMethod getInstanceMethod = generateGetInstanceSupplierMethod(method -> {
 			method.addJavadoc("Get the bean instance supplier for '$L'.", beanName);
 			method.addModifiers(PRIVATE_STATIC);

spring-core-test/src/test/java/org/springframework/aot/agent/InstrumentedMethodTests.java

@@ -194,7 +194,7 @@ void classGetConstructorsShouldNotMatchTypeReflectionHint() {
 
 		@Test
 		void classGetConstructorsShouldMatchConstructorReflectionHint() throws Exception {
-			hints.reflection().registerConstructor(String.class.getConstructor());
+			hints.reflection().registerConstructor(String.class.getConstructor(), ExecutableMode.INVOKE);
 			assertThatInvocationMatches(InstrumentedMethod.CLASS_GETCONSTRUCTORS, this.stringGetConstructors);
 		}
 
@@ -250,7 +250,7 @@ void classGetDeclaredConstructorsShouldNotMatchTypeReflectionHint() {
 
 		@Test
 		void classGetDeclaredConstructorsShouldMatchConstructorReflectionHint() throws Exception {
-			hints.reflection().registerConstructor(String.class.getConstructor());
+			hints.reflection().registerConstructor(String.class.getConstructor(), ExecutableMode.INVOKE);
 			assertThatInvocationMatches(InstrumentedMethod.CLASS_GETDECLAREDCONSTRUCTORS, this.stringGetDeclaredConstructors);
 		}
 
@@ -350,7 +350,7 @@ void classGetDeclaredMethodsShouldNotMatchTypeReflectionHint() {
 
 		@Test
 		void classGetDeclaredMethodsShouldMatchMethodReflectionHint() throws Exception {
-			hints.reflection().registerMethod(String.class.getMethod("toString"));
+			hints.reflection().registerMethod(String.class.getMethod("toString"), ExecutableMode.INVOKE);
 			assertThatInvocationMatches(InstrumentedMethod.CLASS_GETDECLAREDMETHODS, this.stringGetScaleMethod);
 		}
 
@@ -392,7 +392,7 @@ void classGetMethodsShouldNotMatchTypeReflectionHint() {
 
 		@Test
 		void classGetMethodsShouldMatchMethodReflectionHint() throws Exception {
-			hints.reflection().registerMethod(String.class.getMethod("toString"));
+			hints.reflection().registerMethod(String.class.getMethod("toString"), ExecutableMode.INVOKE);
 			assertThatInvocationMatches(InstrumentedMethod.CLASS_GETMETHODS, this.stringGetMethods);
 		}
 

spring-core/src/main/java/org/springframework/aot/hint/BindingReflectionHintsRegistrar.java

@@ -145,7 +145,7 @@ private void registerKotlinSerializationHints(ReflectionHints hints, Class<?> cl
 			Class<?> companionClass = ClassUtils.resolveClassName(companionClassName, null);
 			Method serializerMethod = ClassUtils.getMethodIfAvailable(companionClass, "serializer");
 			if (serializerMethod != null) {
-				hints.registerMethod(serializerMethod);
+				hints.registerMethod(serializerMethod, ExecutableMode.INVOKE);
 			}
 		}
 	}

spring-core/src/main/java/org/springframework/aot/hint/ReflectionHints.java

@@ -36,6 +36,8 @@
  * Gather the need for reflection at runtime.
  *
  * @author Stephane Nicoll
+ * @author Phillip Webb
+ * @author Andy Wilkinson
  * @since 6.0
  */
 public class ReflectionHints {
@@ -79,6 +81,7 @@ public TypeHint getTypeHint(Class<?> type) {
 	 * @param type the type to customize
 	 * @param typeHint a builder to further customize hints for that type
 	 * @return {@code this}, to facilitate method chaining
+	 * @see #registerType(TypeReference, MemberCategory...)
 	 */
 	public ReflectionHints registerType(TypeReference type, Consumer<TypeHint.Builder> typeHint) {
 		Builder builder = this.types.computeIfAbsent(type, TypeHint.Builder::new);
@@ -93,29 +96,30 @@ public ReflectionHints registerType(TypeReference type, Consumer<TypeHint.Builde
 	 * @param memberCategories the member categories to apply
 	 * @return {@code this}, to facilitate method chaining
 	 */
-	public ReflectionHints registerType(Class<?> type, MemberCategory... memberCategories) {
-		return registerType(TypeReference.of(type), memberCategories);
+	public ReflectionHints registerType(TypeReference type, MemberCategory... memberCategories) {
+		return registerType(type, TypeHint.builtWith(memberCategories));
 	}
 
 	/**
-	 * Register or customize reflection hints for the specified type
-	 * using the specified {@link MemberCategory MemberCategories}.
+	 * Register or customize reflection hints for the specified type.
 	 * @param type the type to customize
-	 * @param memberCategories the member categories to apply
+	 * @param typeHint a builder to further customize hints for that type
 	 * @return {@code this}, to facilitate method chaining
+	 * @see #registerType(Class, MemberCategory...)
 	 */
-	public ReflectionHints registerType(TypeReference type , MemberCategory... memberCategories) {
-		return registerType(type, TypeHint.builtWith(memberCategories));
+	public ReflectionHints registerType(Class<?> type, Consumer<TypeHint.Builder> typeHint) {
+		return registerType(TypeReference.of(type), typeHint);
 	}
 
 	/**
-	 * Register or customize reflection hints for the specified type.
+	 * Register or customize reflection hints for the specified type
+	 * using the specified {@link MemberCategory MemberCategories}.
 	 * @param type the type to customize
-	 * @param typeHint a builder to further customize hints for that type
+	 * @param memberCategories the member categories to apply
 	 * @return {@code this}, to facilitate method chaining
 	 */
-	public ReflectionHints registerType(Class<?> type, Consumer<TypeHint.Builder> typeHint) {
-		return registerType(TypeReference.of(type), typeHint);
+	public ReflectionHints registerType(Class<?> type, MemberCategory... memberCategories) {
+		return registerType(TypeReference.of(type), memberCategories);
 	}
 
 	/**
@@ -125,6 +129,7 @@ public ReflectionHints registerType(Class<?> type, Consumer<TypeHint.Builder> ty
 	 * @param typeName the type to customize
 	 * @param typeHint a builder to further customize hints for that type
 	 * @return {@code this}, to facilitate method chaining
+	 * @see #registerTypeIfPresent(ClassLoader, String, MemberCategory...)
 	 */
 	public ReflectionHints registerTypeIfPresent(@Nullable ClassLoader classLoader,
 			String typeName, Consumer<TypeHint.Builder> typeHint) {
@@ -134,6 +139,19 @@ public ReflectionHints registerTypeIfPresent(@Nullable ClassLoader classLoader,
 		return this;
 	}
 
+	/**
+	 * Register or customize reflection hints for the specified type if it
+	 * is available using the specified {@link ClassLoader}.
+	 * @param classLoader the classloader to use to check if the type is present
+	 * @param typeName the type to customize
+	 * @param memberCategories the member categories to apply
+	 * @return {@code this}, to facilitate method chaining
+	 */
+	public ReflectionHints registerTypeIfPresent(@Nullable ClassLoader classLoader,
+			String typeName, MemberCategory... memberCategories) {
+		return registerTypeIfPresent(classLoader, typeName, TypeHint.builtWith(memberCategories));
+	}
+
 	/**
 	 * Register or customize reflection hints for the types defined by the
 	 * specified list of {@link TypeReference type references}. The specified
@@ -162,7 +180,9 @@ public ReflectionHints registerField(Field field) {
 	 * enabling {@link ExecutableMode#INVOKE}.
 	 * @param constructor the constructor that requires reflection
 	 * @return {@code this}, to facilitate method chaining
+	 * @deprecated in favor of {@link #registerConstructor(Constructor, ExecutableMode)}
 	 */
+	@Deprecated
 	public ReflectionHints registerConstructor(Constructor<?> constructor) {
 		return registerConstructor(constructor, ExecutableMode.INVOKE);
 	}
@@ -175,16 +195,19 @@ public ReflectionHints registerConstructor(Constructor<?> constructor) {
 	 * @return {@code this}, to facilitate method chaining
 	 */
 	public ReflectionHints registerConstructor(Constructor<?> constructor, ExecutableMode mode) {
-		return registerConstructor(constructor, ExecutableHint.builtWith(mode));
+		return registerType(TypeReference.of(constructor.getDeclaringClass()),
+				typeHint -> typeHint.withConstructor(mapParameters(constructor), mode));
 	}
 
 	/**
 	 * Register the need for reflection on the specified {@link Constructor}.
 	 * @param constructor the constructor that requires reflection
 	 * @param constructorHint a builder to further customize the hints of this
 	 * constructor
-	 * @return {@code this}, to facilitate method chaining
+	 * @return {@code this}, to facilitate method chaining`
+	 * @deprecated in favor of {@link #registerConstructor(Constructor, ExecutableMode)}
 	 */
+	@Deprecated
 	public ReflectionHints registerConstructor(Constructor<?> constructor, Consumer<ExecutableHint.Builder> constructorHint) {
 		return registerType(TypeReference.of(constructor.getDeclaringClass()),
 				typeHint -> typeHint.withConstructor(mapParameters(constructor), constructorHint));
@@ -195,7 +218,9 @@ public ReflectionHints registerConstructor(Constructor<?> constructor, Consumer<
 	 * enabling {@link ExecutableMode#INVOKE}.
 	 * @param method the method that requires reflection
 	 * @return {@code this}, to facilitate method chaining
+	 * @deprecated in favor of {@link #registerMethod(Method, ExecutableMode)}
 	 */
+	@Deprecated
 	public ReflectionHints registerMethod(Method method) {
 		return registerMethod(method, ExecutableMode.INVOKE);
 	}
@@ -208,15 +233,18 @@ public ReflectionHints registerMethod(Method method) {
 	 * @return {@code this}, to facilitate method chaining
 	 */
 	public ReflectionHints registerMethod(Method method, ExecutableMode mode) {
-		return registerMethod(method, ExecutableHint.builtWith(mode));
+		return registerType(TypeReference.of(method.getDeclaringClass()),
+				typeHint -> typeHint.withMethod(method.getName(), mapParameters(method), mode));
 	}
 
 	/**
 	 * Register the need for reflection on the specified {@link Method}.
 	 * @param method the method that requires reflection
 	 * @param methodHint a builder to further customize the hints of this method
 	 * @return {@code this}, to facilitate method chaining
+	 * @deprecated in favor of {@link #registerMethod(Method, ExecutableMode)}
 	 */
+	@Deprecated
 	public ReflectionHints registerMethod(Method method, Consumer<ExecutableHint.Builder> methodHint) {
 		return registerType(TypeReference.of(method.getDeclaringClass()),
 				typeHint -> typeHint.withMethod(method.getName(), mapParameters(method), methodHint));

spring-core/src/main/java/org/springframework/aot/hint/TypeHint.java

@@ -35,6 +35,8 @@
  * A hint that describes the need for reflection on a type.
  *
  * @author Stephane Nicoll
+ * @author Phillip Webb
+ * @author Andy Wilkinson
  * @since 6.0
  */
 public final class TypeHint implements ConditionalHint {
@@ -199,7 +201,9 @@ public Builder withField(String name) {
 		 * parameter types, enabling {@link ExecutableMode#INVOKE}.
 		 * @param parameterTypes the parameter types of the constructor
 		 * @return {@code this}, to facilitate method chaining
+		 * @deprecated in favor of {@link #withConstructor(List, ExecutableMode)}
 		 */
+		@Deprecated
 		public Builder withConstructor(List<TypeReference> parameterTypes) {
 			return withConstructor(parameterTypes, ExecutableMode.INVOKE);
 		}
@@ -222,8 +226,11 @@ public Builder withConstructor(List<TypeReference> parameterTypes, ExecutableMod
 		 * @param constructorHint a builder to further customize the hints of this
 		 * constructor
 		 * @return {@code this}, to facilitate method chaining
+		 * @deprecated in favor of {@link #withConstructor(List, ExecutableMode)}
 		 */
-		public Builder withConstructor(List<TypeReference> parameterTypes, Consumer<ExecutableHint.Builder> constructorHint) {
+		@Deprecated
+		public Builder withConstructor(List<TypeReference> parameterTypes,
+				Consumer<ExecutableHint.Builder> constructorHint) {
 			ExecutableKey key = new ExecutableKey("<init>", parameterTypes);
 			ExecutableHint.Builder builder = this.constructors.computeIfAbsent(key,
 					k -> ExecutableHint.ofConstructor(parameterTypes));
@@ -237,7 +244,9 @@ public Builder withConstructor(List<TypeReference> parameterTypes, Consumer<Exec
 		 * @param name the name of the method
 		 * @param parameterTypes the parameter types of the constructor
 		 * @return {@code this}, to facilitate method chaining
+		 * @deprecated in favor of {@link #withMethod(String, List, ExecutableMode)}
 		 */
+		@Deprecated
 		public Builder withMethod(String name, List<TypeReference> parameterTypes) {
 			return withMethod(name, parameterTypes, ExecutableMode.INVOKE);
 		}
@@ -261,8 +270,11 @@ public Builder withMethod(String name, List<TypeReference> parameterTypes, Execu
 		 * @param parameterTypes the parameter types of the constructor
 		 * @param methodHint a builder to further customize the hints of this method
 		 * @return {@code this}, to facilitate method chaining
+		 * @deprecated in favor of {@link #withMethod(String, List, ExecutableMode)}
 		 */
-		public Builder withMethod(String name, List<TypeReference> parameterTypes, Consumer<ExecutableHint.Builder> methodHint) {
+		@Deprecated
+		public Builder withMethod(String name, List<TypeReference> parameterTypes,
+				Consumer<ExecutableHint.Builder> methodHint) {
 			ExecutableKey key = new ExecutableKey(name, parameterTypes);
 			ExecutableHint.Builder builder = this.methods.computeIfAbsent(key,
 					k -> ExecutableHint.ofMethod(name, parameterTypes));
@@ -274,6 +286,7 @@ public Builder withMethod(String name, List<TypeReference> parameterTypes, Consu
 		 * Adds the specified {@linkplain MemberCategory member categories}.
 		 * @param memberCategories the categories to apply
 		 * @return {@code this}, to facilitate method chaining
+		 * @see TypeHint#builtWith(MemberCategory...)
 		 */
 		public Builder withMembers(MemberCategory... memberCategories) {
 			this.memberCategories.addAll(Arrays.asList(memberCategories));

spring-core/src/main/java/org/springframework/aot/hint/annotation/SimpleReflectiveProcessor.java

@@ -21,6 +21,7 @@
 import java.lang.reflect.Field;
 import java.lang.reflect.Method;
 
+import org.springframework.aot.hint.ExecutableMode;
 import org.springframework.aot.hint.ReflectionHints;
 
 /**
@@ -64,7 +65,7 @@ protected void registerTypeHint(ReflectionHints hints, Class<?> type) {
 	 * @param constructor the constructor to process
 	 */
 	protected void registerConstructorHint(ReflectionHints hints, Constructor<?> constructor) {
-		hints.registerConstructor(constructor);
+		hints.registerConstructor(constructor, ExecutableMode.INVOKE);
 	}
 
 	/**
@@ -82,7 +83,7 @@ protected void registerFieldHint(ReflectionHints hints, Field field) {
 	 * @param method the method to process
 	 */
 	protected void registerMethodHint(ReflectionHints hints, Method method) {
-		hints.registerMethod(method);
+		hints.registerMethod(method, ExecutableMode.INVOKE);
 	}
 
 }