Improve Bean Overriding support, testing and documentation

This commit improves on the bean overriding feature in several ways:
the API is simplified and polished (metadata and processor contracts,
 etc...).

The commit also reworks infrastructure classes (context customizer,
test execution listener, BeanOverrideBeanFactoryPostProcessor, etc...).
Parsing of annotations is now fully stateless.

In order to avoid OverrideMetadata in bean definition and to make a
first step towards AOT support, the BeanOverrideBeanFactoryPostProcessor
now delegates to a BeanOverrideRegistrar to track classes to parse,
the metadata-related state as well as for the field injection methods
for tests.

Lastly, this commit increases the test coverage for the provided
annotations and adds integration tests and fixes a few `@TestBean`
issues.

Author: simonbasle

framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-beanoverriding.adoc

@@ -47,6 +47,9 @@ Java::
 <2> The result of this static method will be used as the instance and injected into the field
 ======
 
+NOTE: The method to invoke is searched in the test class and any enclosing class it might
+have, as well as its hierarchy. This typically allows nested test class to provide the
+method to use in the root test class.
 
 [[spring-testing-annotation-beanoverriding-mockitobean]]
 == `@MockitoBean` and `@MockitoSpyBean`
@@ -100,32 +103,31 @@ and associated infrastructure, which allows to define custom bean overriding var
 
 In order to provide an extension, three classes are needed:
 
- - A concrete `BeanOverrideProcessor<P>`.
- - A concrete `OverrideMetadata` created by said processor.
+ - A concrete `BeanOverrideProcessor` implementation, `P`.
+ - One or more concrete `OverrideMetadata` implementations created by said processor.
  - An annotation meta-annotated with `@BeanOverride(P.class)`.
 
 The Spring TestContext Framework includes infrastructure classes that support bean
-overriding: a `BeanPostProcessor`, a `TestExecutionListener` and a `ContextCustomizerFactory`.
-These are automatically registered via the Spring TestContext Framework `spring.factories`
-file.
+overriding: a `BeanFactoryPostProcessor`, a `TestExecutionListener` and a `ContextCustomizerFactory`.
+The later two are automatically registered via the Spring TestContext Framework
+`spring.factories` file, and are responsible for setting up the rest of the infrastructure.
 
 The test classes are parsed looking for any field meta-annotated with `@BeanOverride`,
 instantiating the relevant `BeanOverrideProcessor` in order to register an `OverrideMetadata`.
 
-Then the `BeanOverrideBeanPostProcessor` will use that information to alter the Context,
-registering and replacing bean definitions as influenced by each metadata
+Then the `BeanOverrideBeanFactoryPostProcessor` will use that information to alter the
+Context, registering and replacing bean definitions as influenced by each metadata
 `BeanOverrideStrategy`:
 
  - `REPLACE_DEFINITION`: the bean post-processor replaces the bean definition.
 If it is not present in the context, an exception is thrown.
  - `CREATE_OR_REPLACE_DEFINITION`: same as above but if the bean definition is not present
 in the context, one is created
- - `WRAP_EARLY_BEAN`: an original instance is obtained via
-`SmartInstantiationAwareBeanPostProcessor#getEarlyBeanReference(Object, String)` and
-provided to the processor during `OverrideMetadata` creation.
-
-NOTE: The Bean Overriding infrastructure works best with singleton beans. It also doesn't
-include any bean resolution (unlike e.g. an `@Autowired`-annotated field). As such, the
-name of the bean to override MUST be somehow provided to or computed by the
-`BeanOverrideProcessor`. Typically, the end user provides the name as part of the custom
-annotation's attributes, or the annotated field's name.
+ - `WRAP_EARLY_BEAN`: an original instance is obtained and passed to the `OverrideMetadata`
+when the override instance is created.
+
+NOTE: The Bean Overriding infrastructure doesn't include any bean resolution step
+(unlike e.g. an `@Autowired`-annotated field). As such, the name of the bean to override
+MUST be somehow provided to or computed by the `BeanOverrideProcessor`. Typically, the end
+user provides the name as part of the custom annotation's attributes, or the annotated
+field's name.

spring-test/src/main/java/org/springframework/test/context/bean/override/BeanOverride.java

