Support import of idomatic testcontainer declaration classes

Add an `@ImportTestcontainers` annotation which can be used to import
idomatic testcontainer declaration classes.

Closes gh-35245

spring-boot-project/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/beans/TestcontainerBeanDefinition.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2012-2023 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.boot.testcontainers.beans;
+
+import org.springframework.beans.factory.config.BeanDefinition;
+import org.springframework.core.annotation.MergedAnnotations;
+
+/**
+ * Extended {@link org.springframework.beans.factory.config.BeanDefinition} interface used
+ * to register testcontainer beans.
+ *
+ * @author Phillip Webb
+ * @since 3.1.0
+ */
+public interface TestcontainerBeanDefinition extends BeanDefinition {
+
+	/**
+	 * Return the container image name or {@code null} if the image name is not yet known.
+	 * @return the container image name
+	 */
+	String getContainerImageName();
+
+	/**
+	 * Return any annotations declared alongside the container.
+	 * @return annotations declared with the container
+	 */
+	MergedAnnotations getAnnotations();
+
+}

spring-boot-project/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/beans/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2012-2023 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.
+ */
+
+/**
+ * Spring bean support classes for Testcontainers.
+ */
+package org.springframework.boot.testcontainers.beans;

spring-boot-project/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/context/ContainerFieldsImporter.java

@@ -0,0 +1,76 @@
+/*
+ * Copyright 2012-2023 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.boot.testcontainers.context;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Modifier;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.testcontainers.containers.Container;
+
+import org.springframework.beans.factory.support.BeanDefinitionRegistry;
+import org.springframework.beans.factory.support.BeanNameGenerator;
+import org.springframework.util.Assert;
+import org.springframework.util.ReflectionUtils;
+
+/**
+ * Used by {@link ImportTestcontainersRegistrar} to import {@link Container} fields.
+ *
+ * @author Phillip Webb
+ */
+class ContainerFieldsImporter {
+
+	void registerBeanDefinitions(BeanDefinitionRegistry registry, BeanNameGenerator importBeanNameGenerator,
+			Class<?> definitionClass) {
+		for (Field field : getContainerFields(definitionClass)) {
+			assertValid(field);
+			Container<?> container = getContainer(field);
+			registerBeanDefinition(registry, importBeanNameGenerator, field, container);
+		}
+	}
+
+	private List<Field> getContainerFields(Class<?> containersClass) {
+		List<Field> containerFields = new ArrayList<>();
+		ReflectionUtils.doWithFields(containersClass, containerFields::add, this::isContainerField);
+		return List.copyOf(containerFields);
+	}
+
+	private boolean isContainerField(Field candidate) {
+		return Container.class.isAssignableFrom(candidate.getType());
+	}
+
+	private void assertValid(Field field) {
+		Assert.state(Modifier.isStatic(field.getModifiers()),
+				() -> "Container field '" + field.getName() + "' must be static");
+	}
+
+	private Container<?> getContainer(Field field) {
+		ReflectionUtils.makeAccessible(field);
+		Container<?> container = (Container<?>) ReflectionUtils.getField(field, null);
+		Assert.state(container != null, () -> "Container field '" + field.getName() + "' must not have a null value");
+		return container;
+	}
+
+	private void registerBeanDefinition(BeanDefinitionRegistry registry, BeanNameGenerator importBeanNameGenerator,
+			Field field, Container<?> container) {
+		TestcontainerFieldBeanDefinition beanDefinition = new TestcontainerFieldBeanDefinition(field, container);
+		String beanName = importBeanNameGenerator.generateBeanName(beanDefinition, registry);
+		registry.registerBeanDefinition(beanName, beanDefinition);
+	}
+
+}

