sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1661083 - in /sling/site/trunk/content/documentation: development.mdtext development/eclipse-settings-null-analysis.png development/jsr-305.mdtext
Date Fri, 20 Feb 2015 10:34:30 GMT
Author: kwin
Date: Fri Feb 20 10:34:30 2015
New Revision: 1661083

SLING-4377 add documentation on how to leverage the JSR-305 annotations

  (with props)

Modified: sling/site/trunk/content/documentation/development.mdtext
--- 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
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
--- 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
@@ -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`](
and [`ResourceResolver.getResource`](
This is often forgotten, which may lead to `NullPointerException`s. Sling API 2.9.0 introduced
the JSR-305 annotations ([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](
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](
+Due to the fact that Eclipse and FindBugs are interpreting annotations differently ([Findbugs-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](
Those need to be enabled in 
+*Preferences->Java->Compiler->Errors/Warnings* via **Enable annoation-based null
+Also the annotations need to be configured. For Sling those are
+* `javax.annotation.CheckForNull` as **'Nullable' annotation**
+* `javax.annotation.Nonnull` as ** **'NonNull' annotation**
+![Eclipse Settings for Null analysis](eclipse-settings-null-analysis.png)
+## 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](
+## 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

View raw message