@@ -34,7 +34,7 @@
  *
  * @author Simon Baslé
  * @since 6.2
- * @see BeanOverrideBeanPostProcessor
+ * @see BeanOverrideBeanFactoryPostProcessor
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.ANNOTATION_TYPE)

spring-test/src/main/java/org/springframework/test/context/bean/override/BeanOverrideBeanFactoryPostProcessor.java

@@ -0,0 +1,275 @@
+/*
+ * 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.test.context.bean.override;
+
+import java.lang.reflect.Field;
+import java.util.Arrays;
+import java.util.LinkedHashSet;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.function.Consumer;
+
+import org.springframework.aop.scope.ScopedProxyUtils;
+import org.springframework.beans.BeansException;
+import org.springframework.beans.factory.BeanFactoryUtils;
+import org.springframework.beans.factory.FactoryBean;
+import org.springframework.beans.factory.config.BeanDefinition;
+import org.springframework.beans.factory.config.BeanFactoryPostProcessor;
+import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
+import org.springframework.beans.factory.config.ConstructorArgumentValues;
+import org.springframework.beans.factory.config.RuntimeBeanReference;
+import org.springframework.beans.factory.config.SmartInstantiationAwareBeanPostProcessor;
+import org.springframework.beans.factory.support.BeanDefinitionRegistry;
+import org.springframework.beans.factory.support.DefaultListableBeanFactory;
+import org.springframework.beans.factory.support.RootBeanDefinition;
+import org.springframework.core.Ordered;
+import org.springframework.core.PriorityOrdered;
+import org.springframework.core.ResolvableType;
+import org.springframework.util.Assert;
+import org.springframework.util.StringUtils;
+
+/**
+ * A {@link BeanFactoryPostProcessor} implementation that processes test classes
+ * and adapt the {@link BeanDefinitionRegistry} for any {@link BeanOverride} it
+ * may define.
+ *
+ * <p>A set of classes from which to parse {@link OverrideMetadata} must be
+ * provided to this processor. Each test class is expected to use any
+ * annotation meta-annotated with {@link BeanOverride @BeanOverride} to mark
+ * beans to override. The {@link BeanOverrideParsingUtils#hasBeanOverride(Class)}
+ * method can be used to check if a class matches the above criteria.
+ *
+ * <p>The provided classes are fully parsed at creation to build a metadata set.
+ * This processor implements several {@link BeanOverrideStrategy overriding
+ * strategy} and chooses the correct one according to each override metadata
+ * {@link OverrideMetadata#getStrategy()} method. Additionally, it provides
+ * support for injecting the overridden bean instances into their corresponding
+ * annotated {@link Field fields}.
+ *
+ * @author Simon Baslé
+ * @since 6.2
+ */
+class BeanOverrideBeanFactoryPostProcessor implements BeanFactoryPostProcessor, Ordered {
+
+	private static final String INFRASTRUCTURE_BEAN_NAME = BeanOverrideBeanFactoryPostProcessor.class.getName();
+
+	private static final String EARLY_INFRASTRUCTURE_BEAN_NAME =
+			BeanOverrideBeanFactoryPostProcessor.WrapEarlyBeanPostProcessor.class.getName();
+
+	private final BeanOverrideRegistrar overrideRegistrar;
+
+
+	/**
+	 * Create a new {@code BeanOverrideBeanFactoryPostProcessor} instance with
+	 * the given {@link BeanOverrideRegistrar}, which contains a set of parsed
+	 * {@link OverrideMetadata}.
+	 * @param overrideRegistrar the {@link BeanOverrideRegistrar} used to track
+	 * metadata
+	 */
+	public BeanOverrideBeanFactoryPostProcessor(BeanOverrideRegistrar overrideRegistrar) {
+		this.overrideRegistrar = overrideRegistrar;
+	}
+
+
+	@Override
+	public int getOrder() {
+		return Ordered.LOWEST_PRECEDENCE - 10;
+	}
+
+
+	@Override
+	public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {
+		Assert.isInstanceOf(DefaultListableBeanFactory.class, beanFactory,
+				"Bean overriding annotations can only be used on a DefaultListableBeanFactory");
+		postProcessWithRegistry((DefaultListableBeanFactory) beanFactory);
+	}
+
+	private void postProcessWithRegistry(DefaultListableBeanFactory registry) {
+		for (OverrideMetadata metadata : this.overrideRegistrar.getOverrideMetadata()) {
+			registerBeanOverride(registry, metadata);
+		}
+	}
+
+	/**
+	 * Copy certain details of a {@link BeanDefinition} to the definition created by
+	 * this processor for a given {@link OverrideMetadata}.
+	 * <p>The default implementation copies the {@linkplain BeanDefinition#isPrimary()
+	 * primary flag} and the {@linkplain BeanDefinition#getScope() scope}.
+	 */
+	protected void copyBeanDefinitionDetails(BeanDefinition from, RootBeanDefinition to) {
+		to.setPrimary(from.isPrimary());
+		to.setScope(from.getScope());
+	}
+
+	private void registerBeanOverride(DefaultListableBeanFactory beanFactory, OverrideMetadata overrideMetadata) {
+		switch (overrideMetadata.getStrategy()) {
+			case REPLACE_DEFINITION -> registerReplaceDefinition(beanFactory, overrideMetadata, true);
+			case REPLACE_OR_CREATE_DEFINITION -> registerReplaceDefinition(beanFactory, overrideMetadata, false);
+			case WRAP_BEAN -> registerWrapBean(beanFactory, overrideMetadata);
+		}
+	}
+
+	private void registerReplaceDefinition(DefaultListableBeanFactory beanFactory, OverrideMetadata overrideMetadata, boolean enforceExistingDefinition) {
+
+		RootBeanDefinition beanDefinition = createBeanDefinition(overrideMetadata);
+		String beanName = overrideMetadata.getBeanName();
+
+		BeanDefinition existingBeanDefinition = null;
+		if (beanFactory.containsBeanDefinition(beanName)) {
+			existingBeanDefinition = beanFactory.getBeanDefinition(beanName);
+			copyBeanDefinitionDetails(existingBeanDefinition, beanDefinition);
+			beanFactory.removeBeanDefinition(beanName);
+		}
+		else if (enforceExistingDefinition) {
+			throw new IllegalStateException("Unable to override bean '" + beanName + "'; there is no" +
+					" bean definition to replace with that name");
+		}
+		beanFactory.registerBeanDefinition(beanName, beanDefinition);
+
+		Object override = overrideMetadata.createOverride(beanName, existingBeanDefinition, null);
+		if (beanFactory.isSingleton(beanName)) {
+			// Now we have an instance (the override) that we can register.
+			// At this stage we don't expect a singleton instance to be present,
+			// and this call will throw if there is such an instance already.
+			beanFactory.registerSingleton(beanName, override);
+		}
+
+		overrideMetadata.track(override, beanFactory);
+		this.overrideRegistrar.registerNameForMetadata(overrideMetadata, beanName);
+	}
+
+	/**
+	 * Check that the expected bean name is registered and matches the type to override.
+	 * <p>If so, put the override metadata in the early tracking map.
+	 * <p>The map will later be checked to see if a given bean should be wrapped
+	 * upon creation, during the {@link WrapEarlyBeanPostProcessor#getEarlyBeanReference(Object, String)}
+	 * phase.
+	 */
+	private void registerWrapBean(DefaultListableBeanFactory beanFactory, OverrideMetadata metadata) {
+		Set<String> existingBeanNames = getExistingBeanNames(beanFactory, metadata.getBeanType());
+		String beanName = metadata.getBeanName();
+		if (!existingBeanNames.contains(beanName)) {
+			throw new IllegalStateException("Unable to override bean '" + beanName + "' by wrapping," +
+					" no existing bean instance by this name of type " + metadata.getBeanType());
+		}
+		this.overrideRegistrar.markWrapEarly(metadata, beanName);
+		this.overrideRegistrar.registerNameForMetadata(metadata, beanName);
+	}
+
+	private RootBeanDefinition createBeanDefinition(OverrideMetadata metadata) {
+		RootBeanDefinition definition = new RootBeanDefinition();
+		definition.setTargetType(metadata.getBeanType());
+		return definition;
+	}
+
+	private Set<String> getExistingBeanNames(DefaultListableBeanFactory beanFactory, ResolvableType resolvableType) {
+		Set<String> beans = new LinkedHashSet<>(
+				Arrays.asList(beanFactory.getBeanNamesForType(resolvableType, true, false)));
+		Class<?> type = resolvableType.resolve(Object.class);
+		for (String beanName : beanFactory.getBeanNamesForType(FactoryBean.class, true, false)) {
+			beanName = BeanFactoryUtils.transformedBeanName(beanName);
+			BeanDefinition beanDefinition = beanFactory.getBeanDefinition(beanName);
+			Object attribute = beanDefinition.getAttribute(FactoryBean.OBJECT_TYPE_ATTRIBUTE);
+			if (resolvableType.equals(attribute) || type.equals(attribute)) {
+				beans.add(beanName);
+			}
+		}
+		beans.removeIf(ScopedProxyUtils::isScopedTarget);
+		return beans;
+	}
+
+	/**
+	 * Register a {@link BeanOverrideBeanFactoryPostProcessor} with a {@link BeanDefinitionRegistry}.
+	 * <p>Not required when using the Spring TestContext Framework, as registration
+	 * is automatic via the
+	 * {@link org.springframework.core.io.support.SpringFactoriesLoader SpringFactoriesLoader}
+	 * mechanism.
+	 * @param registry the bean definition registry
+	 */
+	public static void register(BeanDefinitionRegistry registry) {
+		RuntimeBeanReference registrarReference = new RuntimeBeanReference(BeanOverrideRegistrar.INFRASTRUCTURE_BEAN_NAME);
+		// Early processor
+		addInfrastructureBeanDefinition(
+				registry, WrapEarlyBeanPostProcessor.class, EARLY_INFRASTRUCTURE_BEAN_NAME, constructorArgs ->
+					constructorArgs.addIndexedArgumentValue(0, registrarReference));
+
+		// Main processor
+		addInfrastructureBeanDefinition(
+				registry, BeanOverrideBeanFactoryPostProcessor.class, INFRASTRUCTURE_BEAN_NAME, constructorArgs ->
+						constructorArgs.addIndexedArgumentValue(0, registrarReference));
+	}
+
+	private static void addInfrastructureBeanDefinition(BeanDefinitionRegistry registry,
+			Class<?> clazz, String beanName, Consumer<ConstructorArgumentValues> constructorArgumentsConsumer) {
+
+		if (!registry.containsBeanDefinition(beanName)) {
+			RootBeanDefinition definition = new RootBeanDefinition(clazz);
+			definition.setRole(BeanDefinition.ROLE_INFRASTRUCTURE);
+			ConstructorArgumentValues constructorArguments = definition.getConstructorArgumentValues();
+			constructorArgumentsConsumer.accept(constructorArguments);
+			registry.registerBeanDefinition(beanName, definition);
+		}
+	}
+
+
+	static final class WrapEarlyBeanPostProcessor implements SmartInstantiationAwareBeanPostProcessor,
+			PriorityOrdered {
+
+		private final BeanOverrideRegistrar overrideRegistrar;
+
+		private final Map<String, Object> earlyReferences;
+
+
+		private WrapEarlyBeanPostProcessor(BeanOverrideRegistrar registrar) {
+			this.overrideRegistrar = registrar;
+			this.earlyReferences = new ConcurrentHashMap<>(16);
+		}
+
+
+		@Override
+		public int getOrder() {
+			return Ordered.HIGHEST_PRECEDENCE;
+		}
+
+		@Override
+		public Object getEarlyBeanReference(Object bean, String beanName) throws BeansException {
+			if (bean instanceof FactoryBean) {
+				return bean;
+			}
+			this.earlyReferences.put(getCacheKey(bean, beanName), bean);
+			return this.overrideRegistrar.wrapIfNecessary(bean, beanName);
+		}
+
+		@Override
+		public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
+			if (bean instanceof FactoryBean) {
+				return bean;
+			}
+			if (this.earlyReferences.remove(getCacheKey(bean, beanName)) != bean) {
+				return this.overrideRegistrar.wrapIfNecessary(bean, beanName);
+			}
+			return bean;
+		}
+
+		private String getCacheKey(Object bean, String beanName) {
+			return (StringUtils.hasLength(beanName) ? beanName : bean.getClass().getName());
+		}
+
+	}
+
+}