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

[si...@apache.org]

Author: simonetripodi
Date: Mon Jul 19 19:38:58 2010
New Revision: 965598

URL: http://svn.apache.org/viewvc?rev=965598&view=rev
Log:
reorganized ToC
modified introduction

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=965598&r1=965597&r2=965598&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 Mon Jul 19 19:38:58 2010
@@ -25,7 +25,7 @@
         meta data-based definition of rules for <code>Digester</code>.
         This improves maintainability of both Java code and XML documents, as
         rules are now defined in POJOs and generating <code>Digester</code>
-        parsers at run-time.</p>
+        parsers at run-time, avoiding manual updates.</p>
 
         <a name="doc.Description"></a>
         <br />
@@ -37,13 +37,9 @@
             <br />
             <a href="#doc.RuleElements">[Rule Elements]</a>
             <br />
-            <a href="#doc.Patterns">[Matching Patterns]</a>
+            <a href="#doc.Bootstrapping">[Bootstrapping]</a>
             <br />
-            <a href="#doc.Inclusion">[Including rules files in other rules files]</a>
-            <br />
-            <a href="#doc.InclusionJava">[Including programmatically-created rules]</a>
-            <br />
-            <a href="#doc.DigesterCreation">[Creating a digester from XML]</a>
+            <a href="#doc.SPI">[Service provider interface]</a>
             <br />
         </div>
 
@@ -60,15 +56,28 @@
         <a name="doc.Annotation_Rules"></a>
         <h3>Annotation Rules</h3>
 
-        <p>Annotation Rules are defined by the combination of:
+        <p>A digester rule on a POJO is expressed through one or more annotations.
+        An annotation is considered a digester rule definition if its retention
+        policy contains RUNTIME and if the annotation itself is annotated with
+        <code>org.apache.commons.digester.annotations.DigesterRule</code>.</p>
+
+        <p>The <code>DigesterRule</code> is defined by the combination of:</p>
         <ul>
-            <li>an annotation that reflect a Digester rule;</li>
-            <li>a handler that has to be invoked during the class traversal;</li>
-            <li>a rule provider that creates the <code>pattern, rule</code> pair.</li>
+            <li>the reflected rule class by the annotation;</li>
+            <li>the handler class that has to be invoked during the class traversal;</li>
+            <li>the rule provider that produces the <code>pattern, rule</code> pair.</li>
         </ul>
-        The Annotation Rules are applied on types, methods and fields.</p>
 
-        <h4></h4>
+        <p>Digester annotations can target any of the following <code>ElementType</code>s:</p>
+        <ul>
+            <li><code>FIELD</code> for Digester rules concerning attributes;</li>
+            <li><code>METHOD</code> for Digester rules concerning methods calls;</li>
+            <li><code>PARAMETER</code> for Digester rules concerning methods parameters setting;</li>
+            <li><code>TYPE</code> for constrained beans.</li>
+        </ul>
+        <p>While other <code>ElementType</code>s are not forbidden, the Digester
+        annotations processor does not have to recognize and process annotation
+        rules placed on such types.</p>
 
     </body>
 </html>