2
2
= Null-safety
3
3
4
4
Although 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
6
6
usages. Reading the https://jspecify.dev/docs/user-guide/[JSpecify user guide] is highly recommended in order to get
7
7
familiar with those annotations and semantics.
8
8
9
9
The 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
11
11
both Java by leveraging some tooling (https://github.com/uber/NullAway[NullAway] or IDEs supporting null-safety
12
12
annotations such as IntelliJ IDEA or Eclipse) and Kotlin where JSpecify annotations are automatically translated to
13
13
{kotlin-docs}/null-safety.html[Kotlin's null safety].
@@ -40,7 +40,7 @@ to enforce null-safety during build time at application level.
40
40
The purpose of this section is to share some guidelines proposed for using JSpecify annotations in the context of
41
41
Spring-related libraries or applications.
42
42
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
44
44
usages are by far more frequent than nullable ones. In order to keep codebases readable, we typically want to define
45
45
that by default, type usages are non-null unless marked as nullable for a specific scope. This is exactly the purpose of
46
46
https://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,
75
75
}
76
76
----
77
77
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 .
81
81
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
83
83
the array itself. Pay attention to the syntax
84
84
https://docs.oracle.com/javase/specs/jls/se17/html/jls-9.html#jls-9.7.4[defined by the Java specification] which may be
85
85
initially surprising:
@@ -101,7 +101,7 @@ typical use cases.
101
101
The {spring-framework-api}/lang/Contract.html[@Contract] annotation in the `org.springframework.lang` package
102
102
can be used to express complementary semantics to avoid non-relevant null-safety warnings in your codebase.
103
103
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]
105
105
annotation in the `org.springframework.lang` package can be used to specify that the method return value must be used.
106
106
107
107
[[null-safety-migrating]]
@@ -115,12 +115,12 @@ introduced in Spring Framework 5 when JSpecify did not exist and the best option
115
115
but widespread JSR) meta-annotations. They are deprecated as of Spring Framework 7 in favor of
116
116
https://jspecify.dev/docs/start-here/[JSpecify] annotations, which provide significant enhancements such as properly
117
117
defined 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.
119
119
120
120
A key difference is that Spring null-safety annotations, following JSR 305 semantics, apply to fields,
121
121
parameters 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.
124
124
125
125
That means array and varargs null-safety declarations have to be updated to keep the same semantic. For example
126
126
`@Nullable Object[] array` with Spring annotations needs to be changed to `Object @Nullable [] array` with JSpecify
0 commit comments