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

[kw...@apache.org]

Author: kwin
Date: Thu Mar  2 07:31:24 2017
New Revision: 1785077

URL: http://svn.apache.org/viewvc?rev=1785077&view=rev
Log:
document `validation.id` property, fix some typos

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

Modified: sling/site/trunk/content/documentation/bundles/validation.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/validation.mdtext?rev=1785077&r1=1785076&r2=1785077&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/validation.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/validation.mdtext Thu Mar  2 07:31:24 2017
@@ -11,7 +11,7 @@ Many Sling projects want to be able to v
 # Prerequisites
 To use this validation framework the following bundles need to be deployed
 
-1. `org.apace.sling.validation.api`
+1. `org.apache.sling.validation.api`
 1. `org.apache.sling.validation.core`
 
 In addition a [service resolver mapping]({{ refs.service-authentication.path }}) needs to be configured for the service name `org.apache.sling.validation.core`. The bound service user needs to have at least read access to all resources within the resource resolver's search paths (usually `/apps` and `/libs`).
@@ -69,12 +69,12 @@ The resources should have the following
 `properties\<propertyName>\optional` | Property | `Boolean` | If `true` it is not an error if there is no property with the given `<propertyName>` or none matching the  `nameRegex`. If not set or `false` the property must be there.  | no | `false`
 `properties\<propertyName>\propertyMultiple` | Property | `Boolean` | If `true` only multivalue properties are allowed with the name `<propertyName>` or matching the `nameRegex`. If not set or `false`, multi- and single-value properties are accepted.  | no | `false`
 `properties\<propertyName>\nameRegex` | Property | `String` | If set the `<propertyName>` has no longer a meaning. Rather all properties which match the given regular expression are considered. At least one match is required, otherwise the validated resource/valuemap is considered invalid. | no | `property[0-8]`  
-`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`. The parametrization differs per validator.  | no | `regex=^[a-z]*$`
+`properties\<propertyName>\validators\<validatorId>` | Resource | - | The `<validatorId>` must be the id of a validator. The id is given by the OSGi service property `validation.id` set in the validator. Each validators node might have arbitrarily many child resources (one per validator).  | no | `false`  
+`properties\<propertyName>\validators\<validatorName>\validatorArguments` | Property | `String[]` | The parametrization for the validator with the id  `<validatorId>`. Each value must have the pattern `key=value`. The parametrization differs per validator. | no | `regex=^[a-z]*$`
 `properties\<propertyName>\validators\<validatorName>\severity` | Property | `Integer` | The severity which should be set on all emitted validation failures by this validator. | no | `0` 
-`children\<resourceName>` | Resource | - | This resource ensures that the resource with the name `<resourceName>` is there. The resource name has no longer a meaning if the property `nameRegex` is set on this node.  | no | `child1`
+`children\<resourceName>` | Resource | - | This resource ensures that the resource with the name `<resourceName>` is there. The resource name has no longer a meaning if the property `nameRegex` is set on this node. | no | `child1`
 `children\<resourceName>\nameRegex` | Property | `String` | If set the `<resourceName>` has no longer a meaning. Rather all resources whose name match the given regular expression are considered. At least one match is required, otherwise the validated resource/valuemap is considered invalid. | no | `child[1-9]`
-`children\<resourceName>\optional` | Property | `Boolean` | If `true` it is not an error if there is no resource with the given `<resourceName>` or none matching the  `nameRegex`. If not set or `false` the resource must be there.  | no | `false`
+`children\<resourceName>\optional` | Property | `Boolean` | If `true` it is not an error if there is no resource with the given `<resourceName>` or none matching the  `nameRegex`. If not set or `false` the resource must be there. | no | `false`
 `children\<resourceName>\properties` | Resource | - | The properties can be configured on the child level in the same way as on the root level. | no | -
 
 ## Validation Model Inheritance
@@ -113,15 +113,18 @@ See [Sling Models validation]({{ refs.mo
         }
     }
 
+# Validators
 
-# 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.
+Validator ID | Description | Parameters | Since
+-------------------------------------------------
+[`org.apache.sling.validation.core.RegexValidator`](https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/validation/core/src/main/java/org/apache/sling/validation/impl/validators/RegexValidator.java) | Validates that a property value matches a given regular expression | `regex`, mandatory parameter giving a regular expression according to the pattern described in [java.util.regex.Pattern](http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html). Only if the property value matches this expression it is considered valid. | 1.0.0
 
+# Writing Validators
+To write a validator one needs to implement the [`org.apache.sling.validation.spi.Validator`](hhttps://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/validation/api/src/main/java/org/apache/sling/validation/spi/Validator.java) interface in an OSGi service (look at [`org.apache.sling.validation.core.RegexValidator`](https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/validation/core/src/main/java/org/apache/sling/validation/impl/validators/RegexValidator.java) for an example).
+That interface defines the method `validate`. That is called for each property which is bound to the validator through the validation model.
 Each validator needs to specify one type parameter which defines upon which classes the validator can act (usually `String`). Array types are also supported here. Collection types are not supported. If a property value cannot be converted to the requested type from the validator (through `ValueMap.get(name, type)`), validation will fail.
 
+In addition that OSGi service needs to expose a property called `validation.id`. The value of this property should start with the providing bundle symbolic name. Only through this value the validator can be referenced from validation models. If multiple validators have the same `validation.id` value the one with the highest service ranking gets chosen.
 
 # References
 1. [Apache Sling Generic Validation Framework, adaptTo 2014](http://www.slideshare.net/raducotescu/apache-sling-generic-validation-framework)