Add support for JSpecify.

Author: mp911de

pom.xml

@@ -1,5 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
 
 	<modelVersion>4.0.0</modelVersion>
 
@@ -116,6 +118,13 @@
 			<optional>true</optional>
 		</dependency>
 
+		<dependency>
+			<groupId>org.jspecify</groupId>
+			<artifactId>jspecify</artifactId>
+			<version>0.3.0</version>
+			<optional>true</optional>
+		</dependency>
+
 		<dependency>
 			<groupId>com.google.code.findbugs</groupId>
 			<artifactId>jsr305</artifactId>

src/main/antora/modules/ROOT/pages/repositories/null-handling.adoc

@@ -25,6 +25,9 @@ They provide a tooling-friendly approach and opt-in `null` checks during runtime
 
 Spring annotations are meta-annotated with https://jcp.org/en/jsr/detail?id=305[JSR 305] annotations (a dormant but widely used JSR).
 JSR 305 meta-annotations let tooling vendors (such as https://www.jetbrains.com/help/idea/nullable-and-notnull-annotations.html[IDEA], https://help.eclipse.org/latest/index.jsp?topic=/org.eclipse.jdt.doc.user/tasks/task-using_external_null_annotations.htm[Eclipse], and link:https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types[Kotlin]) provide null-safety support in a generic way, without having to hard-code support for Spring annotations.
+
+NOTE: Spring Data can evaluate link:https://jspecify.dev/[JSpecify] annotations to determine nullability rules.0 JSpecify is still in development and might experience slight changes.
+
 To enable runtime checking of nullability constraints for query methods, you need to activate non-nullability on the package level by using Spring’s `@NonNullApi` in `package-info.java`, as shown in the following example:
 
 .Declaring Non-nullability in `package-info.java`

src/main/java/org/springframework/data/util/NullabilityIntrospector.java

@@ -18,6 +18,8 @@
 import java.lang.annotation.Annotation;
 import java.lang.annotation.ElementType;
 import java.lang.reflect.AnnotatedElement;
+import java.lang.reflect.AnnotatedType;
+import java.lang.reflect.Executable;
 import java.lang.reflect.Method;
 import java.lang.reflect.Parameter;
 import java.util.ArrayList;
@@ -52,8 +54,12 @@ class NullabilityIntrospector implements Nullability.Introspector {
 			providers.add(new Jsr305Provider());
 		}
 
-		if (JakartaAnnotation.isAvailable()) {
-			providers.add(new JakartaAnnotation());
+		if (JakartaAnnotationProvider.isAvailable()) {
+			providers.add(new JakartaAnnotationProvider());
+		}
+
+		if (JSpecifyAnnotationProvider.isAvailable()) {
+			providers.add(new JSpecifyAnnotationProvider());
 		}
 
 		providers.add(new SpringProvider());
@@ -251,7 +257,7 @@ private static boolean isInScope(Annotation annotation, ElementType elementType)
 		}
 
 		/**
-		 * Introspect {@link Annotation} for being either a meta-annotation composed from {@code Nonnull} or {code Nonnull}
+		 * Introspect {@link Annotation} for being either a meta-annotation composed of {@code Nonnull} or {code Nonnull}
 		 * itself expressing non-nullability.
 		 *
 		 * @param annotation
@@ -274,56 +280,124 @@ static boolean isNullable(Annotation annotation) {
 	}
 
 	/**
-	 * Provider based on the JSR-305 (dormant) spec. Elements can be either annotated with
-	 * {@code @Nonnull}/{@code @Nullable} directly or through meta-annotations that are composed of
-	 * {@code @Nonnull}/{@code @Nullable} and {@code @TypeQualifierDefault}.
+	 * Simplified variant of {@link Jsr305Provider} without {@code when} and {@code @TypeQualifierDefault} support.
 	 */
-	static class JakartaAnnotation extends NullabilityProvider {
+	static class JakartaAnnotationProvider extends SimpleAnnotationNullabilityProvider {
 
 		private static final Class<Annotation> NON_NULL = findClass("jakarta.annotation.Nonnull");
 		private static final Class<Annotation> NULLABLE = findClass("jakarta.annotation.Nullable");
 
+		JakartaAnnotationProvider() {
+			super(NON_NULL, NULLABLE);
+		}
+
 		public static boolean isAvailable() {
 			return NON_NULL != null && NULLABLE != null;
 		}
+	}
+
+	/**
+	 * Provider for JSpecify annotations.
+	 */
+	static class JSpecifyAnnotationProvider extends NullabilityProvider {
+
+		private static final Class<Annotation> NON_NULL = findClass("org.jspecify.annotations.NonNull");
+		private static final Class<Annotation> NULLABLE = findClass("org.jspecify.annotations.Nullable");
+		private static final Class<Annotation> NULL_MARKED = findClass("org.jspecify.annotations.NullMarked");
+		private static final Class<Annotation> NULL_UNMARKED = findClass("org.jspecify.annotations.NullUnmarked");
+
+		public static boolean isAvailable() {
+			return NON_NULL != null && NULLABLE != null && NULL_MARKED != null && NULL_UNMARKED != null;
+		}
 
 		@Override
 		Spec evaluate(AnnotatedElement element, ElementType elementType) {
 
-			if (element.isAnnotationPresent(NULLABLE) || MergedAnnotations.from(element).isPresent(NULLABLE)) {
-				return Spec.NULLABLE;
+			Annotation[] annotations = element.getAnnotations();
+			AnnotatedType annotatedType = null;
+
+			if (element instanceof Parameter p) {
+
+				Spec result = evaluate(p.getAnnotatedType(), elementType);
+
+				if (result != Spec.UNSPECIFIED) {
+					return result;
+				}
 			}
 
-			Annotation[] annotations = element.getAnnotations();
+			if (element instanceof Executable e) {
 
+				Spec result = evaluate(e.getAnnotatedReturnType(), elementType);
+
+				if (result != Spec.UNSPECIFIED) {
+					return result;
+				}
+			}
+
+			return evaluate(annotations);
+		}
+
+		private static Spec evaluate(Annotation[] annotations) {
 			for (Annotation annotation : annotations) {
 
-				if (test(NON_NULL, annotation)) {
+				if (SimpleAnnotationNullabilityProvider.test(NULL_UNMARKED, annotation)) {
+					return Spec.UNSPECIFIED;
+				}
+
+				if (SimpleAnnotationNullabilityProvider.test(NULL_MARKED, annotation)
+						|| SimpleAnnotationNullabilityProvider.test(NON_NULL, annotation)) {
 					return Spec.NON_NULL;
 				}
 
-				if (test(NULLABLE, annotation)) {
+				if (SimpleAnnotationNullabilityProvider.test(NULLABLE, annotation)) {
 					return Spec.NULLABLE;
 				}
 			}
 
 			return Spec.UNSPECIFIED;
 		}
+	}
+
+	/**
+	 * Annotation-based {@link NullabilityProvider} leveraging simple or meta-annotations.
+	 */
+	static class SimpleAnnotationNullabilityProvider extends NullabilityProvider {
 
-		private static boolean test(Class<Annotation> annotationClass, Annotation annotation) {
+		private final Class<Annotation> nonNull;
+		private final Class<Annotation> nullable;
 
-			if (annotation.annotationType().equals(annotationClass)) {
-				return true;
+		SimpleAnnotationNullabilityProvider(Class<Annotation> nonNull, Class<Annotation> nullable) {
+			this.nonNull = nonNull;
+			this.nullable = nullable;
+		}
+
+		@Override
+		Spec evaluate(AnnotatedElement element, ElementType elementType) {
+
+			Annotation[] annotations = element.getAnnotations();
+
+			for (Annotation annotation : annotations) {
+
+				if (test(nonNull, annotation)) {
+					return Spec.NON_NULL;
+				}
+
+				if (test(nullable, annotation)) {
+					return Spec.NULLABLE;
+				}
 			}
 
-			MergedAnnotations annotations = MergedAnnotations.from(annotation.annotationType());
-			if (annotations.isPresent(annotationClass)) {
-				Annotation meta = annotations.get(annotationClass).synthesize();
+			return Spec.UNSPECIFIED;
+		}
+
+		static boolean test(Class<Annotation> annotationClass, Annotation annotation) {
 
+			if (annotation.annotationType().equals(annotationClass)) {
 				return true;
 			}
 
-			return false;
+			MergedAnnotations annotations = MergedAnnotations.from(annotation.annotationType());
+			return annotations.isPresent(annotationClass);
 		}
 
 	}

src/test/java/org/springframework/data/util/NullableUtilsUnitTests.java

@@ -93,6 +93,29 @@ void shouldConsiderJakartaNonNullParameters() {
 		assertThat(pn1.isNonNull()).isFalse();
 	}
 
+	@Test //
+	void shouldConsiderJSpecifyNonNullParameters() {
+
+		var method = ReflectionUtils.findMethod(org.springframework.data.util.nonnull.jspecify.NonNullOnPackage.class,
+				"someMethod", String.class, String.class);
+		Nullability.Introspector introspector = Nullability.introspect(method.getDeclaringClass());
+		Nullability mrt = introspector.forReturnType(method);
+
+		assertThat(mrt.isDeclared()).isTrue();
+		assertThat(mrt.isNonNull()).isTrue();
+		assertThat(mrt.isNullable()).isFalse();
+
+		Nullability pn0 = introspector.forParameter(MethodParameter.forExecutable(method, 0));
+		assertThat(pn0.isDeclared()).isTrue();
+		assertThat(pn0.isNullable()).isFalse();
+		assertThat(pn0.isNonNull()).isTrue();
+
+		Nullability pn1 = introspector.forParameter(MethodParameter.forExecutable(method, 1));
+		assertThat(pn1.isDeclared()).isTrue();
+		assertThat(pn1.isNullable()).isTrue();
+		assertThat(pn1.isNonNull()).isFalse();
+	}
+
 	@Test // DATACMNS-1154
 	void shouldConsiderJsr305NonNullParameters() {
 

src/test/java/org/springframework/data/util/nonnull/jspecify/NonNullOnPackage.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2017-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.data.util.nonnull.jspecify;
+
+import org.jspecify.annotations.Nullable;
+
+/**
+ * @author Mark Paluch
+ */
+public interface NonNullOnPackage {
+
+	String someMethod(String arg, @Nullable String nullableArg);
+}

src/test/java/org/springframework/data/util/nonnull/jspecify/package-info.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright 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.
+ */
+
+/**
+ * @author Mark Paluch
+ */
+@NullMarked
+package org.springframework.data.util.nonnull.jspecify;
+
+import org.jspecify.annotations.NullMarked;