svn commit: r965758 - /commons/sandbox/at-digester/trunk/src/java/org/apache/commons/digester/annotations/package.html

[simonetripodi]

Author: simonetripodi
Date: Tue Jul 20 08:48:34 2010
New Revision: 965758

URL: http://svn.apache.org/viewvc?rev=965758&view=rev
Log:
added Providers and Handlers description

Modified:
    
commons/sandbox/at-digester/trunk/src/java/org/apache/commons/digester/annotations/package.html

Modified: 
commons/sandbox/at-digester/trunk/src/java/org/apache/commons/digester/annotations/package.html
URL: 
http://svn.apache.org/viewvc/commons/sandbox/at-digester/trunk/src/java/org/apache/commons/digester/annotations/package.html?rev=965758&r1=965757&r2=965758&view=diff
==============================================================================
--- 
commons/sandbox/at-digester/trunk/src/java/org/apache/commons/digester/annotations/package.html
 (original)
+++ 
commons/sandbox/at-digester/trunk/src/java/org/apache/commons/digester/annotations/package.html
 Tue Jul 20 08:48:34 2010
@@ -147,6 +147,72 @@ public @interface ObjectCreate {
 
 }</pre>
 
+        <h4>Rule provider implementation</h4>
+        <p>A Digester rule provider implementation performs the rule creation
+        of a given annotation for a given annotated element. The implementation
+        classes are specified by the <code>providedBy</code> element of the
+        <code>@DigesterRule</code> annotation that decorates the rule 
annotation
+        definition. The rule provider implementation implements the
+        
<code>org.apache.commons.digester.annotations.AnnotationRuleProvider&lt;A 
extends Annotation, E extends AnnotatedElement, R extends Rule&gt;</code>
+        interface.</p>
+
+        <h4>Example</h4>
+        <pre>class ObjectCreateRuleProvider implements 
AnnotationRuleProvider&lt;ObjectCreate, Class&lt;?&gt;, ObjectCreateRule&gt; {
+
+    private Class<?> clazz;
+
+    public void init(ObjectCreate annotation, Class<?> element) {
+        this.clazz = element;
+    }
+
+    public ObjectCreateRule get() {
+        return new ObjectCreateRule(this.clazz);
+    }
+
+}</pre>
+
+        <h5>Notes</h5>
+        <p>A new instance of the provider will be created each time the 
Digester
+        annotations processor will meet the relative rule that requests it.</p>
+        <p>To supply the missing <code>AnnotatedElement</code> for methods
+        <code>PARAMETER</code>s, the Digester annotation processor come with 
the
+        
<code>org.apache.commons.digester.annotations.reflect.MethodArgument</code>
+        class.</p>
+
+        <h4>Digester loader handler implementation</h4>
+        <p>The Digester loader handler is an <code>AnnotatedElement</code>
+        interceptor invoked when meeting a particular Digester rule annotation
+        while analyzing the target class.</p>
+
+        <p>By default, the Digester annotations processor, when meeting a
+        Digester annotation rule, extracts the rule pattern and the relative
+        rule provider to store it in the
+        
<code>org.apache.commons.digester.annotations.FromAnnotationsRuleSet</code>,
+        an <code>org.apache.commons.digester.RuleSet</code> implementation.</p>
+
+        <p>If designers have the need of a more elaborate annottaion 
processing,
+        they can specify the <code>handledBy</code> element of the
+        <code>@DigesterRule</code> annotation that decorates the rule 
annotation
+        definition. The Digester loader handler implementation implements the
+        <code>DigesterLoaderHandler&lt;A extends Annotation, E extends 
AnnotatedElement&gt;</code>
+        interface.</p>
+
+        <h4>Example</h4>
+        <pre>class SetPropertiesLoaderHandler implements 
DigesterLoaderHandler&lt;SetProperty, Field&gt; {
+
+    public void handle(SetProperty annotation, Field element, 
FromAnnotationsRuleSet ruleSet) {
+        SetPropertiesRuleProvider ruleProvider = 
ruleSet.getProvider(annotation.pattern(), SetPropertiesRuleProvider.class);
+
+        if (ruleProvider == null) {
+            ruleProvider = new SetPropertiesRuleProvider();
+            ruleSet.addRuleProvider(annotation.pattern(), ruleProvider);
+        }
+
+        ruleProvider.addAlias(annotation, element);
+    }
+
+}</pre>
+
         <a name="doc.BuiltinRules"></a>
         <h3>Built-in Rules</h3>