Author: kwin
Date: Mon Mar 6 14:33:24 2017
New Revision: 1785656
URL: http://svn.apache.org/viewvc?rev=1785656&view=rev
Log:
add information about SonarQube and external annotations in Eclipse
Modified:
sling/site/trunk/content/documentation/development/jsr-305.mdtext
Modified: sling/site/trunk/content/documentation/development/jsr-305.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/development/jsr-305.mdtext?rev=1785656&r1=1785655&r2=1785656&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/development/jsr-305.mdtext (original)
+++ sling/site/trunk/content/documentation/development/jsr-305.mdtext Mon Mar
6 14:33:24 2017
@@ -1,9 +1,11 @@
Title: Leveraging JSR-305 null annotations to prevent NullPointerExceptions
-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/sling7/org/apache/sling/api/adapter/Adaptable.html#adaptTo-java.lang.Class-)
and
[`ResourceResolver.getResource`](https://sling.apache.org/apidocs/sling7/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 introduced the JSR-305 annotations
([SLING-4377](https://issues.apache.org/jira/browse/SLING-4377)) which allow
tools to check automatically for missing null checks in the code.
+[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/sling7/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 introduced the JSR-305 annotations
([SLING-4377](https://issues.apache.org/jira/browse/SLING-4377)) which allow
tools to check automatically for missing null checks in the code.
-## Annotations
+# 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:
@@ -13,7 +15,7 @@ Due to the fact that Eclipse and FindBug
Annotations which support setting the default null semantics of return values
and or parameters on a package level cannot be leveraged for that reason.
-## Use With Eclipse
+# 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 those are
@@ -23,12 +25,14 @@ Also the annotations need to be configur
-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 still Eclipse will emit a warning like *The expression of type 'String'
needs unchecked conversion to conform to '@Nonnull String'*. The only known
workaround is to disable the **"Unchecked conversion from non-annotated type to
@NonNull type"** or to annotate also the field with `
-@Nonnull`.
+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 still Eclipse will emit a warning like *The expression of type 'String'
needs unchecked conversion to conform to '@Nonnull String'*. The only known
workaround is to disable the **"Unchecked conversion from non-annotated type to
@NonNull type"** or to annotate also the field with `@Nonnull`.
More information are available at
[https://wiki.eclipse.org/JDT_Core/Null_Analysis](https://wiki.eclipse.org/JDT_Core/Null_Analysis).
-## Use With Findbugs
+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).
+The former provides also some m2e extension to ease setting up the classpaths
with external annotations from within your pom.xml.
+
+# Use With Findbugs
Findbugs evaluates the used annotations by default. You can restrict the rules
to only the ones which check for those annotations, which are
* InconsistentAnnotations
@@ -38,9 +42,10 @@ Findbugs evaluates the used annotations
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).
+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 Maven
+# Use With Maven
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
@@ -63,4 +68,8 @@ You can also let Maven automatically run
-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`.
\ No newline at end of file
+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 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.
\ No newline at end of file
