root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

Polish reference documentation

This commit is contained in:
Sebastien Deleuze 2017-09-26 14:49:14 +02:00
parent 6f2d58fac6
commit 12ef367f89
2 changed files with 46 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
src/docs/asciidoc/core/core-null-safety.adoc
View File

@ -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 <<kotlin#null-safety,Kotlin support documentation>>.
[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.
====
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 <<kotlin#null-safety,Kotlin support documentation>>.
== 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.

21
src/docs/asciidoc/kotlin.adoc
View File

@ -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