spring-boot-project/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/context/DynamicPropertySourceMethodsImporter.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2012-2023 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.boot.testcontainers.context;
+
+import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
+import java.util.Set;
+
+import org.springframework.boot.testcontainers.properties.TestcontainersPropertySource;
+import org.springframework.core.MethodIntrospector;
+import org.springframework.core.annotation.MergedAnnotations;
+import org.springframework.core.env.Environment;
+import org.springframework.test.context.DynamicPropertyRegistry;
+import org.springframework.test.context.DynamicPropertySource;
+import org.springframework.util.Assert;
+import org.springframework.util.ReflectionUtils;
+
+/**
+ * Used by {@link ImportTestcontainersRegistrar} to import
+ * {@link DynamicPropertySource @DynamicPropertySource} methods.
+ *
+ * @author Phillip Webb
+ */
+class DynamicPropertySourceMethodsImporter {
+
+	private final Environment environment;
+
+	DynamicPropertySourceMethodsImporter(Environment environment) {
+		this.environment = environment;
+	}
+
+	void registerDynamicPropertySources(Class<?> definitionClass) {
+		Set<Method> methods = MethodIntrospector.selectMethods(definitionClass, this::isAnnotated);
+		if (methods.isEmpty()) {
+			return;
+		}
+		DynamicPropertyRegistry registry = TestcontainersPropertySource.attach(this.environment);
+		methods.forEach((method) -> {
+			assertValid(method);
+			ReflectionUtils.makeAccessible(method);
+			ReflectionUtils.invokeMethod(method, null, registry);
+		});
+	}
+
+	private boolean isAnnotated(Method method) {
+		return MergedAnnotations.from(method).isPresent(DynamicPropertySource.class);
+	}
+
+	private void assertValid(Method method) {
+		Assert.state(Modifier.isStatic(method.getModifiers()),
+				() -> "@DynamicPropertySource method '" + method.getName() + "' must be static");
+		Class<?>[] types = method.getParameterTypes();
+		Assert.state(types.length == 1 && types[0] == DynamicPropertyRegistry.class,
+				() -> "@DynamicPropertySource method '" + method.getName()
+						+ "' must accept a single DynamicPropertyRegistry argument");
+	}
+
+}

spring-boot-project/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/context/ImportTestcontainers.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2012-2023 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.boot.testcontainers.context;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.testcontainers.containers.Container;
+
+import org.springframework.context.ApplicationContext;
+import org.springframework.context.annotation.Import;
+
+/**
+ * Imports idiomatic Testcontainer declaration classes into the Spring
+ * {@link ApplicationContext}. The following elements will be considered from the imported
+ * classes:
+ * <ul>
+ * <li>All static fields that declare {@link Container} values.</li>
+ * <li>All {@code @DynamicPropertySource} annotated methods.</li>
+ * </ul>
+ *
+ * @author Phillip Webb
+ * @since 3.1.0
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Import(ImportTestcontainersRegistrar.class)
+public @interface ImportTestcontainers {
+
+	/**
+	 * The declaration classes to import. If no {@code value} is defined then the class
+	 * that declares the {@link ImportTestcontainers @ImportTestcontainers} annotation
+	 * will be searched.
+	 * @return the definition classes to import
+	 */
+	Class<?>[] value() default {};
+
+}

spring-boot-project/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/context/ImportTestcontainersRegistrar.java

