Skip to content

Commit e184860

Browse files
committed
Use "nullness" instead of "nullability"
This commit updates the null-safety documentation to use "nullness" instead of "nullability" in order to be consistent with the JSpecify documentation. See spring-projectsgh-28797
1 parent a3594e7 commit e184860

File tree

1 file changed

+11
-11
lines changed

1 file changed

+11
-11
lines changed

framework-docs/modules/ROOT/pages/core/null-safety.adoc

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22
= Null-safety
33

44
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
66
usages. Reading the https://jspecify.dev/docs/user-guide/[JSpecify user guide] is highly recommended in order to get
77
familiar with those annotations and semantics.
88

99
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
1111
both Java by leveraging some tooling (https://github.com/uber/NullAway[NullAway] or IDEs supporting null-safety
1212
annotations 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.
4040
The purpose of this section is to share some guidelines proposed for using JSpecify annotations in the context of
4141
Spring-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
4444
usages are by far more frequent than nullable ones. In order to keep codebases readable, we typically want to define
4545
that by default, type usages are non-null unless marked as nullable for a specific scope. This is exactly the purpose of
4646
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,
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
8383
the array itself. Pay attention to the syntax
8484
https://docs.oracle.com/javase/specs/jls/se17/html/jls-9.html#jls-9.7.4[defined by the Java specification] which may be
8585
initially surprising:
@@ -101,7 +101,7 @@ typical use cases.
101101
The {spring-framework-api}/lang/Contract.html[@Contract] annotation in the `org.springframework.lang` package
102102
can 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]
105105
annotation 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
115115
but widespread JSR) meta-annotations. They are deprecated as of Spring Framework 7 in favor of
116116
https://jspecify.dev/docs/start-here/[JSpecify] annotations, which provide significant enhancements such as properly
117117
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.
119119

120120
A key difference is that Spring null-safety annotations, following JSR 305 semantics, apply to fields,
121121
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.
124124

125125
That 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

Comments
 (0)