Author: simonetripodi
Date: Mon Jul 19 20:33:07 2010
New Revision: 965617
URL: http://svn.apache.org/viewvc?rev=965617&view=rev
Log:
completed the Annotation Rule section
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=965617&r1=965616&r2=965617&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 20:33:07 2010
@@ -35,7 +35,7 @@
<br />
<a href="#doc.Annotation_Rules">[Annotation Rules]</a>
<br />
- <a href="#doc.RuleElements">[Rule Elements]</a>
+ <a href="#doc.BuiltinRules">[Built-in Rules]</a>
<br />
<a href="#doc.Bootstrapping">[Bootstrapping]</a>
<br />
@@ -65,9 +65,14 @@
<p>The <code>DigesterRule</code> is defined by the combination of:</p>
<ul>
- <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>
+ <li>the reflected <code>Class<? extends
org.apache.commons.digester.Rule></code>
+ by the annotation;</li>
+ <li>the
<code>org.apache.commons.digester.annotations.DigesterLoaderHandler</code>
+ class that has to be invoked during the target class traversal
+ (if not specifyied, the annotation processor will supply the
+
<code>org.apache.commons.digester.annotations.handlers.DefaultLoaderHandler</code>);</li>
+ <li>the
<code>org.apache.commons.digester.annotations.AnnotationRuleProvider</code>
+ provider that produces the <code>pattern, rule</code> pair.</li>
</ul>
<p>Digester annotations can target any of the following
<code>ElementType</code>s:</p>
@@ -84,5 +89,67 @@
<p>Every Digester rule annotation <b>must</b> define a <i>pattern</i>
element of type <code>String</code> that represents the element
matching
path pattern.</p>
+
+ <h4>Example</h4>
+ <pre>@Documented
+...@retention(RetentionPolicy.RUNTIME)
+...@target(ElementType.TYPE)
+...@creationrule
+...@digesterrule(
+ reflectsRule = ObjectCreateRule.class,
+ providedBy = ObjectCreateRuleProvider.class
+)
+public @interface ObjectCreate {
+
+ String pattern();
+
+}</pre>
+
+ <h4>Applying multiple annotation rule of the same type</h4>
+ <p>It is often useful to declare the same annotation rule more than
once
+ to the same target, with different properties. To support this
requirement,
+ the Digester annotation processor treats annotations annotated by
+ <code>@org.apache.commons.digester.annotations.DigesterRuleList</code>
+ whose <code>value</code> element has a return type of an array of rule
+ annotations in a special way. Each element in the value array are
processed
+ by the Digester annotation processor as regular annotation rule
annotations.
+ This means that each Digester rule specified in the <code>value</code>
+ element is applied to the target. The annotation must have retention
+ <code>RUNTIME</code> and can be applied on a type, field, method or
+ method parameter. It is recommended to use the same set of targets as
+ the initial Digester annotation rule.</p>
+
+ <p>Note to designers: each Digester annotation rule should be coupled
+ with its corresponding multi-valued annotation.
+ The specification recommends, though does not mandate, the definition
of
+ an inner annotation named <code>List</code>.</p>
+
+ <h4>Example</h4>
+ <pre>@Documented
+...@retention(RetentionPolicy.RUNTIME)
+...@target(ElementType.TYPE)
+...@creationrule
+...@digesterrule(
+ reflectsRule = ObjectCreateRule.class,
+ providedBy = ObjectCreateRuleProvider.class
+)
+public @interface ObjectCreate {
+
+ String pattern();
+
+ @Documented
+ @Retention(RetentionPolicy.RUNTIME)
+ @Target(ElementType.TYPE)
+ @DigesterRuleList
+ @interface List {
+ ObjectCreate[] value();
+ }
+
+}</pre>
+
+ <a name="doc.BuiltinRules"></a>
+ <h3>Built-in Rules</h3>
+
+ <p></p>
</body>
</html>
