svn commit: r1014784 - in /websites/staging/sling/trunk/content: ./ documentation/development/jsr-305.html

[bu...@apache.org]

Author: buildbot
Date: Fri Jun 30 15:13:00 2017
New Revision: 1014784

Log:
Staging update by buildbot for sling

Modified:
    websites/staging/sling/trunk/content/   (props changed)
    websites/staging/sling/trunk/content/documentation/development/jsr-305.html

Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Jun 30 15:13:00 2017
@@ -1 +1 @@
-1800271
+1800431

Modified: websites/staging/sling/trunk/content/documentation/development/jsr-305.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/development/jsr-305.html (original)
+++ websites/staging/sling/trunk/content/documentation/development/jsr-305.html Fri Jun 30 15:13:00 2017
@@ -135,10 +135,11 @@ h2:hover > .headerlink, h3:hover > .head
 <p>The annotations used within Sling are based on the <a href="https://jcp.org/en/jsr/detail?id=305">JSR-305</a> which is dormant since 2012. Nevertheless those annotations are understood by most of the tools and used by other Apache Projects like Apache Oak <a href="https://issues.apache.org/jira/browse/OAK-37">OAK-37</a>.</p>
 <p>Due to the fact that Eclipse and FindBugs are interpreting annotations differently (<a href="https://sourceforge.net/p/findbugs/bugs/1355/">Findbugs-1355</a>). Sling only uses the following two different annotations which are supported by both tools:</p>
 <ol>
-<li><code>javax.annotation.CheckForNull</code></li>
-<li><code>javax.annotation.Nonnull</code></li>
+<li><code>javax.annotation.CheckForNull</code> (only on return values which may be <code>null</code>)</li>
+<li><code>javax.annotation.Nonnull</code> (on return values and arguments which are never supposed to be <code>null</code>)</li>
 </ol>
 <p>Annotations which support setting the default null semantics of return values and or parameters on a package level cannot be leveraged for that reason.</p>
+<p>In case no annotations have been set on method arguments those accept <code>null</code> as a value. Return values should always be explicitly annotated, as from both cases checks can be derived.</p>
 <p>The annotations have a retention policy of <code>runtime</code>, therefore bundles using these automatically have a <code>Import-Package</code> header listing <code>javax.annotation</code>. That package is by default exported by the system bundle (as this package is also part of the <a href="https://docs.oracle.com/javase/7/docs/api/javax/annotation/package-summary.html">JRE</a>). To be able to resolve the bundle through this exported package from the system bundle you should use the <code>com.google.code.findbugs:jsr305</code> artifact in version 3.0.0 as that exports the package <code>javax.annotation</code> in no specific version. Newer versions use version directives which automatically restrict the version range for the generated <code>Import-Package</code> header to <code>[3,4)</code> <a href="https://github.com/amaembo/jsr-305/issues/31">which usually cannot be resolved at run time</a>.</p>
 <h1 id="use-with-eclipse">Use With Eclipse<a class="headerlink" href="#use-with-eclipse" title="Permanent link">&para;</a></h1>
 <p>Eclipse since Juno supports <a href="http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Freference%2Fpreferences%2Fjava%2Fcompiler%2Fref-preferences-errors-warnings.htm&amp;anchor=null_analysis">null analysis based on any annotations</a>. Those need to be enabled in 
@@ -222,7 +223,7 @@ This method was presented by Michael Vor
 <h1 id="use-with-sonarqube">Use with SonarQube<a class="headerlink" href="#use-with-sonarqube" title="Permanent link">&para;</a></h1>
 <p>At least rule <a href="https://sonarqube.com/coding_rules#rule_key=squid%3AS2259">squid:S2259</a> in SonarQube supports JSR-305 annotations as well for null checks.</p>
       <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
-        Rev. 1792488 by kwin on Mon, 24 Apr 2017 15:15:56 +0000
+        Rev. 1800431 by kwin on Fri, 30 Jun 2017 15:12:38 +0000
       </div>
       <div class="trademarkFooter"> 
         Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project