Polish

Author: snicoll

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

@@ -48,7 +48,7 @@ Java::
 ======
 
 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
+have, as well as its hierarchy. This typically allows nested test class to rely on the
 method to use in the root test class.
 
 [[spring-testing-annotation-beanoverriding-mockitobean]]
@@ -101,33 +101,34 @@ Java::
 The three annotations introduced above build upon the `@BeanOverride` meta-annotation
 and associated infrastructure, which allows to define custom bean overriding variants.
 
-In order to provide an extension, three classes are needed:
+To create an extension, the following is needed:
 
- - A concrete `BeanOverrideProcessor` implementation, `P`.
- - One or more concrete `OverrideMetadata` implementations created by said processor.
- - An annotation meta-annotated with `@BeanOverride(P.class)`.
+- An annotation meta-annotated with `@BeanOverride` that defines the
+`BeanOverrideProcessor` to use.
+- The `BeanOverrideProcessor` implementation itself.
+- One or more concrete `OverrideMetadata` implementations provided by the processor.
 
 The Spring TestContext Framework includes infrastructure classes that support bean
-overriding: a `BeanFactoryPostProcessor`, a `TestExecutionListener` and a `ContextCustomizerFactory`.
+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`.
+instantiating the relevant `BeanOverrideProcessor` in order to register an
+`OverrideMetadata`.
 
 Then the `BeanOverrideBeanFactoryPostProcessor` will use that information to alter the
-Context, registering and replacing bean definitions as influenced by each metadata
+context, registering and replacing bean definitions as defined 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 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.
+ - `REPLACE_DEFINITION`: replaces the bean definition. If it is not present in the
+context, an exception is thrown.
+ - `CREATE_OR_REPLACE_DEFINITION`: replaces the bean definition if the bean definition
+does not exist, or create one if it is not.
+ - `WRAP_BEAN`: get the original instance early so that it can be wrapped.
+
+NOTE: The Bean Overriding infrastructure does not include any bean resolution step,
+unlike an `@Autowired`-annotated field for instance. As such, the name of the bean to
+override must be somehow provided to or computed by the `BeanOverrideProcessor`.
+Typically, the user provides the name one way or the other.

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

@@ -22,15 +22,13 @@
 import java.lang.annotation.Target;
 
 /**
- * Mark an annotation as eligible for Bean Override parsing.
+ * Mark an annotation as eligible for Bean Override processing.
  *
- * <p>This meta-annotation specifies a {@link BeanOverrideProcessor} class which
- * must be capable of handling the composed annotation that is meta-annotated
- * with {@code @BeanOverride}.
+ * <p>Specifying this annotation triggers the defined  {@link BeanOverrideProcessor}
+ * which must be capable of handling the composed annotation and its attributes.
  *
- * <p>The composed annotation that is meta-annotated with {@code @BeanOverride}
- * must have a {@code RetentionPolicy} of {@link RetentionPolicy#RUNTIME RUNTIME}
- * and a {@code Target} of {@link ElementType#FIELD FIELD}.
+ * <p>The composed annotation is meant to be detected on fields only so it is
+ * expected that it has a {@code Target} of {@link ElementType#FIELD FIELD}.
  *
  * @author Simon Baslé
  * @since 6.2
@@ -41,8 +39,8 @@
 public @interface BeanOverride {
 
 	/**
-	 * A {@link BeanOverrideProcessor} implementation class by which the composed
-	 * annotation should be processed.
+	 * The {@link BeanOverrideProcessor} implementation to trigger against
+	 * the composed annotation.
 	 */
 	Class<? extends BeanOverrideProcessor> value();
 

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

@@ -22,31 +22,26 @@
 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.BeanFactory;
 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.
+ * and adapt the {@link BeanFactory} 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
@@ -66,10 +61,6 @@
  */
 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;
 
@@ -94,14 +85,16 @@ public int getOrder() {
 
 	@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);
+		if (!(beanFactory instanceof BeanDefinitionRegistry registry)) {
+			throw new IllegalStateException("Cannot process bean override with a BeanFactory " +
+					"that doesn't implement BeanDefinitionRegistry: " + beanFactory.getClass());
+		}
+		postProcessWithRegistry(beanFactory, registry);
 	}
 
-	private void postProcessWithRegistry(DefaultListableBeanFactory registry) {
+	private void postProcessWithRegistry(ConfigurableListableBeanFactory beanFactory, BeanDefinitionRegistry registry) {
 		for (OverrideMetadata metadata : this.overrideRegistrar.getOverrideMetadata()) {
-			registerBeanOverride(registry, metadata);
+			registerBeanOverride(beanFactory, registry, metadata);
 		}
 	}
 
@@ -116,15 +109,20 @@ protected void copyBeanDefinitionDetails(BeanDefinition from, RootBeanDefinition
 		to.setScope(from.getScope());
 	}
 
-	private void registerBeanOverride(DefaultListableBeanFactory beanFactory, OverrideMetadata overrideMetadata) {
+	private void registerBeanOverride(ConfigurableListableBeanFactory beanFactory, BeanDefinitionRegistry registry,
+			OverrideMetadata overrideMetadata) {
+
 		switch (overrideMetadata.getStrategy()) {
-			case REPLACE_DEFINITION -> registerReplaceDefinition(beanFactory, overrideMetadata, true);
-			case REPLACE_OR_CREATE_DEFINITION -> registerReplaceDefinition(beanFactory, overrideMetadata, false);
+			case REPLACE_DEFINITION ->
+					registerReplaceDefinition(beanFactory, registry, overrideMetadata, true);
+			case REPLACE_OR_CREATE_DEFINITION ->
+					registerReplaceDefinition(beanFactory, registry, overrideMetadata, false);
 			case WRAP_BEAN -> registerWrapBean(beanFactory, overrideMetadata);
 		}
 	}
 
-	private void registerReplaceDefinition(DefaultListableBeanFactory beanFactory, OverrideMetadata overrideMetadata, boolean enforceExistingDefinition) {
+	private void registerReplaceDefinition(ConfigurableListableBeanFactory beanFactory, BeanDefinitionRegistry registry,
+			OverrideMetadata overrideMetadata, boolean enforceExistingDefinition) {
 
 		RootBeanDefinition beanDefinition = createBeanDefinition(overrideMetadata);
 		String beanName = overrideMetadata.getBeanName();
@@ -133,13 +131,13 @@ private void registerReplaceDefinition(DefaultListableBeanFactory beanFactory, O
 		if (beanFactory.containsBeanDefinition(beanName)) {
 			existingBeanDefinition = beanFactory.getBeanDefinition(beanName);
 			copyBeanDefinitionDetails(existingBeanDefinition, beanDefinition);
-			beanFactory.removeBeanDefinition(beanName);
+			registry.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);
+		registry.registerBeanDefinition(beanName, beanDefinition);
 
 		Object override = overrideMetadata.createOverride(beanName, existingBeanDefinition, null);
 		if (beanFactory.isSingleton(beanName)) {
@@ -160,7 +158,7 @@ else if (enforceExistingDefinition) {
 	 * upon creation, during the {@link WrapEarlyBeanPostProcessor#getEarlyBeanReference(Object, String)}
 	 * phase.
 	 */
-	private void registerWrapBean(DefaultListableBeanFactory beanFactory, OverrideMetadata metadata) {
+	private void registerWrapBean(ConfigurableListableBeanFactory beanFactory, OverrideMetadata metadata) {
 		Set<String> existingBeanNames = getExistingBeanNames(beanFactory, metadata.getBeanType());
 		String beanName = metadata.getBeanName();
 		if (!existingBeanNames.contains(beanName)) {
@@ -177,7 +175,7 @@ private RootBeanDefinition createBeanDefinition(OverrideMetadata metadata) {
 		return definition;
 	}
 
-	private Set<String> getExistingBeanNames(DefaultListableBeanFactory beanFactory, ResolvableType resolvableType) {
+	private Set<String> getExistingBeanNames(ConfigurableListableBeanFactory beanFactory, ResolvableType resolvableType) {
 		Set<String> beans = new LinkedHashSet<>(
 				Arrays.asList(beanFactory.getBeanNamesForType(resolvableType, true, false)));
 		Class<?> type = resolvableType.resolve(Object.class);
@@ -193,39 +191,6 @@ private Set<String> getExistingBeanNames(DefaultListableBeanFactory beanFactory,
 		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 {

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

@@ -0,0 +1,105 @@
+/*
+ * 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.util.Set;
+import java.util.function.Consumer;
+
+import org.springframework.beans.factory.config.BeanDefinition;
+import org.springframework.beans.factory.config.ConstructorArgumentValues;
+import org.springframework.beans.factory.config.RuntimeBeanReference;
+import org.springframework.beans.factory.support.BeanDefinitionRegistry;
+import org.springframework.beans.factory.support.RootBeanDefinition;
+import org.springframework.context.ConfigurableApplicationContext;
+import org.springframework.test.context.ContextCustomizer;
+import org.springframework.test.context.MergedContextConfiguration;
+import org.springframework.test.context.bean.override.BeanOverrideBeanFactoryPostProcessor.WrapEarlyBeanPostProcessor;
+
+/**
+ * {@link ContextCustomizer} implementation that registers the necessary
+ * infrastructure to support {@linkplain BeanOverride bean overriding}.
+ *
+ * @author Simon Baslé
+ * @author Stephane Nicoll
+ * @since 6.2
+ */
+class BeanOverrideContextCustomizer implements ContextCustomizer {
+
+	private static final String REGISTRAR_BEAN_NAME =
+			"org.springframework.test.context.bean.override.internalBeanOverrideRegistrar";
+
+	private static final String INFRASTRUCTURE_BEAN_NAME =
+			"org.springframework.test.context.bean.override.internalBeanOverridePostProcessor";
+
+	private static final String EARLY_INFRASTRUCTURE_BEAN_NAME =
+			"org.springframework.test.context.bean.override.internalWrapEarlyBeanPostProcessor";
+
+
+	private final Set<Class<?>> detectedClasses;
+
+	BeanOverrideContextCustomizer(Set<Class<?>> detectedClasses) {
+		this.detectedClasses = detectedClasses;
+	}
+
+	static void registerInfrastructure(BeanDefinitionRegistry registry, Set<Class<?>> detectedClasses) {
+		addInfrastructureBeanDefinition(registry, BeanOverrideRegistrar.class, REGISTRAR_BEAN_NAME,
+				constructorArgs -> constructorArgs.addIndexedArgumentValue(0, detectedClasses));
+		RuntimeBeanReference registrarReference = new RuntimeBeanReference(REGISTRAR_BEAN_NAME);
+		addInfrastructureBeanDefinition(
+				registry, WrapEarlyBeanPostProcessor.class, EARLY_INFRASTRUCTURE_BEAN_NAME,
+				constructorArgs -> constructorArgs.addIndexedArgumentValue(0, registrarReference));
+		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);
+		}
+	}
+
+	@Override
+	public void customizeContext(ConfigurableApplicationContext context, MergedContextConfiguration mergedConfig) {
+		if (context instanceof BeanDefinitionRegistry registry) {
+			registerInfrastructure(registry, this.detectedClasses);
+		}
+	}
+
+	@Override
+	public boolean equals(Object obj) {
+		if (obj == this) {
+			return true;
+		}
+		if (obj == null || obj.getClass() != getClass()) {
+			return false;
+		}
+		BeanOverrideContextCustomizer other = (BeanOverrideContextCustomizer) obj;
+		return this.detectedClasses.equals(other.detectedClasses);
+	}
+
+	@Override
+	public int hashCode() {
+		return this.detectedClasses.hashCode();
+	}
+
+}