Author: kwin
Date: Fri Feb 20 10:34:30 2015
New Revision: 1661083
URL: http://svn.apache.org/r1661083
Log:
SLING-4377 add documentation on how to leverage the JSR-305 annotations
Added:
sling/site/trunk/content/documentation/development/eclipse-settings-null-analysis.png
(with props)
sling/site/trunk/content/documentation/development/jsr-305.mdtext
Modified:
sling/site/trunk/content/documentation/development.mdtext
Modified: sling/site/trunk/content/documentation/development.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/development.mdtext?rev=1661083&r1=1661082&r2=1661083&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/development.mdtext (original)
+++ sling/site/trunk/content/documentation/development.mdtext Fri Feb 20
10:34:30 2015
@@ -14,6 +14,7 @@ Look here for more information on develo
* [Monitoring Requests]({{ refs.monitoring-requests.path }})
* [Repository Based Development]({{ refs.repository-based-development.path }})
* [Sling IDE Tooling]({{ refs.ide-tooling.path }})
+* [Leveraging JSR-305 null annotations]({{refs.jsr-305.path}})
## Testing Sling-based Applications
Added:
sling/site/trunk/content/documentation/development/eclipse-settings-null-analysis.png
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/development/eclipse-settings-null-analysis.png?rev=1661083&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
sling/site/trunk/content/documentation/development/eclipse-settings-null-analysis.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: 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=1661083&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/development/jsr-305.mdtext (added)
+++ sling/site/trunk/content/documentation/development/jsr-305.mdtext Fri Feb
20 10:34:30 2015
@@ -0,0 +1,55 @@
+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.
+
+
+## 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`
+1. `javax.annotation.Nonnull`
+
+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
+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
+
+* `javax.annotation.CheckForNull` as **'Nullable' annotation**
+* `javax.annotation.Nonnull` as ** **'NonNull' annotation**
+
+
+
+## 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
+* NoteUnconditionalParamDerefs
+* FindNullDeref
+* FindNullDerefsInvolvingNonShortCircuitEvaluation
+
+Findbugs is also integrated in
[Sonarqube](http://docs.sonarqube.org/display/SONAR/Findbugs+Plugin).
+
+## 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
+ <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>
\ No newline at end of file
