This is an automated email from the ASF dual-hosted git repository.
sseifert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git
The following commit(s) were added to refs/heads/master by this push:
new 1b54e14 SLING-7798 update null-analysis documentation
1b54e14 is described below
commit 1b54e14245e2f5c17e5ca84c47f08e622b5662a3
Author: sseifert <[email protected]>
AuthorDate: Sat Aug 18 13:43:41 2018 +0200
SLING-7798 update null-analysis documentation
---
.../jbake/content/documentation/development.md | 2 +-
.../content/documentation/development/jsr-305.md | 112 +--------------------
.../development/{jsr-305.md => null-analysis.md} | 27 +++--
3 files changed, 19 insertions(+), 122 deletions(-)
diff --git a/src/main/jbake/content/documentation/development.md
b/src/main/jbake/content/documentation/development.md
index 37538b7..a694bab 100644
--- a/src/main/jbake/content/documentation/development.md
+++ b/src/main/jbake/content/documentation/development.md
@@ -19,7 +19,7 @@ Look here for more information on developper support when
your are using Sling t
* [Monitoring Requests](/documentation/development/monitoring-requests.html)
* [Repository Based
Development](/documentation/development/repository-based-development.html)
* [Sling IDE Tooling](/documentation/development/ide-tooling.html)
-* [Leveraging JSR-305 null
annotations](/documentation/development/jsr-305.html)
+* [Leveraging @NotNull/@Nullable null
annotations](/documentation/development/null-analysis.html)
## Testing Sling-based Applications
diff --git a/src/main/jbake/content/documentation/development/jsr-305.md
b/src/main/jbake/content/documentation/development/jsr-305.md
index d3a65c2..88a2624 100644
--- a/src/main/jbake/content/documentation/development/jsr-305.md
+++ b/src/main/jbake/content/documentation/development/jsr-305.md
@@ -4,115 +4,7 @@ status=published
tags=development
~~~~~~
-[TOC]
+This page was moved to [Leveraging @NotNull/@Nullable annotations to prevent
NullPointerExceptions][null-analysis].
-# Introduction
-The Sling API forces developers to sometimes check for `null` return values.
Most prominently this is the case for
[`Adaptable.adaptTo`](https://sling.apache.org/apidocs/sling8/org/apache/sling/api/adapter/Adaptable.html#adaptTo-java.lang.Class-)
and
[`ResourceResolver.getResource`](https://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/ResourceResolver.html#getResource-java.lang.String-).
This is often forgotten, which may lead to `NullPointerException`s. Sling API
2.9.0 [...]
-# Annotations
-The annotations used within Sling are based on the
[JSR-305](https://jcp.org/en/jsr/detail?id=305) which is dormant since 2012.
Nevertheless those annotations are understood by most of the tools and used by
other Apache Projects like Apache Oak
[OAK-37](https://issues.apache.org/jira/browse/OAK-37).
-
-Due to the fact that Eclipse and FindBugs are interpreting annotations
differently ([Findbugs-1355](https://sourceforge.net/p/findbugs/bugs/1355/)).
Sling only uses the following two different annotations which are supported by
both tools:
-
-1. `javax.annotation.CheckForNull` (only on return values which may be `null`)
-1. `javax.annotation.Nonnull` (on return values and arguments which are never
supposed to be `null`)
-
-Annotations which support setting the default null semantics of return values
and or parameters on a package level cannot be leveraged for that reason.
-
-In case no annotations have been set on method arguments those accept `null`
as a value. Return values should always be explicitly annotated, as from both
cases checks can be derived.
-
-The annotations have a retention policy of `runtime`, therefore bundles using
these automatically have a `Import-Package` header listing `javax.annotation`.
That package is by default exported by the system bundle (as this package is
also part of the
[JRE](https://docs.oracle.com/javase/7/docs/api/javax/annotation/package-summary.html)).
To be able to resolve the bundle through this exported package from the system
bundle you should use the `com.google.code.findbugs:jsr305` artifact in v [...]
-
-# Use With Eclipse
-Eclipse since Juno supports [null analysis based on any
annotations](http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Freference%2Fpreferences%2Fjava%2Fcompiler%2Fref-preferences-errors-warnings.htm&anchor=null_analysis).
Those need to be enabled in
-*Preferences->Java->Compiler->Errors/Warnings* via **Enable annoation-based
null analysis**.
-Also the annotations need to be configured. For Sling/JSR 305 those are
-
-* `javax.annotation.CheckForNull` as **'Nullable' annotation** (primary
annotation)
-* `javax.annotation.Nonnull` as **'NonNull' annotation** (primary annotation)
-
-
-
-Unfortunately Eclipse cannot infer information about fields which are for sure
either null or not null (reasoning is available in
[https://wiki.eclipse.org/JDT_Core/Null_Analysis/Options#Risks_of_flow_analysis_for_fields](https://wiki.eclipse.org/JDT_Core/Null_Analysis/Options#Risks_of_flow_analysis_for_fields)
and [Eclipse Bug
247564](https://bugs.eclipse.org/bugs/show_bug.cgi?id=247564)). This also
affecs constants (static final fields) or enums which are known to be non null,
but stil [...]
-
-More information are available at
[https://wiki.eclipse.org/JDT_Core/Null_Analysis](https://wiki.eclipse.org/JDT_Core/Null_Analysis).
-
-Since Eclipse 4.5 (Mars) **external annotations** are supported as well (i.e.
annotations maintained outside of the source code of the libraries, e.g. for
the JRE, Apache Commons Lang). There are some external annotations being
mainted at [lastnpe.org](http://www.lastnpe.org/) and
[TraceCompass](https://github.com/tracecompass/tracecompass/tree/master/common/org.eclipse.tracecompass.common.core/annotations).
There is no official repository yet though ([Eclipse Bug
449653](https://bugs.ec [...]
-[Lastnpe.org](http://www.lastnpe.org/) provides also an m2e extension to ease
setting up the classpaths with external annotations from within your pom.xml.
-
-# Use With Maven
-
-## Leveraging Eclipse JDT Compiler (recommended)
-
-You can use Eclipse JDT also in Maven (with null analysis enabled) for the
regular compilation. That way it will give out the same warnings/errors as
Eclipse and will also consider external annotations.
-JDT in its most recent version is provided by the `tycho-compiler-plugin`
which can be hooked up with the `maven-compiler-plugin`.
-The full list of options for JDT is described in
[here](http://help.eclipse.org/neon/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Ftasks%2Ftask-using_batch_compiler.htm).
-This method was presented by Michael Vorburger in his presentation [The end of
the world as we know
it](https://www.slideshare.net/mikervorburger/the-end-of-the-world-as-we-know-it-aka-your-last-nullpointerexception-1b-bugs/14).
-
- ::xml
- <plugin>
- <artifactId>maven-compiler-plugin</artifactId>
- <version>3.5.1</version>
- <configuration>
- <source>1.8</source>
- <target>1.8</target>
- <showWarnings>true</showWarnings>
- <compilerId>jdt</compilerId>
- <compilerArguments>
- <!-- just take the full Maven classpath as external annotations -->
- <annotationpath>CLASSPATH</annotationpath>
- </compilerArguments>
- <!-- maintain the org.eclipse.jdt.core.prefs properties to options
listed on
-
http://help.eclipse.org/neon/index.jsp?topic=/org.eclipse.jdt.doc.user/tasks/task-using_batch_compiler.htm
-->
-
<compilerArgument>-err:nullAnnot,null,-missingNullDefault</compilerArgument>
- </configuration>
- <dependencies>
- <dependency>
- <groupId>org.eclipse.tycho</groupId>
- <artifactId>tycho-compiler-jdt</artifactId>
- <version>1.0.0</version>
- </dependency>
- </dependencies>
- </plugin>
-
-## Leveraging FindBugs
-You can also let Maven automatically run FindBugs to execute those checks via
the **findbugs-maven-plugin**. For that just add the following plugin to your
`pom.xml`
-
- ::xml
- <plugin>
- <groupId>org.codehaus.mojo</groupId>
- <artifactId>findbugs-maven-plugin</artifactId>
- <version>3.0.0</version>
- <configuration>
-
<visitors>InconsistentAnnotations,NoteUnconditionalParamDerefs,FindNullDeref,FindNullDerefsInvolvingNonShortCircuitEvaluation</visitors>
- </configuration>
- <executions>
- <execution>
- <id>run-findbugs-fornullchecks</id>
- <goals>
- <goal>check</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
-
-
-The results are often very imprecise
([MFINDBUGS-208](http://jira.codehaus.org/browse/MFINDBUGS-208)), especially
when it comes to line numbers, therefore it is best to start the Findbugs GUI
in case of errors found by this plugin via `mvn findbugs:gui`.
-
-
-# Use With FindBugs
-FindBugs evaluates the JSR-305 annotations by default. You can restrict the
rules to only the ones which check for those annotations, which are
-
-* InconsistentAnnotations
-* NoteUnconditionalParamDerefs
-* FindNullDeref
-* FindNullDerefsInvolvingNonShortCircuitEvaluation
-
-A complete list of visitors class names in Findbugs can be found in the
[sourcecode](https://code.google.com/p/findbugs/source/browse/#git%2Ffindbugs%2Fsrc%2Fjava%2Fedu%2Fumd%2Fcs%2Ffindbugs%2Fdetect%253Fstate%253Dclosed).
The according [bug
patterns](http://findbugs.sourceforge.net/bugDescriptions.html) have an
identifier (in parenthesis) for which you can search in the according Java
classes, in case you want to extend the checks.
-
-Findbugs is also integrated in
[SonarQube](http://docs.sonarqube.org/display/SONAR/Findbugs+Plugin) but for
SonarQube you should now rather use the native Java plugin
-(look at [Use with SonarQube](#use-with-sonarqube)).
-
-# Use with SonarQube
-
-At least rule
[squid:S2259](https://sonarqube.com/coding_rules#rule_key=squid%3AS2259) in
SonarQube supports JSR-305 annotations as well for null checks.
+[null-analysis]: /documentation/development/null-analysis.html
diff --git a/src/main/jbake/content/documentation/development/jsr-305.md
b/src/main/jbake/content/documentation/development/null-analysis.md
similarity index 78%
copy from src/main/jbake/content/documentation/development/jsr-305.md
copy to src/main/jbake/content/documentation/development/null-analysis.md
index d3a65c2..f0a094c 100644
--- a/src/main/jbake/content/documentation/development/jsr-305.md
+++ b/src/main/jbake/content/documentation/development/null-analysis.md
@@ -1,4 +1,4 @@
-title=Leveraging JSR-305 null annotations to prevent NullPointerExceptions
+title=Leveraging @NotNull/@Nullable annotations to prevent
NullPointerExceptions
type=page
status=published
tags=development
@@ -7,29 +7,30 @@ tags=development
[TOC]
# Introduction
-The Sling API forces developers to sometimes check for `null` return values.
Most prominently this is the case for
[`Adaptable.adaptTo`](https://sling.apache.org/apidocs/sling8/org/apache/sling/api/adapter/Adaptable.html#adaptTo-java.lang.Class-)
and
[`ResourceResolver.getResource`](https://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/ResourceResolver.html#getResource-java.lang.String-).
This is often forgotten, which may lead to `NullPointerException`s. Sling API
2.9.0 [...]
+
+The Sling API forces developers to sometimes check for `null` return values.
Most prominently this is the case for
[`Adaptable.adaptTo`](https://sling.apache.org/apidocs/sling8/org/apache/sling/api/adapter/Adaptable.html#adaptTo-java.lang.Class-)
and
[`ResourceResolver.getResource`](https://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/ResourceResolver.html#getResource-java.lang.String-).
This is often forgotten, which may lead to `NullPointerException`s. Sling API
2.9.0 [...]
# Annotations
-The annotations used within Sling are based on the
[JSR-305](https://jcp.org/en/jsr/detail?id=305) which is dormant since 2012.
Nevertheless those annotations are understood by most of the tools and used by
other Apache Projects like Apache Oak
[OAK-37](https://issues.apache.org/jira/browse/OAK-37).
-Due to the fact that Eclipse and FindBugs are interpreting annotations
differently ([Findbugs-1355](https://sourceforge.net/p/findbugs/bugs/1355/)).
Sling only uses the following two different annotations which are supported by
both tools:
+The annotations used within Sling are based on the [Jetbrains
Annotations][jetbrains-annotations-docs]. Although introduced by the company
that offers the IntelliJ IDEA IDE, those annotations are understood by most of
the tools and used by other Apache Projects like Apache Oak.
-1. `javax.annotation.CheckForNull` (only on return values which may be `null`)
-1. `javax.annotation.Nonnull` (on return values and arguments which are never
supposed to be `null`)
+Sling only uses the following two annotations:
-Annotations which support setting the default null semantics of return values
and or parameters on a package level cannot be leveraged for that reason.
+1. `org.jetbrains.annotations.NotNull` (on return values and arguments which
are never supposed to be `null`)
+2. `org.jetbrains.annotations.Nullable` (only on return values which may be
`null`)
-In case no annotations have been set on method arguments those accept `null`
as a value. Return values should always be explicitly annotated, as from both
cases checks can be derived.
+Annotations which support setting the default null semantics of return values
and or parameters on a package level are not used.
-The annotations have a retention policy of `runtime`, therefore bundles using
these automatically have a `Import-Package` header listing `javax.annotation`.
That package is by default exported by the system bundle (as this package is
also part of the
[JRE](https://docs.oracle.com/javase/7/docs/api/javax/annotation/package-summary.html)).
To be able to resolve the bundle through this exported package from the system
bundle you should use the `com.google.code.findbugs:jsr305` artifact in v [...]
+In case no annotations have been set on method arguments those accept `null`
as a value. Return values should always be explicitly annotated, as from both
cases checks can be derived.
# Use With Eclipse
+
Eclipse since Juno supports [null analysis based on any
annotations](http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Freference%2Fpreferences%2Fjava%2Fcompiler%2Fref-preferences-errors-warnings.htm&anchor=null_analysis).
Those need to be enabled in
*Preferences->Java->Compiler->Errors/Warnings* via **Enable annoation-based
null analysis**.
Also the annotations need to be configured. For Sling/JSR 305 those are
-* `javax.annotation.CheckForNull` as **'Nullable' annotation** (primary
annotation)
-* `javax.annotation.Nonnull` as **'NonNull' annotation** (primary annotation)
+* `org.jetbrains.annotations.NotNull` as **'Nullable' annotation** (primary
annotation)
+* `org.jetbrains.annotations.Nullable` as **'NonNull' annotation** (primary
annotation)
@@ -116,3 +117,7 @@ Findbugs is also integrated in
[SonarQube](http://docs.sonarqube.org/display/SON
# Use with SonarQube
At least rule
[squid:S2259](https://sonarqube.com/coding_rules#rule_key=squid%3AS2259) in
SonarQube supports JSR-305 annotations as well for null checks.
+
+
+
+[jetbrains-annotations-docs]:
https://www.jetbrains.com/help/idea/nullable-and-notnull-annotations.html
