commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From simonetrip...@apache.org
Subject svn commit: r1128447 - /commons/sandbox/digester3/trunk/src/site/xdoc/guide/annotations.xml
Date Fri, 27 May 2011 20:33:07 GMT
Author: simonetripodi
Date: Fri May 27 20:33:07 2011
New Revision: 1128447

URL: http://svn.apache.org/viewvc?rev=1128447&view=rev
Log:
updated annotation package description according to latest modification

Modified:
    commons/sandbox/digester3/trunk/src/site/xdoc/guide/annotations.xml

Modified: commons/sandbox/digester3/trunk/src/site/xdoc/guide/annotations.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/digester3/trunk/src/site/xdoc/guide/annotations.xml?rev=1128447&r1=1128446&r2=1128447&view=diff
==============================================================================
--- commons/sandbox/digester3/trunk/src/site/xdoc/guide/annotations.xml (original)
+++ commons/sandbox/digester3/trunk/src/site/xdoc/guide/annotations.xml Fri May 27 20:33:07
2011
@@ -48,12 +48,8 @@ limitations under the License.
         <ul>
             <li>the reflected <code>Class&lt;? extends org.apache.commons.digester3.Rule&gt;</code>
             by the annotation;</li>
-            <li>the <code>org.apache.commons.digester3.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.digester3.annotations.handlers.DefaultLoaderHandler</code>);</li>
-            <li>the <code>org.apache.commons.digester3.annotations.AnnotationRuleProvider</code>
-            provider that produces the <code>pattern, rule</code> pair.</li>
+            <li>the <code>org.apache.commons.digester3.annotations.AnnotationHandler</code>
+            class that has to be invoked during the target class traversal.</li>
         </ul>
 
         <p>Digester annotations can target any of the following <code>ElementType</code>s:</p>
@@ -69,20 +65,23 @@ limitations under the License.
 
         <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>
+        path pattern, and the <i>namespaceURI</i> for which the <code>Rule</code>
is relevant.</p>
 
         <source>@Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 @CreationRule
 @DigesterRule(
-        reflectsRule = ObjectCreateRule.class,
-        providedBy = ObjectCreateRuleProvider.class
+    reflectsRule = ObjectCreateRule.class,
+    providedBy = ObjectCreateRuleProvider.class
 )
-public @interface ObjectCreate {
+public @interface ObjectCreate
+{
 
     String pattern();
 
+    String namespaceURI() default "";
+
 }</source>
        </subsection>
 
@@ -106,94 +105,65 @@ public @interface ObjectCreate {
         an inner annotation named <code>List</code>.</p>
 
          <source>@Documented
-@Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.TYPE)
+@Retention( RetentionPolicy.RUNTIME )
+@Target( ElementType.TYPE )
 @CreationRule
 @DigesterRule(
     reflectsRule = ObjectCreateRule.class,
-    providedBy = ObjectCreateRuleProvider.class
+    handledBy = ObjectCreateHandler.class
 )
-public @interface ObjectCreate {
+public @interface ObjectCreate
+{
 
     String pattern();
 
+    String namespaceURI() default "";
+
     @Documented
-    @Retention(RetentionPolicy.RUNTIME)
-    @Target(ElementType.TYPE)
+    @Retention( RetentionPolicy.RUNTIME )
+    @Target( ElementType.TYPE )
     @DigesterRuleList
-    @interface List {
+    @interface List
+    {
         ObjectCreate[] value();
     }
 
 }</source>
        </subsection>
 
-       <subsection name="Rule provider implementation">
-         <p>A Digester rule provider implementation performs the rule creation
+       <subsection name="AnnotationHandler implementation">
+         <p>An <code>AnnotationHandler</code> implementation performs the
rule binding
         of a given annotation for a given annotated element. The implementation
-        classes are specified by the <code>providedBy</code> element of the
+        classes are specified by the <code>handledBy</code> element of the
         <code>@DigesterRule</code> annotation that decorates the rule annotation
         definition. The rule provider implementation implements the
-        <code>org.apache.commons.digester3.annotations.AnnotationRuleProvider&lt;A
extends Annotation, E extends AnnotatedElement, R extends Rule&gt;</code>
+        <code>org.apache.commons.digester3.annotations.AnnotationHandler&lt;A extends
Annotation, E extends AnnotatedElement&gt;</code>
         interface.</p>
 
-        <source>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);
+        <source>class ObjectCreateHandler
+    implements AnnotationHandler&lt;ObjectCreate, Class&lt;?&gt;&gt;
+{
+
+    public void handle( ObjectCreate annotation, Class&lt;?&gt; element, RulesBinder
rulesBinder )
+    {
+        rulesBinder.forPattern( annotation.pattern() )
+            .withNamespaceURI( annotation.namespaceURI() )
+            .createObject()
+                .ofType( element )
+                .ofTypeSpecifiedByAttribute( annotation.attributeName() != null ? annotation.attributeName()
: null );
     }
 
 }</source>
 
-         <h5>Notes</h5>
-        <p>A new instance of the provider will be created each time the Digester
+        <h5>Notes</h5>
+        <p>A new instance of the <code>AnnotationHandler</code> 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.digester3.annotations.reflect.MethodArgument</code>
+        <code>org.apache.commons.digester.annotations.reflect.MethodArgument</code>
         class.</p>
        </subsection>
 
-       <subsection name="Digester loader handler implementation">
-         <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.digester3.annotations.FromAnnotationsRuleSet</code>,
-        an <code>org.apache.commons.digester3.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. Follows below an example:</p>
-
-        <source>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);
-    }
-
-}</source>
-       </subsection>
-
        <subsection name="Built-in Rules">
          <p>All built-in annotation rules are in the package
         <code>org.apache.commons.digester3.annotations.rules</code>.
