Add nullability annotations to core/spring-boot-testcontainers

mhalbritter · mhalbritter · commit 419a1c33598a · 2025-07-29T14:46:44.000+02:00
See gh-46587
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/beans/TestcontainerBeanDefinition.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/beans/TestcontainerBeanDefinition.java
@@ -16,6 +16,8 @@
 
 package org.springframework.boot.testcontainers.beans;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.beans.factory.config.BeanDefinition;
 import org.springframework.core.annotation.MergedAnnotations;
 
@@ -32,7 +34,7 @@ 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();
+	@Nullable String getContainerImageName();
 
 	/**
 	 * Return any annotations declared alongside the container.
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/beans/package-info.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/beans/package-info.java
@@ -17,4 +17,7 @@
 /**
  * Spring bean support classes for Testcontainers.
  */
+@NullMarked
 package org.springframework.boot.testcontainers.beans;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/context/ImportTestcontainersRegistrar.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/context/ImportTestcontainersRegistrar.java
@@ -18,6 +18,7 @@
 
 import java.util.Set;
 
+import org.jspecify.annotations.Nullable;
 import org.testcontainers.lifecycle.Startable;
 
 import org.springframework.beans.factory.support.BeanDefinitionRegistry;
@@ -42,7 +43,7 @@ class ImportTestcontainersRegistrar implements ImportBeanDefinitionRegistrar {
 
 	private final ContainerFieldsImporter containerFieldsImporter;
 
-	private final DynamicPropertySourceMethodsImporter dynamicPropertySourceMethodsImporter;
+	private final @Nullable DynamicPropertySourceMethodsImporter dynamicPropertySourceMethodsImporter;
 
 	ImportTestcontainersRegistrar(Environment environment) {
 		this.containerFieldsImporter = new ContainerFieldsImporter();
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/context/package-info.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/context/package-info.java
@@ -17,4 +17,7 @@
 /**
  * Spring context support classes for Testcontainers.
  */
+@NullMarked
 package org.springframework.boot.testcontainers.context;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/lifecycle/TestcontainersLifecycleBeanPostProcessor.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/lifecycle/TestcontainersLifecycleBeanPostProcessor.java
@@ -26,6 +26,7 @@
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
+import org.jspecify.annotations.Nullable;
 import org.testcontainers.containers.ContainerState;
 import org.testcontainers.containers.GenericContainer;
 import org.testcontainers.lifecycle.Startable;
@@ -145,7 +146,7 @@ private List<String> getBeanNames(Class<?> type) {
 		return List.of(this.beanFactory.getBeanNamesForType(type, true, false));
 	}
 
-	private List<Object> getBeans(List<String> beanNames) {
+	private @Nullable List<Object> getBeans(List<String> beanNames) {
 		List<Object> beans = new ArrayList<>(beanNames.size());
 		for (String beanName : beanNames) {
 			try {
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/lifecycle/TestcontainersStartup.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/lifecycle/TestcontainersStartup.java
@@ -23,6 +23,7 @@
 import java.util.Set;
 import java.util.stream.Collectors;
 
+import org.jspecify.annotations.Nullable;
 import org.testcontainers.containers.Container;
 import org.testcontainers.lifecycle.Startable;
 import org.testcontainers.lifecycle.Startables;
@@ -72,11 +73,11 @@ void start(Collection<? extends Startable> startables) {
 
 	abstract void start(Collection<? extends Startable> startables);
 
-	static TestcontainersStartup get(ConfigurableEnvironment environment) {
+	static TestcontainersStartup get(@Nullable ConfigurableEnvironment environment) {
 		return get((environment != null) ? environment.getProperty(PROPERTY) : null);
 	}
 
-	private static TestcontainersStartup get(String value) {
+	private static TestcontainersStartup get(@Nullable String value) {
 		if (value == null) {
 			return SEQUENTIAL;
 		}
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/lifecycle/package-info.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/lifecycle/package-info.java
@@ -18,4 +18,7 @@
  * Utilities and helpers to allow testcontainers to be used in a Spring
  * {@link org.springframework.context.ApplicationContext ApplicationContext}.
  */
+@NullMarked
 package org.springframework.boot.testcontainers.lifecycle;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/package-info.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/package-info.java
@@ -17,4 +17,7 @@
 /**
  * Support for testcontainers.
  */
+@NullMarked
 package org.springframework.boot.testcontainers;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/properties/package-info.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/properties/package-info.java
@@ -17,4 +17,7 @@
 /**
  * Dynamic container properties support.
  */
+@NullMarked
 package org.springframework.boot.testcontainers.properties;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/BeanOrigin.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/BeanOrigin.java
@@ -18,6 +18,8 @@
 
 import java.util.Objects;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.beans.factory.config.BeanDefinition;
 import org.springframework.boot.origin.Origin;
 
@@ -30,9 +32,9 @@ class BeanOrigin implements Origin {
 
 	private final String beanName;
 
-	private final String resourceDescription;
+	private final @Nullable String resourceDescription;
 
-	BeanOrigin(String beanName, BeanDefinition beanDefinition) {
+	BeanOrigin(String beanName, @Nullable BeanDefinition beanDefinition) {
 		this.beanName = beanName;
 		this.resourceDescription = (beanDefinition != null) ? beanDefinition.getResourceDescription() : null;
 	}
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/ContainerConnectionDetailsFactory.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/ContainerConnectionDetailsFactory.java
@@ -23,6 +23,7 @@
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
+import org.jspecify.annotations.Nullable;
 import org.testcontainers.containers.Container;
 import org.testcontainers.lifecycle.Startable;
 
@@ -62,7 +63,7 @@ public abstract class ContainerConnectionDetailsFactory<C extends Container<?>,
 	/**
 	 * Constant passed to the constructor when any connection name is accepted.
 	 */
-	protected static final String ANY_CONNECTION_NAME = null;
+	protected static final @Nullable String ANY_CONNECTION_NAME = null;
 
 	private final List<String> connectionNames;
 
@@ -82,7 +83,7 @@ protected ContainerConnectionDetailsFactory() {
 	 * @param connectionName the required connection name or {@link #ANY_CONNECTION_NAME}
 	 * @param requiredClassNames the names of classes that must be present
 	 */
-	protected ContainerConnectionDetailsFactory(String connectionName, String... requiredClassNames) {
+	protected ContainerConnectionDetailsFactory(@Nullable String connectionName, String... requiredClassNames) {
 		this(Arrays.asList(connectionName), requiredClassNames);
 	}
 
@@ -100,14 +101,16 @@ protected ContainerConnectionDetailsFactory(List<String> connectionNames, String
 	}
 
 	@Override
-	public final D getConnectionDetails(ContainerConnectionSource<C> source) {
+	public final @Nullable D getConnectionDetails(ContainerConnectionSource<C> source) {
 		if (!hasRequiredClasses()) {
 			return null;
 		}
 		try {
-			Class<?>[] generics = resolveGenerics();
+			@Nullable Class<?>[] generics = resolveGenerics();
 			Class<?> requiredContainerType = generics[0];
 			Class<?> requiredConnectionDetailsType = generics[1];
+			Assert.state(requiredContainerType != null, "'requiredContainerType' must not be null");
+			Assert.state(requiredConnectionDetailsType != null, "'requiredConnectionDetailsType' must not be null");
 			if (sourceAccepts(source, requiredContainerType, requiredConnectionDetailsType)) {
 				return getContainerConnectionDetails(source);
 			}
@@ -142,7 +145,7 @@ private boolean hasRequiredClasses() {
 			.allMatch((requiredClassName) -> ClassUtils.isPresent(requiredClassName, null));
 	}
 
-	private Class<?>[] resolveGenerics() {
+	private @Nullable Class<?>[] resolveGenerics() {
 		return ResolvableType.forClass(ContainerConnectionDetailsFactory.class, getClass()).resolveGenerics();
 	}
 
@@ -153,7 +156,7 @@ private Class<?>[] resolveGenerics() {
 	 * @param source the source
 	 * @return the service connection or {@code null}.
 	 */
-	protected abstract D getContainerConnectionDetails(ContainerConnectionSource<C> source);
+	protected abstract @Nullable D getContainerConnectionDetails(ContainerConnectionSource<C> source);
 
 	/**
 	 * Base class for {@link ConnectionDetails} results that are backed by a
@@ -166,9 +169,9 @@ protected static class ContainerConnectionDetails<C extends Container<?>>
 
 		private final ContainerConnectionSource<C> source;
 
-		private volatile C container;
+		private volatile @Nullable C container;
 
-		private volatile SslBundle sslBundle;
+		private volatile @Nullable SslBundle sslBundle;
 
 		/**
 		 * Create a new {@link ContainerConnectionDetails} instance.
@@ -203,7 +206,7 @@ protected final C getContainer() {
 		 * @return the ssl bundle or {@code null}
 		 * @since 3.5.0
 		 */
-		protected SslBundle getSslBundle() {
+		protected @Nullable SslBundle getSslBundle() {
 			if (this.source.getSslBundleSource() == null) {
 				return null;
 			}
@@ -242,7 +245,7 @@ static class ContainerConnectionDetailsFactoriesRuntimeHints implements RuntimeH
 		private static final Log logger = LogFactory.getLog(ContainerConnectionDetailsFactoriesRuntimeHints.class);
 
 		@Override
-		public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
+		public void registerHints(RuntimeHints hints, @Nullable ClassLoader classLoader) {
 			SpringFactoriesLoader.forDefaultResourceLocation(classLoader)
 				.load(ConnectionDetailsFactory.class, FailureHandler.logging(logger))
 				.stream()
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/ContainerConnectionSource.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/ContainerConnectionSource.java
@@ -22,6 +22,7 @@
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
+import org.jspecify.annotations.Nullable;
 import org.testcontainers.containers.Container;
 import org.testcontainers.utility.DockerImageName;
 
@@ -54,21 +55,22 @@ public final class ContainerConnectionSource<C extends Container<?>> implements
 
 	private final Class<C> containerType;
 
-	private final String containerImageName;
+	private final @Nullable String containerImageName;
 
-	private final String connectionName;
+	private final @Nullable String connectionName;
 
 	private final Set<Class<?>> connectionDetailsTypes;
 
 	private final Supplier<C> containerSupplier;
 
-	private final SslBundleSource sslBundleSource;
+	private final @Nullable SslBundleSource sslBundleSource;
 
-	private final MergedAnnotations annotations;
+	private final @Nullable MergedAnnotations annotations;
 
-	ContainerConnectionSource(String beanNameSuffix, Origin origin, Class<C> containerType, String containerImageName,
-			MergedAnnotation<ServiceConnection> annotation, Supplier<C> containerSupplier,
-			SslBundleSource sslBundleSource, MergedAnnotations annotations) {
+	ContainerConnectionSource(String beanNameSuffix, Origin origin, Class<C> containerType,
+			@Nullable String containerImageName, MergedAnnotation<ServiceConnection> annotation,
+			Supplier<C> containerSupplier, @Nullable SslBundleSource sslBundleSource,
+			@Nullable MergedAnnotations annotations) {
 		this.beanNameSuffix = beanNameSuffix;
 		this.origin = origin;
 		this.containerType = containerType;
@@ -80,9 +82,9 @@ public final class ContainerConnectionSource<C extends Container<?>> implements
 		this.annotations = annotations;
 	}
 
-	ContainerConnectionSource(String beanNameSuffix, Origin origin, Class<C> containerType, String containerImageName,
-			ServiceConnection annotation, Supplier<C> containerSupplier, SslBundleSource sslBundleSource,
-			MergedAnnotations annotations) {
+	ContainerConnectionSource(String beanNameSuffix, Origin origin, Class<C> containerType,
+			@Nullable String containerImageName, ServiceConnection annotation, Supplier<C> containerSupplier,
+			@Nullable SslBundleSource sslBundleSource, @Nullable MergedAnnotations annotations) {
 		this.beanNameSuffix = beanNameSuffix;
 		this.origin = origin;
 		this.containerType = containerType;
@@ -94,7 +96,8 @@ public final class ContainerConnectionSource<C extends Container<?>> implements
 		this.annotations = annotations;
 	}
 
-	private static String getOrDeduceConnectionName(String connectionName, String containerImageName) {
+	private static @Nullable String getOrDeduceConnectionName(@Nullable String connectionName,
+			@Nullable String containerImageName) {
 		if (StringUtils.hasText(connectionName)) {
 			return connectionName;
 		}
@@ -114,7 +117,7 @@ private static String getOrDeduceConnectionName(String connectionName, String co
 	 * @return if the connection is accepted by this source
 	 * @since 3.4.0
 	 */
-	public boolean accepts(String requiredConnectionName, Class<?> requiredContainerType,
+	public boolean accepts(@Nullable String requiredConnectionName, Class<?> requiredContainerType,
 			Class<?> requiredConnectionDetailsType) {
 		if (StringUtils.hasText(requiredConnectionName)
 				&& !requiredConnectionName.equalsIgnoreCase(this.connectionName)) {
@@ -152,11 +155,11 @@ public Origin getOrigin() {
 		return this.origin;
 	}
 
-	String getContainerImageName() {
+	@Nullable String getContainerImageName() {
 		return this.containerImageName;
 	}
 
-	String getConnectionName() {
+	@Nullable String getConnectionName() {
 		return this.connectionName;
 	}
 
@@ -168,7 +171,7 @@ Set<Class<?>> getConnectionDetailsTypes() {
 		return this.connectionDetailsTypes;
 	}
 
-	SslBundleSource getSslBundleSource() {
+	@Nullable SslBundleSource getSslBundleSource() {
 		return this.sslBundleSource;
 	}
 
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/ServiceConnectionAutoConfigurationRegistrar.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/ServiceConnectionAutoConfigurationRegistrar.java
@@ -19,6 +19,7 @@
 import java.util.LinkedHashSet;
 import java.util.Set;
 
+import org.jspecify.annotations.Nullable;
 import org.testcontainers.containers.Container;
 
 import org.springframework.beans.factory.BeanFactory;
@@ -33,6 +34,7 @@
 import org.springframework.core.annotation.MergedAnnotation;
 import org.springframework.core.annotation.MergedAnnotations;
 import org.springframework.core.type.AnnotationMetadata;
+import org.springframework.util.Assert;
 
 /**
  * {@link ImportBeanDefinitionRegistrar} used by
@@ -71,7 +73,7 @@ private void registerBeanDefinitions(ConfigurableListableBeanFactory beanFactory
 	}
 
 	private Set<ServiceConnection> getServiceConnections(ConfigurableListableBeanFactory beanFactory, String beanName,
-			MergedAnnotations annotations) {
+			@Nullable MergedAnnotations annotations) {
 		Set<ServiceConnection> serviceConnections = beanFactory.findAllAnnotationsOnBean(beanName,
 				ServiceConnection.class, false);
 		if (annotations != null) {
@@ -83,7 +85,7 @@ private Set<ServiceConnection> getServiceConnections(ConfigurableListableBeanFac
 		return serviceConnections;
 	}
 
-	private BeanDefinition getBeanDefinition(ConfigurableListableBeanFactory beanFactory, String beanName) {
+	private @Nullable BeanDefinition getBeanDefinition(ConfigurableListableBeanFactory beanFactory, String beanName) {
 		try {
 			return beanFactory.getBeanDefinition(beanName);
 		}
@@ -94,12 +96,13 @@ private BeanDefinition getBeanDefinition(ConfigurableListableBeanFactory beanFac
 
 	@SuppressWarnings("unchecked")
 	private <C extends Container<?>> ContainerConnectionSource<C> createSource(
-			ConfigurableListableBeanFactory beanFactory, String beanName, BeanDefinition beanDefinition,
-			MergedAnnotations annotations, ServiceConnection serviceConnection) {
+			ConfigurableListableBeanFactory beanFactory, String beanName, @Nullable BeanDefinition beanDefinition,
+			@Nullable MergedAnnotations annotations, ServiceConnection serviceConnection) {
 		Origin origin = new BeanOrigin(beanName, beanDefinition);
 		Class<C> containerType = (Class<C>) beanFactory.getType(beanName, false);
 		String containerImageName = (beanDefinition instanceof TestcontainerBeanDefinition testcontainerBeanDefinition)
 				? testcontainerBeanDefinition.getContainerImageName() : null;
+		Assert.state(containerType != null, "'containerType' must not be null");
 		return new ContainerConnectionSource<>(beanName, origin, containerType, containerImageName, serviceConnection,
 				() -> beanFactory.getBean(beanName, containerType),
 				SslBundleSource.get(beanFactory, beanName, annotations), annotations);
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/ServiceConnectionContextCustomizer.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/ServiceConnectionContextCustomizer.java
@@ -20,6 +20,7 @@
 import java.util.Set;
 import java.util.stream.Collectors;
 
+import org.jspecify.annotations.Nullable;
 import org.testcontainers.containers.Container;
 
 import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
@@ -91,8 +92,8 @@ List<ContainerConnectionSource<?>> getSources() {
 	 * Relevant details from {@link ContainerConnectionSource} used as a
 	 * MergedContextConfiguration cache key.
 	 */
-	private record CacheKey(String connectionName, Set<Class<?>> connectionDetailsTypes, Container<?> container,
-			SslBundleSource sslBundleSource) {
+	private record CacheKey(@Nullable String connectionName, Set<Class<?>> connectionDetailsTypes,
+			Container<?> container, @Nullable SslBundleSource sslBundleSource) {
 
 		CacheKey(ContainerConnectionSource<?> source) {
 			this(source.getConnectionName(), source.getConnectionDetailsTypes(), source.getContainerSupplier().get(),
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/ServiceConnectionContextCustomizerFactory.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/ServiceConnectionContextCustomizerFactory.java
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/SslBundleSource.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/SslBundleSource.java
diff --git a/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/package-info.java b/core/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/service/connection/package-info.java
