Author: buildbot
Date: Mon Mar 6 14:33:41 2017
New Revision: 1007821
Log:
Staging update by buildbot for sling
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/bundles/validation.html
websites/staging/sling/trunk/content/documentation/development/jsr-305.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Mar 6 14:33:41 2017
@@ -1 +1 @@
-1785614
+1785656
Modified:
websites/staging/sling/trunk/content/documentation/bundles/validation.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles/validation.html
(original)
+++ websites/staging/sling/trunk/content/documentation/bundles/validation.html
Mon Mar 6 14:33:41 2017
@@ -117,7 +117,10 @@ h2:hover > .headerlink, h3:hover > .head
<div class="toc">
<ul>
<li><a href="#prerequisites">Prerequisites</a></li>
-<li><a href="#basic-usage">Basic Usage</a></li>
+<li><a href="#basic-usage">Basic Usage</a><ul>
+<li><a href="#validationresult">ValidationResult</a></li>
+</ul>
+</li>
<li><a href="#validation-model-resources">Validation Model Resources</a><ul>
<li><a href="#validation-model-inheritance">Validation Model
Inheritance</a></li>
<li><a href="#precedence-of-validation-models">Precedence of Validation
Models</a></li>
@@ -179,6 +182,12 @@ h2:hover > .headerlink, h3:hover > .head
<p>All methods to retrieve a validation model support a boolean parameter
<code>considerResourceSuperTypeModels</code>. If this is set to true, the
validation model is not only being looked up for exactly the given resource
type but also for all its resource super types. The returned model is then a
merged model of all found validation model along the resource type
hierarchy.</p>
+<h2 id="validationresult">ValidationResult<a class="headerlink"
href="#validationresult" title="Permanent link">¶</a></h2>
+<p>The <code>ValidationResult</code> indicates whether a given
<code>Resource</code> or <code>ValueMap</code> is valid or invalid according to
a given validation model. In the latter case it aggregates one or more
<code>ValidationFailure</code>s. Each <code>ValidationFailure</code> is
encapsulating an error message and a severity. The severity may be set on the
following locations (where locations on top may overwrite severity from
locations below):
+1. validation model (per use case of a <code>Validator</code>)
+1. severity defined on the <code>Validator</code>
+1. the default severity (may be set through the OSGi configuration for PID
"org.apache.sling.validation.impl.ValidationServiceImpl", is 0 by default)</p>
+<p>You have to use a <code>ResourceBundle</code> (<a
href="/documentation/bundles/internationalization-support-i18n.html">Internationalization
Support</a>) to resolve the message for a specific locale. By default Sling
Validation comes only with English failure messages.</p>
<h1 id="validation-model-resources">Validation Model Resources<a
class="headerlink" href="#validation-model-resources" title="Permanent
link">¶</a></h1>
<p>The <code>ValidationModel</code> is constructed from resources with the
resourceType <strong>sling/validation/model</strong>. Those resources are
considered validation model resources if they are located below the Sling
ResourceResolver search paths (<em>/apps</em> and <em>/libs</em>).</p>
<p>The resources should have the following format:</p>
@@ -302,7 +311,7 @@ To overwrite some property or child from
<h2 id="since-sling-models-120">Since Sling Models 1.2.0<a class="headerlink"
href="#since-sling-models-120" title="Permanent link">¶</a></h2>
<p>See <a href="/documentation/bundles/models.html#validation">Sling Models
validation</a></p>
<h2 id="before-sling-models-120">Before Sling Models 1.2.0<a
class="headerlink" href="#before-sling-models-120" title="Permanent
link">¶</a></h2>
-<p>one needs to call the validate method within the PostConstruct method of
the according Sling Model</p>
+<p>One needs to call the validate method within the PostConstruct method of
the according Sling Model</p>
<div class="codehilite"><pre><span class="nd">@SlingObject</span>
<span class="kd">protected</span> <span class="n">Resource</span> <span
class="n">resource</span><span class="o">;</span>
@@ -358,7 +367,7 @@ Each validator needs to specify one type
<li><a
href="http://www.slideshare.net/raducotescu/apache-sling-generic-validation-framework";>Apache
Sling Generic Validation Framework, adaptTo 2014</a></li>
</ol>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1785139 by kwin on Thu, 2 Mar 2017 14:05:56 +0000
+ Rev. 1785620 by kwin on Mon, 6 Mar 2017 10:21:05 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
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
Mon Mar 6 14:33:41 2017
@@ -114,8 +114,19 @@ h2:hover > .headerlink, h3:hover > .head
visibility: hidden;
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink,
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink,
dt:hover > .elementid-permalink { visibility: visible }</style>
-<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<a class="headerlink" href="#annotations"
title="Permanent link">¶</a></h2>
+<div class="toc">
+<ul>
+<li><a href="#introduction">Introduction</a></li>
+<li><a href="#annotations">Annotations</a></li>
+<li><a href="#use-with-eclipse">Use With Eclipse</a></li>
+<li><a href="#use-with-findbugs">Use With Findbugs</a></li>
+<li><a href="#use-with-maven">Use With Maven</a></li>
+<li><a href="#use-with-sonarqube">Use with SonarQube</a></li>
+</ul>
+</div>
+<h1 id="introduction">Introduction<a class="headerlink" href="#introduction"
title="Permanent link">¶</a></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/sling8/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>
+<h1 id="annotations">Annotations<a class="headerlink" href="#annotations"
title="Permanent link">¶</a></h1>
<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>
@@ -123,7 +134,7 @@ h2:hover > .headerlink, h3:hover > .head
<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<a class="headerlink"
href="#use-with-eclipse" title="Permanent link">¶</a></h2>
+<h1 id="use-with-eclipse">Use With Eclipse<a class="headerlink"
href="#use-with-eclipse" title="Permanent link">¶</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&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>
@@ -134,7 +145,9 @@ Also the annotations need to be configur
<p><img alt="Eclipse Settings for Null analysis"
src="eclipse-settings-null-analysis.png" /></p>
<p>Unfortunately Eclipse cannot infer information about fields which are for
sure either null or not null (reasoning is available in <a
href="https://wiki.eclipse.org/JDT_Core/Null_Analysis/Options#Risks_of_flow_analysis_for_fields";>https://wiki.eclipse.org/JDT_Core/Null_Analysis/Options#Risks_of_flow_analysis_for_fields</a>
and <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=247564";>Eclipse Bug
247564</a>). This also affecs constants (static final fields) or enums which
are known to be non null, but still Eclipse will emit a warning like <em>The
expression of type 'String' needs unchecked conversion to conform to '@Nonnull
String'</em>. The only known workaround is to disable the <strong>"Unchecked
conversion from non-annotated type to @NonNull type"</strong> or to annotate
also the field with <code>@Nonnull</code>.</p>
<p>More information are available at <a
href="https://wiki.eclipse.org/JDT_Core/Null_Analysis";>https://wiki.eclipse.org/JDT_Core/Null_Analysis</a>.</p>
-<h2 id="use-with-findbugs">Use With Findbugs<a class="headerlink"
href="#use-with-findbugs" title="Permanent link">¶</a></h2>
+<p>Since Eclipse 4.5 (Mars) external annotations are supported as well (i.e.
annotations maintained outside of the source code of the libraries, e.g. for
the JRE, Apache Commons Lang). There are some external annotations being
mainted at <a href="http://www.lastnpe.org/";>lastnpe.org</a> and <a
href="https://github.com/tracecompass/tracecompass/tree/master/common/org.eclipse.tracecompass.common.core/annotations";>TraceCompass</a>.
+The former provides also some m2e extension to ease setting up the classpaths
with external annotations from within your pom.xml.</p>
+<h1 id="use-with-findbugs">Use With Findbugs<a class="headerlink"
href="#use-with-findbugs" title="Permanent link">¶</a></h1>
<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>
@@ -143,8 +156,9 @@ Also the annotations need to be configur
<li>FindNullDerefsInvolvingNonShortCircuitEvaluation</li>
</ul>
<p>A complete list of visitors class names in Findbugs can be found in the <a
href="https://code.google.com/p/findbugs/source/browse/#git%2Ffindbugs%2Fsrc%2Fjava%2Fedu%2Fumd%2Fcs%2Ffindbugs%2Fdetect%253Fstate%253Dclosed";>sourcecode</a>.
The according <a
href="http://findbugs.sourceforge.net/bugDescriptions.html";>bug patterns</a>
have an identifier (in parenthesis) for which you can search in the according
Java classes, in case you want to extend the checks.</p>
-<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<a class="headerlink"
href="#use-with-maven" title="Permanent link">¶</a></h2>
+<p>Findbugs is also integrated in <a
href="http://docs.sonarqube.org/display/SONAR/Findbugs+Plugin";>SonarQube</a>
but for SonarQube you should now rather use the native Java plugin
+(look at <a href="#use-with-sonarqube">Use with SonarQube</a>).</p>
+<h1 id="use-with-maven">Use With Maven<a class="headerlink"
href="#use-with-maven" title="Permanent link">¶</a></h1>
<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>
@@ -166,8 +180,10 @@ Also the annotations need to be configur
<p>The results are often very imprecise (<a
href="http://jira.codehaus.org/browse/MFINDBUGS-208";>MFINDBUGS-208</a>),
especially when it comes to line numbers, therefore it is best to start the
Findbugs GUI in case of errors found by this plugin via <code>mvn
findbugs:gui</code>.</p>
+<h1 id="use-with-sonarqube">Use with SonarQube<a class="headerlink"
href="#use-with-sonarqube" title="Permanent link">¶</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. 1666372 by kwin on Fri, 13 Mar 2015 08:33:27 +0000
+ Rev. 1785656 by kwin on Mon, 6 Mar 2017 14:33:24 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