@@ -240,47 +210,24 @@ public @interface ObjectCreate {
                 <tr><th>Annotation</th><th>Reflect rule</th></tr>
             </thead>
             <tbody>
-                <tr><td>@AttributeCallParam</td><td>org.apache.commons.digester3.Digester#addCallParam(String,
int, String)</td></tr>
-                <tr><td>@CallParam</td><td>org.apache.commons.digester3.Digester#addCallParam(String,
int)</td></tr>
-                <tr><td>@PathCallParam</td><td>org.apache.commons.digester3.Digester#addCallParamPath(String,
int)</td></tr>
-                <tr><td>@StackCallParam</td><td>org.apache.commons.digester3.Digester#addCallParam(String,
int, int)</td></tr>
+                <tr><td>@CallParam</td><td>org.apache.commons.digester3.rule.CallParamRule</td></tr>
             </tbody>
         </table>
        </subsection>
 
        <subsection name="Bootstrapping">
          <p>The core of Digester annotations rules processor is the
-    <code>org.apache.commons.digester3.annotations.DigesterLoader</code> class.</p>
+    <code>org.apache.commons.digester3.annotations.FromAnnotationsRuleModule</code>
class, a specialization of
+    <code>org.apache.commons.digester3.RulesModule</code>.</p>
 
-    <p>A <code>org.apache.commons.digester3.annotations.DigesterLoader</code>
+    <p>A <code>FromAnnotationsRuleModule</code>
     instance is able to analyze <code>Class&lt;?&gt;</code> graphs and
builds
-    the relative <code>org.apache.commons.digester3.RuleSet</code> to create
+    the relative rule bindings to create
     <code>org.apache.commons.digester3.Digester</code> instances.</p>
 
-    <p>The bootstrap sequence has been designed to be as simple as possible,
-    all that's needed is creating a new
-    <code>org.apache.commons.digester3.annotations.DigesterLoaderBuilder</code>
-    instance, plugging the desired
-    <code>org.apache.commons.digester3.annotations.spi.AnnotationRuleProviderFactory</code>
and
-    <code>org.apache.commons.digester3.annotations.spi.DigesterLoaderHandlerFactory</code>.
-    using a chaining builders pattern.</p>
-
-    <p>An <code>org.apache.commons.digester3.annotations.spi.AnnotationRuleProviderFactory</code>
+    <p>An <code>org.apache.commons.digester3.annotations.AnnotationHandlerFactory</code>
     implementation performs the creation of
-    <code>org.apache.commons.digester3.annotations.AnnotationRuleProvider&lt;A
extends Annotation, E extends AnnotatedElement, R extends Rule&gt;</code>
-    instances; the default implementation is limited to create the provider
-    by invoking the default empty constructor of the required class, but
-    users are free to give their implementation if they need a more complex
-    factory, i.e. providers requires components that could be injected from a
-    context, etc. etc.</p>
-
-    <h5>Note</h5>
-    <p>It is strongly descouraged caching <code>AnnotationRuleProvider</code>
-    instances!!!</p>
-
-    <p>Same thing for the <code>org.apache.commons.digester3.annotations.spi.DigesterLoaderHandlerFactory</code>,
-    which implementation performs the creation of
-    <code>DigesterLoaderHandler&lt;A extends Annotation, E extends AnnotatedElement&gt;</code>
+    <code>org.apache.commons.digester3.annotations.AnnotationHandler&lt;A extends
Annotation, E extends AnnotatedElement&gt;</code>
     instances; the default implementation is limited to create the handler
     by invoking the default empty constructor of the required class, but
     users are free to give their implementation if they need a more complex
