svn commit: r1641359 - in /sling/site/trunk/content/documentation: bundles.mdtext bundles/validation.mdtext

[kw...@apache.org]

Author: kwin
Date: Mon Nov 24 10:39:29 2014
New Revision: 1641359

URL: http://svn.apache.org/r1641359
Log:
SLING-2803 initial documentation

Added:
    sling/site/trunk/content/documentation/bundles/validation.mdtext
Modified:
    sling/site/trunk/content/documentation/bundles.mdtext

Modified: sling/site/trunk/content/documentation/bundles.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles.mdtext?rev=1641359&r1=1641358&r2=1641359&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles.mdtext Mon Nov 24 10:39:29 2014
@@ -6,6 +6,7 @@ Title: Bundles
 * [Internationalization Support (i18n)]({{ refs.internationalization-support-i18n.path }})
 * [Manipulating Content - The SlingPostServlet (servlets.post)]({{ refs.manipulating-content-the-slingpostservlet-servlets-post.path }})
 * [Rendering Content - Default GET servlets (servlets.get)]({{ refs.rendering-content-default-get-servlets.path }})
+* [Validation]({{ refs.validation.path }})
 
 ## Resource Providers
 

Added: sling/site/trunk/content/documentation/bundles/validation.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/validation.mdtext?rev=1641359&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/bundles/validation.mdtext (added)
+++ sling/site/trunk/content/documentation/bundles/validation.mdtext Mon Nov 24 10:39:29 2014
@@ -0,0 +1,76 @@
+Title: Sling Validation
+
+[TOC]
+
+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.
+
+# Basic Usage
+To validate a resource one first needs to get a `ValidationModel` and then validate the resource with that model. Both functionalities are provided by the `ValidationService` OSGi service:
+
+    ::java
+    ValidationModel validationModel = validationService.getValidationModel(resource);
+    if (validationModel != null) {
+      ValidationResult result = validationService.validate(resource, validationModel);
+      if (!result.isValid()) {
+        // give out validation messages from result.get
+      }
+    }
+    
+    
+# Validation Model Resources
+The `ValidationModel` is constructed from resources with the resourceType **sling/validation/model**. Those resources are considered validation model resources if they are located
+
+*  below the Sling ResourceResolver search paths (*/apps* and */libs*) **and**
+*  below a node named **validation**.
+ 
+The resources should have the following format:
+
+  Property/Node Name      | Property or Resource |  Type   |  Description   |  Mandatory   |  Example 
+-------------------- | ------- | -------------- | -------------| ---------
+`sling:resourceType` | Property | `String` | Always `sling/validation/model`, otherwise node will never be picked up by Sling Validation. | yes | `sling/validation/model`
+`validatedResourceType` | Property | `String` | The resource type of the resource for which this validation model should be applied. | yes | `my/own/resourcetype` 
+`applicablePaths` | Property |  `String[]` | 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. | no | `/content/mysite`
+`properties\<propertyName>` | Resource | - | This resource ensures that the property with the name `<propertyName>` is there. | no | `false`
+`properties\<propertyName>\propertyMultiple` | Property | `Boolean` | If `true` only multivalue properties are allowed with the name `<propertyName>`. If not set or `false`, multi- and single-value properties are accepted.  | no | `false`  
+`properties\<propertyName>\validators\<validatorName>` | Resource | - | The `<validatorName>` must be the OSGi component name of a validator. Each validators node might have arbitrarily many subnodes (one per validator).  | no | `false`  
+`properties\<propertyName>\validators\<validatorName>\validatorArguments` | Property | `String[]` | The parametrization for the validator with the name  `<validatorName>`. Each value must have the pattern `key=value`.  | no | `regex=^[a-z]*$`  
+`children\<resourceName>` | Resource | - | This resource ensures that the resource with the name `<resourceName>` is there.  | no | `child1`
+`children\<resourceName>\properties\<propertyName>` | Resource | - | This resource ensures that the property with the name `<propertyName>` is there below the resource with the name `<resourceName>`. Below this node validators can be given like for properties on the root level. | no | `property1`
+
+
+# Usage in Sling Models
+Until there is native support in Sling Models [SLING-4161](https://issues.apache.org/jira/browse/SLING-4161), one needs to call the validate method within the PostConstruct method of the according Sling Model
+
+    ::java
+    @SlingObject
+    protected Resource resource;
+    
+    @OSGiService
+    protected ValidationService validation;
+    
+    @PostConstruct
+    public void validate() {
+        ValidationModel validationModel = validation.getValidationModel(resource);
+        if (validationModel == null) {
+            LOG.warn("No validation defined for resource '{}' with type '{}'", resource.getPath(), resource.getResourceType());
+        } else {
+            ValidationResult result = validation.validate(resource, validationModel);
+            if (!result.isValid()) {
+                // give out the validation result
+            }
+        }
+    }
+
+
+# Writing Validators
+The Sling validation bundle currently comes only with one validator `RegexValidator` which checks that the property value matches a given pattern. That validator supports only one parameter which is called `regex`. The value specifies the pattern against which the resource value is matched.
+
+To write a validator one needs to implement the `Validator` interface in an OSGi service.
+That interface defines the method `validate`. That is called for each property which is bound to the validator through the Validation Resources.
+
+Each validator needs to specify one type parameter which defines upon which classes the validator can act (usually `String`). If a property value cannot be converted to the requested type from the validator (through `ValueMap.get(name, type)`), validation will fail.
+
+
+# References
+1. [Apache Sling Generic Validation Framework, adaptTo 2014](http://www.slideshare.net/raducotescu/apache-sling-generic-validation-framework)
+