sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From k...@apache.org
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

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**
+  
+![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](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



Mime
View raw message