@@ -288,89 +235,115 @@ public @interface ObjectCreate {
     context, etc. etc.</p>
 
     <p>Said that, to obtain a fresh new
-    <code>org.apache.commons.digester3.annotations.DigesterLoader</code> instance
-    with default factories, it is enough invoking the default empty constructor:</p>
+    <code>org.apache.commons.digester3.binder.DigesterLoader</code> instance
+    with default factories, it is enough extending the
+    <code>org.apache.commons.digester3.annotations.FromAnnotationsRuleModule</code>
class:</p>
+
+    <source>class MyModule
+    extends FromAnnotationsRuleModule
+{
+
+    @Override
+    protected void configureRules()
+    {
+        bindRulesFrom( MyType1.class );
+        bindRulesFrom( MyType2.class );
+        bindRulesFrom( MyType3.class );
+        ...
+    }
 
-    <source>DigesterLoader digesterLoader = new DigesterLoaderBuilder()
-                                    .useDefaultAnnotationRuleProviderFactory()
-                                    .useDefaultDigesterLoaderHandlerFactory();</source>
-
-    <p>Otherwise, if users need specify theyr custom factories:</p>
-
-    <source>DigesterLoader digesterLoader = new DigesterLoaderBuilder()
-                                    .useAnnotationRuleProviderFactory(new MyAnnotationRuleProviderFactory())
-                                    .useDigesterLoaderHandlerFactory(new MyDigesterLoaderHandlerFactory());</source>
-       </subsection>
+}</source>
+
+    <p>Otherwise, if users need specify their custom factory:</p>
+
+    <source>class MyModule
+    extends FromAnnotationsRuleModule
+{
+
+    @Override
+    protected void configureRules()
+    {
+        useAnnotationHandlerFactory( new MyAnnotationHandlerFactory() );
+        ...
+        bindRulesFrom( MyType1.class );
+        bindRulesFrom( MyType2.class );
+        bindRulesFrom( MyType3.class );
+        ...
+    }
+
+}</source>
+        </subsection>
 
        <subsection name="Example: a simple RSS parser">
          <p>Let's assume there is the need to parse the following (simplified)
     XML/RSS feed:</p>
 
     <source>&lt;rss version="2.0"&gt;
-    &lt;channel&gt;
+  &lt;channel&gt;
 
-        &lt;title&gt;Apache&lt;/title&gt;
-        &lt;link&gt;http://www.apache.org&lt;/link&gt;
-        &lt;description&gt;The Apache Software Foundation&lt;/description&gt;
-        &lt;language&gt;en-US&lt;/language&gt;
-        &lt;rating&gt;(PICS-1.1 "http://www.rsac.org/ratingsv01.html"
-            2 gen true comment "RSACi North America Server"
-            for "http://www.rsac.org" on "1996.04.16T08:15-0500"
-            r (n 0 s 0 v 0 l 0))&lt;/rating&gt;
-
-        &lt;image&gt;
-            &lt;title&gt;Apache&lt;/title&gt;
-            &lt;url&gt;http://jakarta.apache.org/images/jakarta-logo.gif&lt;/url&gt;
-            &lt;link&gt;http://jakarta.apache.org&lt;/link&gt;
-            &lt;width&gt;505&lt;/width&gt;
-            &lt;height&gt;480&lt;/height&gt;
-            &lt;description&gt;The Jakarta project. Open source, serverside java.&lt;/description&gt;
-        &lt;/image&gt;
-
-        &lt;item&gt;
-            &lt;title&gt;Commons Attributes 2.1 Released&lt;/title&gt;
-            &lt;link&gt;http://jakarta.apache.org/site/news/news-2004-2ndHalf.html#20040815.1&lt;/link&gt;
-            &lt;description&gt;The Apache Commons team is happy to announce the release
of Commons Attributes 2.1.
-            This is the first release of the new Commons-Attributes code.&lt;/description&gt;
-        &lt;/item&gt;
-
-        &lt;item&gt;
-            &lt;title&gt;Cloudscape Becomes Apache Derby&lt;/title&gt;
-            &lt;link&gt;http://jakarta.apache.org/site/news/elsewhere-2004-2ndHalf.html#20040803.1&lt;/link&gt;
-            &lt;description&gt;IBM has submitted a proposal to the Apache DB project
for a Java-based package to be called 'Derby'.&lt;/description&gt;
-        &lt;/item&gt;
-
-        &lt;item&gt;
-            &lt;title&gt;Commons BeanUtils 1.7 Released&lt;/title&gt;
-            &lt;link&gt;http://jakarta.apache.org/site/news/news-2004-2ndHalf.html#20040802.1&lt;/link&gt;
-            &lt;description/&gt;
-        &lt;/item&gt;
-
-        &lt;item&gt;
-            &lt;title&gt;Commons JXPath 1.2 Released&lt;/title&gt;
-            &lt;link&gt;http://jakarta.apache.org/site/news/news-2004-2ndHalf.html#20040801.2&lt;/link&gt;
-            &lt;description/&gt;
-        &lt;/item&gt;
-    &lt;/channel&gt;
+    &lt;title&gt;Apache&lt;/title&gt;
+    &lt;link&gt;http://www.apache.org&lt;/link&gt;
+    &lt;description&gt;The Apache Software Foundation&lt;/description&gt;
+    &lt;language&gt;en-US&lt;/language&gt;
+    &lt;rating&gt;(PICS-1.1 "http://www.rsac.org/ratingsv01.html"
+      2 gen true comment "RSACi North America Server"
+      for "http://www.rsac.org" on "1996.04.16T08:15-0500"
+      r (n 0 s 0 v 0 l 0))&lt;/rating&gt;
+
+    &lt;image&gt;
+      &lt;title&gt;Apache&lt;/title&gt;
+      &lt;url&gt;http://jakarta.apache.org/images/jakarta-logo.gif&lt;/url&gt;
+      &lt;link&gt;http://jakarta.apache.org&lt;/link&gt;
+      &lt;width&gt;505&lt;/width&gt;
+      &lt;height&gt;480&lt;/height&gt;
+      &lt;description&gt;The Jakarta project. Open source, serverside java.&lt;/description&gt;
+    &lt;/image&gt;
+
+    &lt;item&gt;
+      &lt;title&gt;Commons Attributes 2.1 Released&lt;/title&gt;
+      &lt;link&gt;http://jakarta.apache.org/site/news/news-2004-2ndHalf.html#20040815.1&lt;/link&gt;
+      &lt;description&gt;The Apache Commons team is happy to announce the release
of Commons Attributes 2.1.
+      This is the first release of the new Commons-Attributes code.&lt;/description&gt;
+    &lt;/item&gt;
+
+    &lt;item&gt;
+      &lt;title&gt;Cloudscape Becomes Apache Derby&lt;/title&gt;
+      &lt;link&gt;http://jakarta.apache.org/site/news/elsewhere-2004-2ndHalf.html#20040803.1&lt;/link&gt;
+      &lt;description&gt;IBM has submitted a proposal to the Apache DB project for
a Java-based package to be called 'Derby'.&lt;/description&gt;
+    &lt;/item&gt;
+
+    &lt;item&gt;
+      &lt;title&gt;Commons BeanUtils 1.7 Released&lt;/title&gt;
+      &lt;link&gt;http://jakarta.apache.org/site/news/news-2004-2ndHalf.html#20040802.1&lt;/link&gt;
+      &lt;description/&gt;
+    &lt;/item&gt;
+
+    &lt;item&gt;
+      &lt;title&gt;Commons JXPath 1.2 Released&lt;/title&gt;
+      &lt;link&gt;http://jakarta.apache.org/site/news/news-2004-2ndHalf.html#20040801.2&lt;/link&gt;
+      &lt;description/&gt;
+    &lt;/item&gt;
+  &lt;/channel&gt;
 &lt;/rss&gt;</source>
 
     <p>So, let's define the Java entities and annotate them; first the <code>Channel</code>
entity:</p>
 
-    <source>@ObjectCreate(pattern = "rss/channel")
-class Channel {
+    <source>@ObjectCreate( pattern = "rss/channel" )
+class Channel
+{
 
     private final List&lt;Item&gt; items = new ArrayList&lt;Item&gt;();
 
-    @BeanPropertySetter(pattern = "rss/channel/title")
+    @BeanPropertySetter( pattern = "rss/channel/title" )
     private String title;
 
-    @BeanPropertySetter(pattern = "rss/channel/link")
+    @BeanPropertySetter( pattern = "rss/channel/link" )
     private String link;
 
-    @BeanPropertySetter(pattern = "rss/channel/description")
+    @BeanPropertySetter( pattern = "rss/channel/description" )
     private String description;
 
-    @BeanPropertySetter(pattern = "rss/channel/language")
+    @BeanPropertySetter( pattern = "rss/channel/language" )
     private String language;
 
     private Image image;
@@ -378,38 +351,41 @@ class Channel {
     // getters and setters
 
     @SetNext
-    public void setImage(Image image) {
+    public void setImage( Image image )
+    {
         this.image = image;
     }
 
     @SetNext
-    public void addItem(Item item) {
-        this.items.add(item);
+    public void addItem( Item item )
+    {
+        this.items.add( item );
     }
 
 }</source>
 
     <p>Then the <code>Image</code> entity:</p>
 
-    <source>@ObjectCreate(pattern = "rss/channel/image")
-class Image {
+    <source>@ObjectCreate( pattern = "rss/channel/image" )
+class Image
+{
 
-    @BeanPropertySetter(pattern = "rss/channel/image/description")
+    @BeanPropertySetter( pattern = "rss/channel/image/description" )
     private String description;
 
-    @BeanPropertySetter(pattern = "rss/channel/image/width")
+    @BeanPropertySetter( pattern = "rss/channel/image/width" )
     private int width;
 
-    @BeanPropertySetter(pattern = "rss/channel/image/height")
+    @BeanPropertySetter( pattern = "rss/channel/image/height" )
     private int height;
 
-    @BeanPropertySetter(pattern = "rss/channel/image/link")
+    @BeanPropertySetter( pattern = "rss/channel/image/link" )
     private String link;
 
-    @BeanPropertySetter(pattern = "rss/channel/image/title")
+    @BeanPropertySetter( pattern = "rss/channel/image/title" )
     private String title;
 
-    @BeanPropertySetter(pattern = "rss/channel/image/url")
+    @BeanPropertySetter( pattern = "rss/channel/image/url" )
     private String url;
 
     // getters and setters
@@ -418,16 +394,17 @@ class Image {
 
     <p>and finally the <code>Item</code> entity:</p>
 
-    <source>@ObjectCreate(pattern = "rss/channel/item")
-class Item {
+    <source>@ObjectCreate( pattern = "rss/channel/item" )
+class Item
+{
 
-    @BeanPropertySetter(pattern = "rss/channel/item/description")
+    @BeanPropertySetter( pattern = "rss/channel/item/description" )
     private String description;
 
-    @BeanPropertySetter(pattern = "rss/channel/item/link")
+    @BeanPropertySetter( pattern = "rss/channel/item/link" )
     private String link;
 
-    @BeanPropertySetter(pattern = "rss/channel/item/title")
+    @BeanPropertySetter( pattern = "rss/channel/item/title" )
     private String title;
 
     // getters and setters
@@ -436,26 +413,32 @@ class Item {
 
     <p>It is now possible to create the <code>Digester</code> instance
and parse the XML:</p>
 
-    <source>DigesterLoader digesterLoader = new DigesterLoaderBuilder()
-                                    .useDefaultAnnotationRuleProviderFactory()
-                                    .useDefaultDigesterLoaderHandlerFactory();
+    <source>import static org.apache.commons.digester3.binder.DigesterLoader.newLoader;
+
+import org.apache.commons.digester3.Digester;
+import org.apache.commons.digester3.binder.DigesterLoader;
+...
+DigesterLoader loader = newLoader( new FromAnnotationsRuleModule()
+    {
+
+        @Override
+        protected void configureRules()
+        {
+            bindRulesFrom( Channel.class );
+        }
+
+    } );
 ...
-Digester digester = digesterLoader.createDigester(Channel.class);
-try {
-    Channel channel = (Channel) digester.parse(new URL("http://www.myfeedprovider.com/rss.xml").openStream());
-} catch (Exception e) {
+Digester digester = digesterLoader.newDigester();
+try
+{
+    Channel channel = digester.parse( new URL( "http://www.myfeedprovider.com/rss.xml" ).openStream()
);
+}
+catch (Exception e)
+{
     // do something
 }
     </source>
-
-    <h5>Notes</h5>
-    <p>If asking to the <code>DigesterLoader</code> instance more then
twice the
-    <code>Digester</code> for the same <code>Class&lt;?&gt;</code>,
the
-    <code>DigesterLoader</code> won't analize the target class for each request,
-    but rather will reuse cached results.</p>
-
-    <p>The same <code>DigesterLoader</code> instance can be reused to create
-    other <code>Digester</code> instances.</p>
        </subsection>
     </section>
   </body>



Mime
View raw message