Although Java does not let you express null-safety with its type system, Spring Framework
now provides the following annotations in the org.springframework.lang
package to let you declare
nullability of APIs and fields:
-
{api-spring-framework}/lang/NonNull.html[
@NonNull
]: Annotation to indicate that a specific parameter, return value, or field cannot benull
(not needed on parameter and return value where@NonNullApi
and@NonNullFields
apply) . -
{api-spring-framework}/lang/Nullable.html[
@Nullable
]: Annotation to indicate that a specific parameter, return value, or field can benull
. -
{api-spring-framework}/lang/NonNullApi.html[
@NonNullApi
]: Annotation at the package level that declares non-null as the default behavior for parameters and return values. -
{api-spring-framework}/lang/NonNullFields.html[
@NonNullFields
]: Annotation at the package level that declares non-null as the default behavior for fields.
Spring Framework leverages itself these annotations, but they can also be used in any Spring based Java project to declare null-safe APIs and optionally null-safe fields. Generic type arguments, varargs and array elements nullability are not supported yet, but should be in an upcoming release, see SPR-15942 for up-to-date information. Nullability declaration are expected to be fine-tuned between Spring Framework release, including minor ones. Nullability of types used inside method bodies is outside of the scope of this feature.
Note
|
Libraries like Reactor or Spring Data provide null-safe APIs that use this feature. |
In addition to providing an explicit declaration for Spring Framework API nullability,
these annotations can be used by an IDE (such as IDEA or Eclipse) to provide useful
warnings related to null-safety in order to avoid NullPointerException
at runtime.
They are also used to make Spring API null-safe in Kotlin projects, since Kotlin natively supports null-safety. More details are available in the Kotlin support documentation.
Spring annotations are meta-annotated with JSR 305 annotations (a dormant but widely spread JSR). JSR 305 meta-annotations let tooling vendors like IDEA or Kotlin provide null-safety support in a generic way, without having to hard-code support for Spring annotations.
It is not necessary nor recommended to add JSR 305 dependency in the project classpath to
take advantage of Spring null-safe API. Only projects such as
Spring-based libraries that use null-safety annotations in their codebase should add
com.google.code.findbugs:jsr305:3.0.2
with compileOnly
Gradle configuration or Maven
provided
scope to avoid compile warnings.