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 2017/03/06 14:33:41 UTC
svn commit: r1007821 - in /websites/staging/sling/trunk/content: ./
documentation/bundles/validation.html documentation/development/jsr-305.html
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