From 12ef367f892f4886895c609b72f16c4938599234 Mon Sep 17 00:00:00 2001 From: Sebastien Deleuze Date: Tue, 26 Sep 2017 14:49:14 +0200 Subject: [PATCH] Polish reference documentation --- src/docs/asciidoc/core/core-null-safety.adoc | 71 ++++++++++---------- src/docs/asciidoc/kotlin.adoc | 21 +++--- 2 files changed, 46 insertions(+), 46 deletions(-) diff --git a/src/docs/asciidoc/core/core-null-safety.adoc b/src/docs/asciidoc/core/core-null-safety.adoc index 36bbe252b1b..a2603a706ea 100644 --- a/src/docs/asciidoc/core/core-null-safety.adoc +++ b/src/docs/asciidoc/core/core-null-safety.adoc @@ -2,38 +2,8 @@ = Null-safety Although Java does not allow to express null-safety with its type system, Spring Framework -now provides annotations to declare nullability of APIs and 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. Nullability of -types used inside method bodies is outside of the scope of this feature. - -These annotations are meta-annotated with https://jcp.org/en/jsr/detail?id=305[JSR 305] -annotations (a dormant JSR but supported by tools like IntelliJ IDEA) to provide useful -warnings to Java developers related to null-safety in order to avoid `NullPointerException` -at runtime. JSR 305 meta-annotations allows tooling vendors to provide null-safety support -in a generic way, without having to hard-code support for Spring annotations. - -[NOTE] -==== -It is not necessary nor recommanded to have JSR 305 dependency in project classpath to -take advatange of Spring null-safe API. Only projects like -Spring-based libraries using 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. -==== - -They are also used by Kotlin which supports natively -https://kotlinlang.org/docs/reference/null-safety.html[null-safety]. More details are -available in <>. - -[NOTE] -==== -Other libraries like Reactor or Spring Data leverage these annotations as well to provide -null-safe APIs. -==== - -The following annotations are provided in the `org.springframework.lang` package: +now provides following annotations in the `org.springframework.lang` package to declare +nullability of APIs and fields: * {api-spring-framework}/lang/NonNull.html[`@NonNull`] annotation where specific parameter, return value or field cannot be `null` (not needed on parameter and return value @@ -45,8 +15,39 @@ The following annotations are provided in the `org.springframework.lang` package * {api-spring-framework}/lang/NonNullFields.html[`@NonNullFields`] annotation at package level 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 https://jira.spring.io/browse/SPR-15942[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] ==== -Generic type arguments, varargs and array elements nullability are not supported yet, -see https://jira.spring.io/browse/SPR-15942[SPR-15942] for up-to-date information. -==== \ No newline at end of file +Libraries like Reactor or Spring Data provide null-safe APIs leveraging this feature. +==== + +== Use cases + +In addition to providing an explicit declaration for Spring Framework API nullability, +these annotation can be used by IDE (such as IDEA or Eclipse) to provide useful +warnings to Java developers 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 https://kotlinlang.org/docs/reference/null-safety.html[null-safety]. More details +are available in <>. + +== JSR 305 meta-annotations + +Spring annotations are meta-annotated with https://jcp.org/en/jsr/detail?id=305[JSR 305] +annotations (a dormant but widely spread JSR). JSR 305 meta-annotations allows tooling vendors +like IDEA or Kotlin to 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 project classpath to +take advantage of Spring null-safe API. Only projects like +Spring-based libraries using 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. diff --git a/src/docs/asciidoc/kotlin.adoc b/src/docs/asciidoc/kotlin.adoc index ad89b461f8c..fb771ddd48d 100644 --- a/src/docs/asciidoc/kotlin.adoc +++ b/src/docs/asciidoc/kotlin.adoc @@ -95,27 +95,26 @@ By default, types from Java APIs used in Kotlin are recognized as https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types[platform types] for which null-checks are relaxed. https://github.com/Kotlin/KEEP/blob/jsr-305/proposals/jsr-305-custom-nullability-qualifiers.md[Kotlin support for JSR 305 annotations] -available as of https://blog.jetbrains.com/kotlin/2017/08/kotlin-1-1-4-is-out/[1.1.4 release] + 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] ==== -Other libraries like Reactor and Spring Data leverage these annotations as well to provide -null-safe APIs for Kotlin developers. +Libraries like Reactor or Spring Data provide null-safe APIs leveraging this feature. ==== The JSR 305 checks can be configured by adding the `-Xjsr305` compiler flag with the following options: `-Xjsr305={strict|warn|ignore}`. -For kotlin versions 1.1.50+/1.2, the default behavior is the same to `-Xjsr305=warn`. The -`strict` value should be considered experimental (Spring API nullability could evolve and -more checks may be added in the future). +For kotlin versions 1.1.50+, the default behavior is the same to `-Xjsr305=warn`. The +`strict` value should be considered experimental (Spring API nullability declaration could +evolve even between minor releases and more checks may be added in the future). [NOTE] ==== Generic type arguments, varargs and array elements nullability are not supported yet, -see https://jira.spring.io/browse/SPR-15942[SPR-15942] for up-to-date information. +but should be in an upcoming release, see https://jira.spring.io/browse/SPR-15942[SPR-15942] +for up-to-date information. ==== [[classes-interfaces]] @@ -127,7 +126,7 @@ with default values. Kotlin parameter names are recognized via a dedicated `KotlinReflectionParameterNameDiscoverer` which allows finding interface method parameter names without requiring the Java 8 `-parameters` -compiler flag enabled during compliation. +compiler flag enabled during compilation. https://github.com/FasterXML/jackson-module-kotlin[Jackson Kotlin module] which is required for serializing / deserializing JSON data is automatically registered when @@ -390,9 +389,9 @@ plugin. [NOTE] ==== -As of Kay release train, Spring Data supports Kotlin immutable class instances and should -not require `kotlin-noarg` plugin if the underlying persistence solution allows it -(for example with MongoDB). +As of Kay release train, Spring Data supports Kotlin immutable class instances +and should not require `kotlin-noarg` plugin if the module leverages Spring Data object +mapping (like with MongoDB, Redis, Cassandra, etc.). ==== === Injecting dependencies