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 2014/12/10 13:43:15 UTC
svn commit: r932172 - in /websites/staging/sling/trunk/content: ./
documentation/bundles/models.html documentation/bundles/validation.html
Author: buildbot
Date: Wed Dec 10 12:43:15 2014
New Revision: 932172
Log:
Staging update by buildbot for sling
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/bundles/models.html
websites/staging/sling/trunk/content/documentation/bundles/validation.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Dec 10 12:43:15 2014
@@ -1 +1 @@
-1644098
+1644385
Modified: websites/staging/sling/trunk/content/documentation/bundles/models.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles/models.html (original)
+++ websites/staging/sling/trunk/content/documentation/bundles/models.html Wed Dec 10 12:43:15 2014
@@ -94,7 +94,11 @@
<ul>
<li><a href="#design-goals">Design Goals</a></li>
<li><a href="#basic-usage">Basic Usage</a></li>
-<li><a href="#client-code">Client Code</a></li>
+<li><a href="#client-code">Client Code</a><ul>
+<li><a href="#adaptto">adaptTo()</a></li>
+<li><a href="#modelfactory-since-120">ModelFactory (since 1.2.0)</a></li>
+</ul>
+</li>
<li><a href="#other-options">Other Options</a><ul>
<li><a href="#names">Names</a></li>
<li><a href="#optional-and-required">Optional and Required</a></li>
@@ -105,6 +109,7 @@
<li><a href="#via">Via</a></li>
<li><a href="#source">Source</a></li>
<li><a href="#adaptations">Adaptations</a></li>
+<li><a href="#wzxhzdk25wzxhzdk26sling-validation-since-120"><a name="validation"></a>Sling Validation (since 1.2.0)</a></li>
</ul>
</li>
<li><a href="#custom-injectors">Custom Injectors</a></li>
@@ -182,6 +187,7 @@ can be listed in a comma-separated list
<h1 id="client-code">Client Code</h1>
+<h2 id="adaptto">adaptTo()</h2>
<p>Client code doesn't need to be aware that Sling Models is being used. It just uses the Sling Adapter framework:</p>
<div class="codehilite"><pre><span class="n">MyModel</span> <span class="n">model</span> <span class="o">=</span> <span class="n">resource</span><span class="o">.</span><span class="na">adaptTo</span><span class="o">(</span><span class="n">MyModel</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
</pre></div>
@@ -198,6 +204,19 @@ can be listed in a comma-separated list
<p>As with other AdapterFactories, if the adaptation can't be made for any reason, <code>adaptTo()</code> returns null.</p>
+<h2 id="modelfactory-since-120">ModelFactory (since 1.2.0)</h2>
+<p>Since Sling Models 1.2.0 (<a href="https://issues.apache.org/jira/browse/SLING-3709">SLING-3709</a>) there is another way of instanciating models. The OSGi service <code>ModelFactory</code> provides a method for instanciating a model that throws exceptions in case the model cannot be instanciated. That way <code>null</code> checks are not necessary.</p>
+<div class="codehilite"><pre><span class="k">try</span> <span class="o">{</span>
+ <span class="n">MyModel</span> <span class="n">model</span> <span class="o">=</span> <span class="n">modelFactory</span><span class="o">.</span><span class="na">createModel</span><span class="o">(</span><span class="n">resource</span><span class="o">,</span> <span class="n">MyModel</span><span class="o">.</span><span class="na">class</span><span class="o">);</span>
+<span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">Exception</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">// give out error message that the model could not be instanciated. </span>
+ <span class="c1">// The exception contains further information. </span>
+ <span class="c1">// See the javadoc of the ModelFactory for which Exception can be expected here</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>In addition <code>ModelFactory</code> provides methods for checking whether a given class is a model at all (having the model annotation) or whether a class can be adapted from a given adaptable.</p>
<h1 id="other-options">Other Options</h1>
<h2 id="names">Names</h2>
<p>If the field or method name doesn't exactly match the property name, <code>@Named</code> can be used:</p>
@@ -399,6 +418,45 @@ strategy by using adding <code>defaultIn
</pre></div>
+<h2 id="wzxhzdk25wzxhzdk26sling-validation-since-120"><a name="validation"></a>Sling Validation (since 1.2.0)</h2>
+<p><em>See also <a href="https://issues.apache.org/jira/browse/SLING-4161">SLING-4161</a></em></p>
+<p>You can use the attribute <code>validation</code> on the Model annotation to enable validation of the resource being used by the Sling model through <a href="/documentation/bundles/validation.html">Sling Validation</a>. That field supports three different values:</p>
+<table>
+<thead>
+<tr>
+<th>Value</th>
+<th>Description</th>
+<th>Invalid validation model</th>
+<th>No validation model found</th>
+<th>Resource invalid according to model</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>DISABLED</code> (default)</td>
+<td>don't validate the resource bound to the Model</td>
+<td>Model instanciated</td>
+<td>Model instanciated</td>
+<td>Model instanciated</td>
+</tr>
+<tr>
+<td><code>REQUIRED</code></td>
+<td>enforce validation of the resource bound to the Model</td>
+<td>Model not instanciated</td>
+<td>Model not instanciated</td>
+<td>Model not instanciated</td>
+</tr>
+<tr>
+<td><code>OPTIONAL</code></td>
+<td>validate the resource bound to the Model (if a validation model is found)</td>
+<td>Model not instanciated</td>
+<td>Model instanciated</td>
+<td>Model not instanciated</td>
+</tr>
+</tbody>
+</table>
+<p>In case the model is not instanciated an appropriate error message is logged (if the model is instanciated through the <code>adaptTo()</code> method or an appropriate exception is thrown if the model is instanciated through <code>ModelFactory.createModel()</code>).
+Validation is only supported on models which are adapted from a <code>Resource</code> and if the Sling Validation Bundle is deployed.</p>
<h1 id="custom-injectors">Custom Injectors</h1>
<p>To create a custom injector, simply implement the <code>org.apache.sling.models.spi.Injector</code> interface and register your implementation with the OSGi service registry. Please refer to the standard injectors in <a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/models/impl/src/main/java/org/apache/sling/models/impl/injectors/">Subversion</a> for examples.</p>
<p>Injectors are invoked in order of their service ranking, from lowest to highest. See the table below for the rankings of the standard injectors.</p>
@@ -531,7 +589,7 @@ strategy by using adding <code>defaultIn
</tbody>
</table>
<h1 id="injector-specific-annotations-since-sling-models-impl-106">Injector-specific Annotations (Since Sling Models Impl 1.0.6)</h1>
-<p>See also <a href="https://issues.apache.org/jira/browse/SLING-3499">SLING-3499</a></p>
+<p><em>See also <a href="https://issues.apache.org/jira/browse/SLING-3499">SLING-3499</a></em></p>
<p>Sometimes it is desirable to use customized annotations which aggregate the standard annotations described above. This will generally have
the following advantages over using the standard annotations:</p>
<ul>
@@ -620,7 +678,7 @@ SPI interface which could use context to
content path context. If multiple implementations of the <code>ImplementationPicker</code> interface are present, they are queried
one after another in order of their service ranking property, the first one that picks an implementation wins.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1639376 by kwin on Thu, 13 Nov 2014 16:06:53 +0000
+ Rev. 1644385 by kwin on Wed, 10 Dec 2014 12:42:57 +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/bundles/validation.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles/validation.html (original)
+++ websites/staging/sling/trunk/content/documentation/bundles/validation.html Wed Dec 10 12:43:15 2014
@@ -98,7 +98,11 @@ This documentation is still work in prog
<ul>
<li><a href="#basic-usage">Basic Usage</a></li>
<li><a href="#validation-model-resources">Validation Model Resources</a></li>
-<li><a href="#usage-in-sling-models">Usage in Sling Models</a></li>
+<li><a href="#usage-in-sling-models">Usage in Sling Models</a><ul>
+<li><a href="#since-sling-models-120">Since Sling Models 1.2.0</a></li>
+<li><a href="#before-sling-models-120">Before Sling Models 1.2.0</a></li>
+</ul>
+</li>
<li><a href="#writing-validators">Writing Validators</a></li>
<li><a href="#references">References</a></li>
</ul>
@@ -106,12 +110,16 @@ This documentation is still work in prog
<p>Many Sling projects want to be able to validate both Resources and request parameters. Through the Sling Validation Bundle this is possible with the help of validation model resources which define validation rules for a certain resourceType.</p>
<h1 id="basic-usage">Basic Usage</h1>
<p>To validate a resource one first needs to get a <code>ValidationModel</code> and then validate the resource with that model. Both functionalities are provided by the <code>ValidationService</code> OSGi service:</p>
-<div class="codehilite"><pre><span class="n">ValidationModel</span> <span class="n">validationModel</span> <span class="o">=</span> <span class="n">validationService</span><span class="o">.</span><span class="na">getValidationModel</span><span class="o">(</span><span class="n">resource</span><span class="o">);</span>
-<span class="k">if</span> <span class="o">(</span><span class="n">validationModel</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
- <span class="n">ValidationResult</span> <span class="n">result</span> <span class="o">=</span> <span class="n">validationService</span><span class="o">.</span><span class="na">validate</span><span class="o">(</span><span class="n">resource</span><span class="o">,</span> <span class="n">validationModel</span><span class="o">);</span>
- <span class="k">if</span> <span class="o">(!</span><span class="n">result</span><span class="o">.</span><span class="na">isValid</span><span class="o">())</span> <span class="o">{</span>
- <span class="c1">// give out validation messages from result.get</span>
- <span class="o">}</span>
+<div class="codehilite"><pre><span class="k">try</span> <span class="o">{</span>
+ <span class="n">ValidationModel</span> <span class="n">validationModel</span> <span class="o">=</span> <span class="n">validationService</span><span class="o">.</span><span class="na">getValidationModel</span><span class="o">(</span><span class="n">resource</span><span class="o">);</span>
+ <span class="k">if</span> <span class="o">(</span><span class="n">validationModel</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">ValidationResult</span> <span class="n">result</span> <span class="o">=</span> <span class="n">validationService</span><span class="o">.</span><span class="na">validate</span><span class="o">(</span><span class="n">resource</span><span class="o">,</span> <span class="n">validationModel</span><span class="o">);</span>
+ <span class="k">if</span> <span class="o">(!</span><span class="n">result</span><span class="o">.</span><span class="na">isValid</span><span class="o">())</span> <span class="o">{</span>
+ <span class="c1">// give out validation messages from result.get</span>
+ <span class="o">}</span>
+ <span class="o">}</span>
+<span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">IllegalStateException</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">// give out error message that the validation model is invalid!</span>
<span class="o">}</span>
</pre></div>
@@ -227,8 +235,11 @@ This documentation is still work in prog
</tr>
</tbody>
</table>
-<h1 id="usage-in-sling-models">Usage in Sling Models</h1>
-<p>Until there is native support in Sling Models <a href="https://issues.apache.org/jira/browse/SLING-4161">SLING-4161</a>, one needs to call the validate method within the PostConstruct method of the according Sling Model</p>
+<h1 id="usage-in-sling-models">Usage in <a href="/documentation/bundles/models.html">Sling Models</a></h1>
+<h2 id="since-sling-models-120">Since Sling Models 1.2.0</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</h2>
+<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>
@@ -237,15 +248,20 @@ This documentation is still work in prog
<span class="nd">@PostConstruct</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">validate</span><span class="o">()</span> <span class="o">{</span>
+ <span class="k">try</span> <span class="o">{</span>
<span class="n">ValidationModel</span> <span class="n">validationModel</span> <span class="o">=</span> <span class="n">validation</span><span class="o">.</span><span class="na">getValidationModel</span><span class="o">(</span><span class="n">resource</span><span class="o">);</span>
<span class="k">if</span> <span class="o">(</span><span class="n">validationModel</span> <span class="o">==</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
<span class="n">LOG</span><span class="o">.</span><span class="na">warn</span><span class="o">(</span><span class="s">"No validation defined for resource '{}' with type '{}'"</span><span class="o">,</span> <span class="n">resource</span><span class="o">.</span><span class="na">getPath</span><span class="o">(),</span> <span class="n">resource</span><span class="o">.</span><span class="na">getResourceType</span><span class="o">());</span>
+
<span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
<span class="n">ValidationResult</span> <span class="n">result</span> <span class="o">=</span> <span class="n">validation</span><span class="o">.</span><span class="na">validate</span><span class="o">(</span><span class="n">resource</span><span class="o">,</span> <span class="n">validationModel</span><span class="o">);</span>
<span class="k">if</span> <span class="o">(!</span><span class="n">result</span><span class="o">.</span><span class="na">isValid</span><span class="o">())</span> <span class="o">{</span>
<span class="c1">// give out the validation result</span>
<span class="o">}</span>
<span class="o">}</span>
+ <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">IllegalStateException</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">LOG</span><span class="o">.</span><span class="na">warn</span><span class="o">(</span><span class="s">"Invalid validation model for resource '{}' with type '{}'"</span><span class="o">,</span> <span class="n">resource</span><span class="o">.</span><span class="na">getPath</span><span class="o">(),</span> <span class="n">resource</span><span class="o">.</span><span class="na">getResourceType</span><span class="o">());</span>
+ <span class="o">}</span>
<span class="o">}</span>
</pre></div>
@@ -260,7 +276,7 @@ That interface defines the method <code>
<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. 1642308 by kwin on Fri, 28 Nov 2014 15:01:24 +0000
+ Rev. 1644385 by kwin on Wed, 10 Dec 2014 12:42:57 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project