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/11/24 11:39:38 UTC
svn commit: r930290 - in /websites/staging/sling/trunk/content: ./
documentation/bundles.html documentation/bundles/validation.html
Author: buildbot
Date: Mon Nov 24 10:39:37 2014
New Revision: 930290
Log:
Staging update by buildbot for sling
Added:
websites/staging/sling/trunk/content/documentation/bundles/validation.html
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/bundles.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Nov 24 10:39:37 2014
@@ -1 +1 @@
-1641357
+1641359
Modified: websites/staging/sling/trunk/content/documentation/bundles.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles.html (original)
+++ websites/staging/sling/trunk/content/documentation/bundles.html Mon Nov 24 10:39:37 2014
@@ -96,6 +96,7 @@
<li><a href="/documentation/bundles/internationalization-support-i18n.html">Internationalization Support (i18n)</a></li>
<li><a href="/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html">Manipulating Content - The SlingPostServlet (servlets.post)</a></li>
<li><a href="/documentation/bundles/rendering-content-default-get-servlets.html">Rendering Content - Default GET servlets (servlets.get)</a></li>
+<li><a href="/documentation/bundles/validation.html">Validation</a></li>
</ul>
<h2 id="resource-providers">Resource Providers</h2>
<ul>
@@ -144,7 +145,7 @@
<li><a href="/documentation/bundles/discovery-api-and-impl.html">Discovery API and its Implementations (discovery.api, discovery.impl)</a></li>
</ul>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1625708 by olli on Wed, 17 Sep 2014 17:18:14 +0000
+ Rev. 1641359 by kwin on Mon, 24 Nov 2014 10:39:29 +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/bundles/validation.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles/validation.html (added)
+++ websites/staging/sling/trunk/content/documentation/bundles/validation.html Mon Nov 24 10:39:37 2014
@@ -0,0 +1,240 @@
+<!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 - Sling Validation</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/bundles.html">Bundles</a>
+ </div>
+
+
+
+ <h1>Sling Validation</h1>
+ <div class="toc">
+<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="#writing-validators">Writing Validators</a></li>
+<li><a href="#references">References</a></li>
+</ul>
+</div>
+<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>
+<span class="o">}</span>
+</pre></div>
+
+
+<h1 id="validation-model-resources">Validation Model Resources</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</p>
+<ul>
+<li>below the Sling ResourceResolver search paths (<em>/apps</em> and <em>/libs</em>) <strong>and</strong></li>
+<li>below a node named <strong>validation</strong>.</li>
+</ul>
+<p>The resources should have the following format:</p>
+<table>
+<thead>
+<tr>
+<th>Property/Node Name</th>
+<th>Property or Resource</th>
+<th>Type</th>
+<th>Description</th>
+<th>Mandatory</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>sling:resourceType</code></td>
+<td>Property</td>
+<td><code>String</code></td>
+<td>Always <code>sling/validation/model</code>, otherwise node will never be picked up by Sling Validation.</td>
+<td>yes</td>
+</tr>
+<tr>
+<td><code>validatedResourceType</code></td>
+<td>Property</td>
+<td><code>String</code></td>
+<td>The resource type of the resource for which this validation model should be applied.</td>
+<td>yes</td>
+</tr>
+<tr>
+<td><code>applicablePaths</code></td>
+<td>Property</td>
+<td><code>String[]</code></td>
+<td>Path prefixes which restrict the validation model to resources which are below one of the given prefix. No wildcards are supported. If not given, there is not path restriction.</td>
+<td>no</td>
+</tr>
+<tr>
+<td><code>properties\<propertyName></code></td>
+<td>Resource</td>
+<td>-</td>
+<td>This resource ensures that the property with the name <code><propertyName></code> is there.</td>
+<td>no</td>
+</tr>
+<tr>
+<td><code>properties\<propertyName>\propertyMultiple</code></td>
+<td>Property</td>
+<td><code>Boolean</code></td>
+<td>If <code>true</code> only multivalue properties are allowed with the name <code><propertyName></code>. If not set or <code>false</code>, multi- and single-value properties are accepted.</td>
+<td>no</td>
+</tr>
+<tr>
+<td><code>properties\<propertyName>\validators\<validatorName></code></td>
+<td>Resource</td>
+<td>-</td>
+<td>The <code><validatorName></code> must be the OSGi component name of a validator. Each validators node might have arbitrarily many subnodes (one per validator).</td>
+<td>no</td>
+</tr>
+<tr>
+<td><code>properties\<propertyName>\validators\<validatorName>\validatorArguments</code></td>
+<td>Property</td>
+<td><code>String[]</code></td>
+<td>The parametrization for the validator with the name <code><validatorName></code>. Each value must have the pattern <code>key=value</code>.</td>
+<td>no</td>
+</tr>
+<tr>
+<td><code>children\<resourceName></code></td>
+<td>Resource</td>
+<td>-</td>
+<td>This resource ensures that the resource with the name <code><resourceName></code> is there.</td>
+<td>no</td>
+</tr>
+<tr>
+<td><code>children\<resourceName>\properties\<propertyName></code></td>
+<td>Resource</td>
+<td>-</td>
+<td>This resource ensures that the property with the name <code><propertyName></code> is there below the resource with the name <code><resourceName></code>. Below this node validators can be given like for properties on the root level.</td>
+<td>no</td>
+</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>
+<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>
+
+<span class="nd">@OSGiService</span>
+<span class="kd">protected</span> <span class="n">ValidationService</span> <span class="n">validation</span><span class="o">;</span>
+
+<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="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>
+</pre></div>
+
+
+<h1 id="writing-validators">Writing Validators</h1>
+<p>The Sling validation bundle currently comes only with one validator <code>RegexValidator</code> which checks that the property value matches a given pattern. That validator supports only one parameter which is called <code>regex</code>. The value specifies the pattern against which the resource value is matched.</p>
+<p>To write a validator one needs to implement the <code>Validator</code> interface in an OSGi service.
+That interface defines the method <code>validate</code>. That is called for each property which is bound to the validator through the Validation Resources.</p>
+<p>Each validator needs to specify one type parameter which defines upon which classes the validator can act (usually <code>String</code>). If a property value cannot be converted to the requested type from the validator (through <code>ValueMap.get(name, type)</code>), validation will fail.</p>
+<h1 id="references">References</h1>
+<ol>
+<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. 1641359 by kwin on Mon, 24 Nov 2014 10:39:29 +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>