@@ -0,0 +1,73 @@
+/*
+ * Copyright 2012-2023 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.boot.testcontainers.context;
+
+import org.springframework.beans.factory.support.BeanDefinitionRegistry;
+import org.springframework.beans.factory.support.BeanNameGenerator;
+import org.springframework.context.annotation.ImportBeanDefinitionRegistrar;
+import org.springframework.core.annotation.MergedAnnotation;
+import org.springframework.core.env.Environment;
+import org.springframework.core.type.AnnotationMetadata;
+import org.springframework.util.ClassUtils;
+import org.springframework.util.ObjectUtils;
+
+/**
+ * {@link ImportBeanDefinitionRegistrar} for
+ * {@link ImportTestcontainers @ImportTestcontainers}.
+ *
+ * @author Phillip Webb
+ * @see ContainerFieldsImporter
+ * @see DynamicPropertySourceMethodsImporter
+ */
+class ImportTestcontainersRegistrar implements ImportBeanDefinitionRegistrar {
+
+	private static final String DYNAMIC_PROPERTY_SOURCE_CLASS = "org.springframework.test.context.DynamicPropertySource";
+
+	private final ContainerFieldsImporter containerFieldsImporter;
+
+	private final DynamicPropertySourceMethodsImporter dynamicPropertySourceMethodsImporter;
+
+	ImportTestcontainersRegistrar(Environment environment) {
+		this.containerFieldsImporter = new ContainerFieldsImporter();
+		this.dynamicPropertySourceMethodsImporter = (!ClassUtils.isPresent(DYNAMIC_PROPERTY_SOURCE_CLASS, null)) ? null
+				: new DynamicPropertySourceMethodsImporter(environment);
+	}
+
+	@Override
+	public void registerBeanDefinitions(AnnotationMetadata importingClassMetadata, BeanDefinitionRegistry registry,
+			BeanNameGenerator importBeanNameGenerator) {
+		MergedAnnotation<ImportTestcontainers> annotation = importingClassMetadata.getAnnotations()
+			.get(ImportTestcontainers.class);
+		Class<?>[] definitionClasses = annotation.getClassArray(MergedAnnotation.VALUE);
+		if (ObjectUtils.isEmpty(definitionClasses)) {
+			Class<?> importingClass = ClassUtils.resolveClassName(importingClassMetadata.getClassName(), null);
+			definitionClasses = new Class<?>[] { importingClass };
+		}
+		registerBeanDefinitions(registry, importBeanNameGenerator, definitionClasses);
+	}
+
+	private void registerBeanDefinitions(BeanDefinitionRegistry registry, BeanNameGenerator importBeanNameGenerator,
+			Class<?>[] definitionClasses) {
+		for (Class<?> definitionClass : definitionClasses) {
+			this.containerFieldsImporter.registerBeanDefinitions(registry, importBeanNameGenerator, definitionClass);
+			if (this.dynamicPropertySourceMethodsImporter != null) {
+				this.dynamicPropertySourceMethodsImporter.registerDynamicPropertySources(definitionClass);
+			}
+		}
+	}
+
+}

spring-boot-project/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/context/TestcontainerFieldBeanDefinition.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2012-2023 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.boot.testcontainers.context;
+
+import java.lang.reflect.Field;
+
+import org.testcontainers.containers.Container;
+
+import org.springframework.beans.factory.support.RootBeanDefinition;
+import org.springframework.boot.testcontainers.beans.TestcontainerBeanDefinition;
+import org.springframework.core.annotation.MergedAnnotations;
+
+/**
+ * {@link RootBeanDefinition} used for testcontainer bean definitions.
+ *
+ * @author Phillip Webb
+ */
+class TestcontainerFieldBeanDefinition extends RootBeanDefinition implements TestcontainerBeanDefinition {
+
+	private final Container<?> container;
+
+	private final MergedAnnotations annotations;
+
+	TestcontainerFieldBeanDefinition(Field field, Container<?> container) {
+		this.container = container;
+		this.annotations = MergedAnnotations.from(field);
+		this.setBeanClass(container.getClass());
+		setInstanceSupplier(() -> container);
+	}
+
+	@Override
+	public String getContainerImageName() {
+		return this.container.getDockerImageName();
+	}
+
+	@Override
+	public MergedAnnotations getAnnotations() {
+		return this.annotations;
+	}
+
+}

spring-boot-project/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/context/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2012-2023 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.
+ */
+
+/**
+ * Spring context support classes for Testcontainers.
+ */
+package org.springframework.boot.testcontainers.context;

spring-boot-project/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2012-2023 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.
+ */
+
+/**
+ * Support for testcontainers.
+ */
+package org.springframework.boot.testcontainers;

