22= Null-safety
33
44Although Java does not let you express null-safety with its type system, the Spring Framework codebase is annotated with
5- https://jspecify.dev/docs/start-here/[JSpecify] annotations to declare the nullability of APIs, fields and related type
5+ https://jspecify.dev/docs/start-here/[JSpecify] annotations to declare the nullness of APIs, fields and related type
66usages. Reading the https://jspecify.dev/docs/user-guide/[JSpecify user guide] is highly recommended in order to get
77familiar with those annotations and semantics.
88
99The primary goal of this explicit null-safety arrangement is to prevent `NullPointerException` to be thrown at runtime via
10- build time checks and to turn explicit nullability into a way to express the possible absence of value. It is useful in
10+ build time checks and to turn explicit nullness into a way to express the possible absence of value. It is useful in
1111both Java by leveraging some tooling (https://github.com/uber/NullAway[NullAway] or IDEs supporting null-safety
1212annotations such as IntelliJ IDEA or Eclipse) and Kotlin where JSpecify annotations are automatically translated to
1313{kotlin-docs}/null-safety.html[Kotlin's null safety].
@@ -40,7 +40,7 @@ to enforce null-safety during build time at application level.
4040The purpose of this section is to share some guidelines proposed for using JSpecify annotations in the context of
4141Spring-related libraries or applications.
4242
43- The key points to understand is that by default, the nullability of types is unknown in Java, and that non-null type
43+ The key points to understand is that by default, the nullness of types is unknown in Java, and that non-null type
4444usages are by far more frequent than nullable ones. In order to keep codebases readable, we typically want to define
4545that by default, type usages are non-null unless marked as nullable for a specific scope. This is exactly the purpose of
4646https://jspecify.dev/docs/api/org/jspecify/annotations/NullMarked.html[`@NullMarked`] that is typically set with Spring
@@ -75,11 +75,11 @@ public static @Nullable String buildMessage(@Nullable String message,
7575}
7676----
7777
78- When overriding a method, nullability annotations are not inherited from the superclass method. That means those
79- nullability annotations should be repeated if you just want to override the implementation and keep the same API
80- nullability .
78+ When overriding a method, nullness annotations are not inherited from the superclass method. That means those
79+ nullness annotations should be repeated if you just want to override the implementation and keep the same API
80+ nullness .
8181
82- With arrays and varargs, you need to be able to differentiate the nullability of the elements from the nullability of
82+ With arrays and varargs, you need to be able to differentiate the nullness of the elements from the nullness of
8383the array itself. Pay attention to the syntax
8484https://docs.oracle.com/javase/specs/jls/se17/html/jls-9.html#jls-9.7.4[defined by the Java specification] which may be
8585initially surprising:
@@ -101,7 +101,7 @@ typical use cases.
101101The {spring-framework-api}/lang/Contract.html[@Contract] annotation in the `org.springframework.lang` package
102102can be used to express complementary semantics to avoid non-relevant null-safety warnings in your codebase.
103103
104- NOTE: Complementary to nullability annotations, the {spring-framework-api}/lang/CheckReturnValue.html[@CheckReturnValue]
104+ NOTE: Complementary to nullness annotations, the {spring-framework-api}/lang/CheckReturnValue.html[@CheckReturnValue]
105105annotation in the `org.springframework.lang` package can be used to specify that the method return value must be used.
106106
107107[[null-safety-migrating]]
@@ -115,12 +115,12 @@ introduced in Spring Framework 5 when JSpecify did not exist and the best option
115115but widespread JSR) meta-annotations. They are deprecated as of Spring Framework 7 in favor of
116116https://jspecify.dev/docs/start-here/[JSpecify] annotations, which provide significant enhancements such as properly
117117defined specifications, a canonical dependency with no split-package issue, better tooling, better Kotlin integration
118- and the capability to specify the nullability more precisely for more use cases.
118+ and the capability to specify the nullness more precisely for more use cases.
119119
120120A key difference is that Spring null-safety annotations, following JSR 305 semantics, apply to fields,
121121parameters and return values while JSpecify annotations apply to type usages. This subtle difference
122- is in practice pretty significant, as it allows for example to differentiate the nullability of elements from the
123- nullability of arrays/varargs as well as defining the nullability of generic types.
122+ is in practice pretty significant, as it allows for example to differentiate the nullness of elements from the
123+ nullness of arrays/varargs as well as defining the nullness of generic types.
124124
125125That means array and varargs null-safety declarations have to be updated to keep the same semantic. For example
126126`@Nullable Object[] array` with Spring annotations needs to be changed to `Object @Nullable [] array` with JSpecify
0 commit comments