You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bu...@apache.org on 2015/02/20 11:34:44 UTC
svn commit: r940841 - in /websites/staging/sling/trunk/content: ./
documentation/development.html
documentation/development/eclipse-settings-null-analysis.png
documentation/development/jsr-305.html
Author: buildbot
Date: Fri Feb 20 10:34:43 2015
New Revision: 940841
Log:
Staging update by buildbot for sling
Added:
websites/staging/sling/trunk/content/documentation/development/eclipse-settings-null-analysis.png (with props)
websites/staging/sling/trunk/content/documentation/development/jsr-305.html
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/development.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Feb 20 10:34:43 2015
@@ -1 +1 @@
-1660871
+1661083
Modified: websites/staging/sling/trunk/content/documentation/development.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/development.html (original)
+++ websites/staging/sling/trunk/content/documentation/development.html Fri Feb 20 10:34:43 2015
@@ -101,6 +101,7 @@
<li><a href="/documentation/development/monitoring-requests.html">Monitoring Requests</a></li>
<li><a href="/documentation/development/repository-based-development.html">Repository Based Development</a></li>
<li><a href="/documentation/development/ide-tooling.html">Sling IDE Tooling</a></li>
+<li><a href="/documentation/development/jsr-305.html">Leveraging JSR-305 null annotations</a></li>
</ul>
<h2 id="testing-sling-based-applications">Testing Sling-based Applications</h2>
<ul>
@@ -130,7 +131,7 @@
<li>A Sonar analysis is available on the <a href="https://analysis.apache.org/dashboard/index/org.apache.sling:sling-builder">analysis.apache.org</a> server.</li>
</ul>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1631433 by sseifert on Mon, 13 Oct 2014 15:01:38 +0000
+ Rev. 1661083 by kwin on Fri, 20 Feb 2015 10:34:30 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
Added: websites/staging/sling/trunk/content/documentation/development/eclipse-settings-null-analysis.png
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/sling/trunk/content/documentation/development/eclipse-settings-null-analysis.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: websites/staging/sling/trunk/content/documentation/development/jsr-305.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/development/jsr-305.html (added)
+++ websites/staging/sling/trunk/content/documentation/development/jsr-305.html Fri Feb 20 10:34:43 2015
@@ -0,0 +1,149 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - Leveraging JSR-305 null annotations to prevent NullPointerExceptions</title>
+ <link rel="icon" href="/res/favicon.ico">
+ <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
+ <link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/">
+ <img border="0" alt="Apache Sling" src="/res/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="/res/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong><a href="/documentation.html">Documentation</a></strong> <br />
+<a href="/documentation/getting-started.html">Getting Started</a> <br />
+<a href="/documentation/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/documentation/development.html">Development</a> <br />
+<a href="/documentation/bundles.html">Bundles</a> <br />
+<a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/documentation/configuration.html">Configuration</a> </p>
+<p><a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> </p>
+<p><strong>API Docs</strong> <br />
+<a href="/apidocs/sling7/index.html">Sling 7</a> <br />
+<a href="/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="/apidocs/sling5/index.html">Sling 5</a> </p>
+<p><strong>Project info</strong> <br />
+<a href="/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://ci.apache.org/builders/sling-trunk">Build Server</a> <br />
+<a href="/project-information/security.html">Security</a> </p>
+<p><strong>Source</strong> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a> <br />
+<a href="git://git.apache.org/sling.git">Git</a> <br />
+<a href="https://github.com/apache/sling">Github Mirror</a> </p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> </p>
+<p><strong><a href="/sitemap.html">Site Map</a></strong></p>
+<!-- no valid ads for now, we'll reactivate this when needed
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+-->
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/development.html">Development</a>
+ </div>
+
+
+
+ <h1>Leveraging JSR-305 null annotations to prevent NullPointerExceptions</h1>
+ <p>The Sling API forces developers to sometimes check for <code>null</code> return values. Most prominently this is the case for <a href="https://sling.apache.org/apidocs/sling7/org/apache/sling/api/adapter/Adaptable.html#adaptTo-java.lang.Class-"><code>Adaptable.adaptTo</code></a> and <a href="https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#getResource-java.lang.String-"><code>ResourceResolver.getResource</code></a>. This is often forgotten, which may lead to <code>NullPointerException</code>s. Sling API 2.9.0 introduced the JSR-305 annotations (<a href="https://issues.apache.org/jira/browse/SLING-4377">SLING-4377</a>) which allow tools to check automatically for missing null checks in the code.</p>
+<h2 id="annotations">Annotations</h2>
+<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>
+</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>
+<h2 id="use-with-eclipse">Use With Eclipse</h2>
+<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&anchor=null_analysis">null analysis based on any annotations</a>. Those need to be enabled in
+<em>Preferences->Java->Compiler->Errors/Warnings</em> via <strong>Enable annoation-based null analysis</strong>.
+Also the annotations need to be configured. For Sling those are</p>
+<ul>
+<li><code>javax.annotation.CheckForNull</code> as <strong>'Nullable' annotation</strong></li>
+<li><code>javax.annotation.Nonnull</code> as <strong> </strong>'NonNull' annotation**</li>
+</ul>
+<p><img alt="Eclipse Settings for Null analysis" src="eclipse-settings-null-analysis.png" /></p>
+<h2 id="use-with-findbugs">Use With Findbugs</h2>
+<p>Findbugs evaluates the used annotations by default. You can restrict the rules to only the ones which check for those annotations, which are</p>
+<ul>
+<li>InconsistentAnnotations</li>
+<li>NoteUnconditionalParamDerefs</li>
+<li>FindNullDeref</li>
+<li>FindNullDerefsInvolvingNonShortCircuitEvaluation</li>
+</ul>
+<p>Findbugs is also integrated in <a href="http://docs.sonarqube.org/display/SONAR/Findbugs+Plugin">Sonarqube</a>.</p>
+<h2 id="use-with-maven">Use With Maven</h2>
+<p>You can also let Maven automatically run Findbugs to execute those checks via the <strong>findbugs-maven-plugin</strong>. For that just add the following plugin to your <code>pom.xml</code></p>
+<div class="codehilite"><pre><span class="nt"><plugin></span>
+ <span class="nt"><groupId></span>org.codehaus.mojo<span class="nt"></groupId></span>
+ <span class="nt"><artifactId></span>findbugs-maven-plugin<span class="nt"></artifactId></span>
+ <span class="nt"><version></span>3.0.0<span class="nt"></version></span>
+ <span class="nt"><configuration></span>
+ <span class="nt"><visitors></span>InconsistentAnnotations,NoteUnconditionalParamDerefs,FindNullDeref,FindNullDerefsInvolvingNonShortCircuitEvaluation<span class="nt"></visitors></span>
+ <span class="nt"></configuration></span>
+ <span class="nt"><executions></span>
+ <span class="nt"><execution></span>
+ <span class="nt"><id></span>run-findbugs-fornullchecks<span class="nt"></id></span>
+ <span class="nt"><goals></span>
+ <span class="nt"><goal></span>check<span class="nt"></goal></span>
+ <span class="nt"></goals></span>
+ <span class="nt"></execution></span>
+ <span class="nt"></executions></span>
+<span class="nt"></plugin></span>
+</pre></div>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1661083 by kwin on Fri, 20 Feb 2015 10:34:30 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>