refactor: Migrate to JSpecify annotations for nullability constraints. (#3016)

Replaces all deprecated Spring annotations with JSpecify annotations, and includes a full refactor so that the parent build profile `-Pnullaway` compiles and works proper.

Closes #2987

Signed-off-by: Michael Simons <[email protected]>

Author: michael-simons

pom.xml

@@ -84,14 +84,19 @@
 		<java-module-name>spring.data.neo4j</java-module-name>
 		<java.version>17</java.version>
 		<jaxb.version>2.3.1</jaxb.version>
+		<jna.version>5.8.0</jna.version>
+		<jspecify.version>1.0.0</jspecify.version>
+		<jsr305.version>3.0.2</jsr305.version>
 		<junit-cc-testcontainer>2021.0.1</junit-cc-testcontainer>
+		<junit-pioneer.version>2.2.0</junit-pioneer.version>
 		<maven-install-plugin.version>3.1.4</maven-install-plugin.version>
 		<maven-site-plugin.version>3.7.1</maven-site-plugin.version>
 		<maven.compiler.release>${java.version}</maven.compiler.release>
 		<neo4j-java-driver.version>5.28.5</neo4j-java-driver.version>
 		<neo4j-migrations.version>2.17.3</neo4j-migrations.version>
 		<neo4j.version>4.4.41</neo4j.version>
 		<objenesis.version>3.0.1</objenesis.version>
+		<org.osgi.core.version>6.0.0</org.osgi.core.version>
 		<project.build.docs>${project.build.directory}/docs</project.build.docs>
 		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
 		<r2dbc.releasetrain>Arabba-SR11</r2dbc.releasetrain>
@@ -102,22 +107,14 @@
 		<skipUnitTests>${skipTests}</skipUnitTests>
 
 		<springdata.commons>4.0.0-SNAPSHOT</springdata.commons>
-		<junit-pioneer.version>2.2.0</junit-pioneer.version>
 	</properties>
 
 	<dependencyManagement>
 		<dependencies>
-			<dependency>
-				<groupId>org.neo4j</groupId>
-				<artifactId>neo4j-cypher-dsl-bom</artifactId>
-				<version>${cypher-dsl.version}</version>
-				<type>pom</type>
-				<scope>import</scope>
-			</dependency>
 			<dependency>
 				<groupId>com.google.code.findbugs</groupId>
 				<artifactId>jsr305</artifactId>
-				<version>3.0.2</version>
+				<version>${jsr305.version}</version>
 			</dependency>
 			<dependency>
 				<groupId>com.tngtech.archunit</groupId>
@@ -131,9 +128,9 @@
 				<scope>test</scope>
 			</dependency>
 			<dependency>
-				<groupId>org.junit-pioneer</groupId>
-				<artifactId>junit-pioneer</artifactId>
-				<version>${junit-pioneer.version}</version>
+				<groupId>io.projectreactor.tools</groupId>
+				<artifactId>blockhound</artifactId>
+				<version>${blockhound.version}</version>
 			</dependency>
 			<dependency>
 				<groupId>io.r2dbc</groupId>
@@ -161,18 +158,35 @@
 			<dependency>
 				<groupId>net.java.dev.jna</groupId>
 				<artifactId>jna</artifactId>
-				<version>5.8.0</version>
+				<version>${jna.version}</version>
 			</dependency>
 			<dependency>
 				<groupId>org.apiguardian</groupId>
 				<artifactId>apiguardian-api</artifactId>
 				<version>${apiguardian.version}</version>
 			</dependency>
+			<dependency>
+				<groupId>org.jspecify</groupId>
+				<artifactId>jspecify</artifactId>
+				<version>${jspecify.version}</version>
+			</dependency>
+			<dependency>
+				<groupId>org.junit-pioneer</groupId>
+				<artifactId>junit-pioneer</artifactId>
+				<version>${junit-pioneer.version}</version>
+			</dependency>
 			<dependency>
 				<groupId>org.neo4j</groupId>
 				<artifactId>neo4j</artifactId>
 				<version>${neo4j.version}</version>
 			</dependency>
+			<dependency>
+				<groupId>org.neo4j</groupId>
+				<artifactId>neo4j-cypher-dsl-bom</artifactId>
+				<version>${cypher-dsl.version}</version>
+				<type>pom</type>
+				<scope>import</scope>
+			</dependency>
 			<dependency>
 				<groupId>org.neo4j.driver</groupId>
 				<artifactId>neo4j-java-driver</artifactId>
@@ -191,7 +205,7 @@
 			<dependency>
 				<groupId>org.osgi</groupId>
 				<artifactId>org.osgi.core</artifactId>
-				<version>6.0.0</version>
+				<version>${org.osgi.core.version}</version>
 			</dependency>
 			<dependency>
 				<groupId>org.slf4j</groupId>
@@ -210,11 +224,6 @@
 				<type>pom</type>
 				<scope>import</scope>
 			</dependency>
-			<dependency>
-				<groupId>io.projectreactor.tools</groupId>
-				<artifactId>blockhound</artifactId>
-				<version>${blockhound.version}</version>
-			</dependency>
 		</dependencies>
 	</dependencyManagement>
 
@@ -279,6 +288,11 @@
 			<scope>test</scope>
 			<optional>true</optional>
 		</dependency>
+		<dependency>
+			<groupId>io.projectreactor.tools</groupId>
+			<artifactId>blockhound</artifactId>
+			<scope>test</scope>
+		</dependency>
 		<dependency>
 			<groupId>io.r2dbc</groupId>
 			<artifactId>r2dbc-h2</artifactId>
@@ -341,6 +355,11 @@
 			<artifactId>kotlinx-coroutines-reactor</artifactId>
 			<optional>true</optional>
 		</dependency>
+		<dependency>
+			<groupId>org.junit-pioneer</groupId>
+			<artifactId>junit-pioneer</artifactId>
+			<scope>test</scope>
+		</dependency>
 		<dependency>
 			<groupId>org.neo4j</groupId>
 			<artifactId>neo4j-cypher-dsl</artifactId>
@@ -415,28 +434,18 @@
 				</exclusion>
 			</exclusions>
 		</dependency>
-		<dependency>
-			<groupId>io.projectreactor.tools</groupId>
-			<artifactId>blockhound</artifactId>
-			<scope>test</scope>
-		</dependency>
-		<dependency>
-			<groupId>org.junit-pioneer</groupId>
-			<artifactId>junit-pioneer</artifactId>
-			<scope>test</scope>
-		</dependency>
 	</dependencies>
 
 	<repositories>
 		<repository>
-			<id>spring-snapshot</id>
-			<url>https://repo.spring.io/snapshot</url>
-			<snapshots>
-				<enabled>true</enabled>
-			</snapshots>
 			<releases>
 				<enabled>false</enabled>
 			</releases>
+			<snapshots>
+				<enabled>true</enabled>
+			</snapshots>
+			<id>spring-snapshot</id>
+			<url>https://repo.spring.io/snapshot</url>
 		</repository>
 		<repository>
 			<id>spring-milestone</id>
@@ -643,31 +652,6 @@
 					</archive>
 				</configuration>
 			</plugin>
-			<plugin>
-				<groupId>org.apache.maven.plugins</groupId>
-				<artifactId>maven-compiler-plugin</artifactId>
-				<executions>
-					<execution>
-						<id>java-compile</id>
-						<configuration combine.self="append">
-							<compilerArgs>
-								<arg>-Xlint:all,-options,-path</arg>
-							</compilerArgs>
-						</configuration>
-					</execution>
-					<execution>
-						<!-- You would think that applying above configuration to java-test-compile would have the same result.
-						     Alas, it doesn't. The build just fails, -e -X doesn't show anything sane.
-						     So, showDeprecation is just warnings, if set to errors, than it fails hard (which is nice for
-						     deprecation, but it also fails during missing When.MAYBE whateever Jakarta annotation
-						     and there's just no motiviation to deal with Spring Data Commons build setup in this project -->
-						<id>java-test-compile</id>
-						<configuration combine.self="append">
-							<showDeprecation>true</showDeprecation>
-						</configuration>
-					</execution>
-				</executions>
-			</plugin>
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-resources-plugin</artifactId>
@@ -689,8 +673,8 @@
 			<build>
 				<resources>
 					<resource>
-						<directory>src/main/antora/resources/antora-resources</directory>
 						<filtering>true</filtering>
+						<directory>src/main/antora/resources/antora-resources</directory>
 					</resource>
 				</resources>
 			</build>

src/main/java/org/springframework/data/neo4j/aot/Neo4jManagedTypesBeanRegistrationAotProcessor.java

@@ -15,17 +15,17 @@
  */
 package org.springframework.data.neo4j.aot;
 
+import org.jspecify.annotations.Nullable;
 import org.springframework.aot.generate.GenerationContext;
 import org.springframework.core.ResolvableType;
 import org.springframework.data.aot.ManagedTypesBeanRegistrationAotProcessor;
-import org.springframework.lang.Nullable;
 import org.springframework.util.ClassUtils;
 
 /**
  * @author Gerrit Meier
  * @since 7.0.0
  */
-public class Neo4jManagedTypesBeanRegistrationAotProcessor extends ManagedTypesBeanRegistrationAotProcessor {
+public final class Neo4jManagedTypesBeanRegistrationAotProcessor extends ManagedTypesBeanRegistrationAotProcessor {
 
 	public Neo4jManagedTypesBeanRegistrationAotProcessor() {
 		setModuleIdentifier("neo4j");
@@ -36,7 +36,7 @@ protected boolean isMatch(@Nullable Class<?> beanType, @Nullable String beanName
 		return isNeo4jManagedTypes(beanType) || super.isMatch(beanType, beanName);
 	}
 
-	protected boolean isNeo4jManagedTypes(@Nullable Class<?> beanType) {
+	boolean isNeo4jManagedTypes(@Nullable Class<?> beanType) {
 		return beanType != null && ClassUtils.isAssignable(Neo4jManagedTypes.class, beanType);
 	}
 

src/main/java/org/springframework/data/neo4j/aot/Neo4jRuntimeHints.java

@@ -15,6 +15,7 @@
  */
 package org.springframework.data.neo4j.aot;
 
+import org.jspecify.annotations.Nullable;
 import org.springframework.aot.hint.MemberCategory;
 import org.springframework.aot.hint.RuntimeHints;
 import org.springframework.aot.hint.RuntimeHintsRegistrar;
@@ -34,7 +35,6 @@
 import org.springframework.data.neo4j.repository.support.SimpleReactiveNeo4jRepository;
 import org.springframework.data.querydsl.QuerydslUtils;
 import org.springframework.data.util.ReactiveWrappers;
-import org.springframework.lang.Nullable;
 
 import java.util.Arrays;
 

src/main/java/org/springframework/data/neo4j/aot/package-info.java

@@ -0,0 +1,4 @@
+@NullMarked
+package org.springframework.data.neo4j.aot;
+
+import org.jspecify.annotations.NullMarked;

src/main/java/org/springframework/data/neo4j/config/AbstractNeo4jConfig.java

@@ -16,6 +16,7 @@
 package org.springframework.data.neo4j.config;
 
 import org.apiguardian.api.API;
+import org.jspecify.annotations.Nullable;
 import org.neo4j.driver.Driver;
 import org.springframework.beans.factory.ObjectProvider;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -30,7 +31,6 @@
 import org.springframework.data.neo4j.core.transaction.Neo4jBookmarkManager;
 import org.springframework.data.neo4j.core.transaction.Neo4jTransactionManager;
 import org.springframework.data.neo4j.repository.config.Neo4jRepositoryConfigurationExtension;
-import org.springframework.lang.Nullable;
 import org.springframework.transaction.PlatformTransactionManager;
 
 /**
@@ -65,11 +65,11 @@ public abstract class AbstractNeo4jConfig extends Neo4jConfigurationSupport {
 	 * @return A imperative Neo4j client.
 	 */
 	@Bean(Neo4jRepositoryConfigurationExtension.DEFAULT_NEO4J_CLIENT_BEAN_NAME)
-	public Neo4jClient neo4jClient(Driver driver, DatabaseSelectionProvider databaseSelectionProvider) {
+	public Neo4jClient neo4jClient(Driver driver, @Nullable DatabaseSelectionProvider databaseSelectionProvider) {
 
 		return Neo4jClient.with(driver)
 				.withDatabaseSelectionProvider(databaseSelectionProvider)
-				.withUserSelectionProvider(getUserSelectionProvider())
+				.withUserSelectionProvider(this.userSelectionProviders.getIfUnique())
 				.withNeo4jBookmarkManager(getBootBookmarkManager())
 				.build();
 	}
@@ -78,11 +78,6 @@ private Neo4jBookmarkManager getBootBookmarkManager() {
 		return this.bookmarkManagerProviders.getIfAvailable(Neo4jBookmarkManager::create);
 	}
 
-	@Nullable
-	private UserSelectionProvider getUserSelectionProvider() {
-		return this.userSelectionProviders == null ? null : this.userSelectionProviders.getIfUnique();
-	}
-
 	@Bean(Neo4jRepositoryConfigurationExtension.DEFAULT_NEO4J_TEMPLATE_BEAN_NAME)
 	public Neo4jOperations neo4jTemplate(final Neo4jClient neo4jClient, final Neo4jMappingContext mappingContext) {
 
@@ -97,12 +92,12 @@ public Neo4jOperations neo4jTemplate(final Neo4jClient neo4jClient, final Neo4jM
 	 * @return A platform transaction manager
 	 */
 	@Bean(Neo4jRepositoryConfigurationExtension.DEFAULT_TRANSACTION_MANAGER_BEAN_NAME)
-	public PlatformTransactionManager transactionManager(Driver driver, DatabaseSelectionProvider databaseSelectionProvider) {
+	public PlatformTransactionManager transactionManager(Driver driver, @Nullable DatabaseSelectionProvider databaseSelectionProvider) {
 
 		return Neo4jTransactionManager
 				.with(driver)
 				.withDatabaseSelectionProvider(databaseSelectionProvider)
-				.withUserSelectionProvider(getUserSelectionProvider())
+				.withUserSelectionProvider(this.userSelectionProviders.getIfUnique())
 				.withBookmarkManager(getBootBookmarkManager())
 				.build();
 	}

src/main/java/org/springframework/data/neo4j/config/AbstractReactiveNeo4jConfig.java

@@ -16,6 +16,7 @@
 package org.springframework.data.neo4j.config;
 
 import org.apiguardian.api.API;
+import org.jspecify.annotations.Nullable;
 import org.neo4j.driver.Driver;
 import org.springframework.beans.factory.ObjectProvider;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -29,7 +30,6 @@
 import org.springframework.data.neo4j.core.transaction.Neo4jBookmarkManager;
 import org.springframework.data.neo4j.core.transaction.ReactiveNeo4jTransactionManager;
 import org.springframework.data.neo4j.repository.config.ReactiveNeo4jRepositoryConfigurationExtension;
-import org.springframework.lang.Nullable;
 import org.springframework.transaction.PlatformTransactionManager;
 import org.springframework.transaction.ReactiveTransactionManager;
 

src/main/java/org/springframework/data/neo4j/config/Neo4jConfigurationSupport.java

@@ -90,18 +90,4 @@ protected final Set<Class<?>> getInitialEntitySet() throws ClassNotFoundExceptio
 
 		return Neo4jEntityScanner.get().scan(getMappingBasePackages());
 	}
-
-	/**
-	 * Scans the given base package for entities, i.e. Neo4j specific types annotated with {@link Node}.
-	 *
-	 * @param basePackage must not be {@literal null}.
-	 * @return found entities in the package to scan.
-	 * @throws ClassNotFoundException if the given class cannot be loaded by the class loader.
-	 * @deprecated since 6.0.2 Use {@link Neo4jEntityScanner} instead.
-	 */
-	@Deprecated
-	protected final Set<Class<?>> scanForEntities(String basePackage) throws ClassNotFoundException {
-
-		return Neo4jEntityScanner.get().scan(basePackage);
-	}
 }

src/main/java/org/springframework/data/neo4j/config/Neo4jEntityScanner.java

@@ -23,6 +23,7 @@
 import java.util.stream.Collectors;
 
 import org.apiguardian.api.API;
+import org.jspecify.annotations.Nullable;
 import org.springframework.beans.factory.config.BeanDefinition;
 import org.springframework.context.ApplicationContext;
 import org.springframework.context.annotation.ClassPathScanningCandidateComponentProvider;
@@ -31,7 +32,6 @@
 import org.springframework.data.annotation.Persistent;
 import org.springframework.data.neo4j.core.schema.Node;
 import org.springframework.data.neo4j.core.schema.RelationshipProperties;
-import org.springframework.lang.Nullable;
 import org.springframework.util.ClassUtils;
 import org.springframework.util.StringUtils;
 
@@ -55,7 +55,8 @@ public static Neo4jEntityScanner get(@Nullable ResourceLoader resourceLoader) {
 		return new Neo4jEntityScanner(resourceLoader);
 	}
 
-	private @Nullable final ResourceLoader resourceLoader;
+	@Nullable
+	private final ResourceLoader resourceLoader;
 
 	/**
 	 * Create a new {@link Neo4jEntityScanner} instance.
@@ -121,8 +122,7 @@ public Set<Class<?>> scan(Collection<String> packages) throws ClassNotFoundExcep
 	 * @param resourceLoader an optional {@link ResourceLoader} to use
 	 * @return a {@link ClassPathScanningCandidateComponentProvider} suitable to scan for Neo4j entities
 	 */
-	private static ClassPathScanningCandidateComponentProvider createClassPathScanningCandidateComponentProvider(
-			@Nullable ResourceLoader resourceLoader) {
+	private static ClassPathScanningCandidateComponentProvider createClassPathScanningCandidateComponentProvider(@Nullable ResourceLoader resourceLoader) {
 
 		ClassPathScanningCandidateComponentProvider delegate = new ClassPathScanningCandidateComponentProvider(false);
 		if (resourceLoader != null) {