spring-boot-project/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/ServiceConnectionAutoConfigurationRegistrar.java

@@ -16,6 +16,7 @@
 
 package org.springframework.boot.testcontainers.service.connection;
 
+import java.util.LinkedHashSet;
 import java.util.Set;
 
 import org.testcontainers.containers.Container;
@@ -27,7 +28,9 @@ import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
 import org.springframework.beans.factory.support.BeanDefinitionRegistry;
 import org.springframework.boot.autoconfigure.service.connection.ConnectionDetailsFactories;
 import org.springframework.boot.origin.Origin;
+import org.springframework.boot.testcontainers.beans.TestcontainerBeanDefinition;
 import org.springframework.context.annotation.ImportBeanDefinitionRegistrar;
+import org.springframework.core.annotation.MergedAnnotation;
 import org.springframework.core.type.AnnotationMetadata;
 
 /**
@@ -56,15 +59,24 @@ class ServiceConnectionAutoConfigurationRegistrar implements ImportBeanDefinitio
 				new ConnectionDetailsFactories());
 		for (String beanName : beanFactory.getBeanNamesForType(Container.class)) {
 			BeanDefinition beanDefinition = getBeanDefinition(beanFactory, beanName);
-			for (ServiceConnection annotation : getAnnotations(beanFactory, beanName)) {
+			for (ServiceConnection annotation : getAnnotations(beanFactory, beanName, beanDefinition)) {
 				ContainerConnectionSource<?> source = createSource(beanFactory, beanName, beanDefinition, annotation);
 				registrar.registerBeanDefinitions(registry, source);
 			}
 		}
 	}
 
-	private Set<ServiceConnection> getAnnotations(ConfigurableListableBeanFactory beanFactory, String beanName) {
-		return beanFactory.findAllAnnotationsOnBean(beanName, ServiceConnection.class, false);
+	private Set<ServiceConnection> getAnnotations(ConfigurableListableBeanFactory beanFactory, String beanName,
+			BeanDefinition beanDefinition) {
+		Set<ServiceConnection> annoations = new LinkedHashSet<>();
+		annoations.addAll(beanFactory.findAllAnnotationsOnBean(beanName, ServiceConnection.class, false));
+		if (beanDefinition instanceof TestcontainerBeanDefinition testcontainerBeanDefinition) {
+			testcontainerBeanDefinition.getAnnotations()
+				.stream(ServiceConnection.class)
+				.map(MergedAnnotation::synthesize)
+				.forEach(annoations::add);
+		}
+		return annoations;
 	}
 
 	private BeanDefinition getBeanDefinition(ConfigurableListableBeanFactory beanFactory, String beanName) {
@@ -82,7 +94,9 @@ class ServiceConnectionAutoConfigurationRegistrar implements ImportBeanDefinitio
 			ServiceConnection annotation) {
 		Origin origin = new BeanOrigin(beanName, beanDefinition);
 		Class<C> containerType = (Class<C>) beanFactory.getType(beanName, false);
-		return new ContainerConnectionSource<>(beanName, origin, containerType, null, annotation,
+		String containerImageName = (beanDefinition instanceof TestcontainerBeanDefinition testcontainerBeanDefinition)
+				? testcontainerBeanDefinition.getContainerImageName() : null;
+		return new ContainerConnectionSource<>(beanName, origin, containerType, containerImageName, annotation,
 				() -> beanFactory.getBean(beanName, containerType));
 	}
 

spring-boot-project/spring-boot-testcontainers/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

@@ -1,2 +1,2 @@
-org.springframework.boot.testcontainers.properties.DynamicProperySourceAutoConfiguration
+org.springframework.boot.testcontainers.properties.TestcontainersPropertySourceAutoConfiguration
 org.springframework.boot.testcontainers.service.connection.ServiceConnectionAutoConfiguration