Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update null-safety documentation

Browse Source 
This commit documents using JSpecify instead of the now deprecated
Spring null-safety annotations.

Closes gh-28797
This commit is contained in:
Sébastien Deleuze
2024-12-16 12:01:25 +01:00
parent b3586560c1
commit 6d2d10cffe
2 changed files with 122 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
framework-docs/modules/ROOT/pages/languages/kotlin/null-safety.adoc
View File

@@ -5,34 +5,11 @@ One of Kotlin's key features is {kotlin-docs}/null-safety.html[null-safety],
which cleanly deals with `null` values at compile time rather than bumping into the famous
`NullPointerException` at runtime. This makes applications safer through nullability
declarations and expressing "`value or no value`" semantics without paying the cost of wrappers, such as `Optional`.
(Kotlin allows using functional constructs with nullable values. See this
{baeldung-blog}/kotlin-null-safety[comprehensive guide to Kotlin null-safety].)
Kotlin allows using functional constructs with nullable values. See this
{baeldung-blog}/kotlin-null-safety[comprehensive guide to Kotlin null-safety].
Although Java does not let you express null-safety in its type-system, the Spring Framework
provides xref:languages/kotlin/null-safety.adoc[null-safety of the whole Spring Framework API]
via tooling-friendly annotations declared in the `org.springframework.lang` package.
By default, types from Java APIs used in Kotlin are recognized as
{kotlin-docs}/java-interop.html#null-safety-and-platform-types[platform types],
for which null-checks are relaxed.
{kotlin-docs}/java-interop.html#jsr-305-support[Kotlin support for JSR-305 annotations]
and Spring nullability annotations provide null-safety for the whole Spring Framework API to Kotlin developers,
with the advantage of dealing with `null`-related issues at compile time.
NOTE: Libraries such as Reactor or Spring Data provide null-safe APIs to leverage this feature.
You can configure JSR-305 checks by adding the `-Xjsr305` compiler flag with the following
options: `-Xjsr305={strict|warn|ignore}`.
For kotlin versions 1.1+, the default behavior is the same as `-Xjsr305=warn`.
The `strict` value is required to have Spring Framework API null-safety taken into account
in Kotlin types inferred from Spring API but should be used with the knowledge that Spring
API nullability declaration could evolve even between minor releases and that more checks may
be added in the future.
NOTE: Generic type arguments, varargs, and array elements nullability are not supported yet,
but should be in an upcoming release. See {kotlin-github-org}/KEEP/issues/79[this discussion]
for up-to-date information.
provides xref:core/null-safety.adoc[null-safety of the whole Spring Framework API]
via tooling-friendly https://jspecify.dev/[JSpecify] annotations.
As of Kotlin 2.1, Kotlin enforces strict handling of nullability annotations from `org.jspecify.annotations` package.