commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From simonetrip...@apache.org
Subject svn commit: r1211627 - /commons/proper/digester/trunk/src/site/xdoc/guide/constructor.xml
Date Wed, 07 Dec 2011 20:51:43 GMT
Author: simonetripodi
Date: Wed Dec  7 20:51:43 2011
New Revision: 1211627

URL: http://svn.apache.org/viewvc?rev=1211627&view=rev
Log:
updated constructor documenation to current codebase

Modified:
    commons/proper/digester/trunk/src/site/xdoc/guide/constructor.xml

Modified: commons/proper/digester/trunk/src/site/xdoc/guide/constructor.xml
URL: http://svn.apache.org/viewvc/commons/proper/digester/trunk/src/site/xdoc/guide/constructor.xml?rev=1211627&r1=1211626&r2=1211627&view=diff
==============================================================================
--- commons/proper/digester/trunk/src/site/xdoc/guide/constructor.xml (original)
+++ commons/proper/digester/trunk/src/site/xdoc/guide/constructor.xml Wed Dec  7 20:51:43
2011
@@ -24,21 +24,23 @@ limitations under the License.
   </properties>
   <body>
     <section name="Constructor based rule">
-      <p>One of the known limit of the old Digester releases is that the
+      <p>One of the missing features of the old Digester releases is that the
       <a href="../apidocs/org/apache/commons/digester3/ObjectCreateRule.html">ObjectCreateRule</a>
works just with
       the default empty constructor.</p>
       <p>One limit that cannot be exceeded is the fact that constructor arguments cannot
be extracted from inner
       XML elements; that's because the <code>ObjectCreateRule</code> creates
the object when the related XML
       element <code>begins</code>, otherwise properties could not be set when
parsing nested elements.</p>
-      <p>On the other hand, constructor arguments can still be extracted from <i>attributes</i>
of the matching
-      XML element for whom the <code>ObjectCreateRule</code> is triggered.</p>
+      <p>That is no longer true :) Constructor arguments can be extracted from <i>attributes</i>
and
+      <i>nested elements</i>of the matching XML element for whom the <code>ObjectCreateRule</code>
is triggered.</p>
       <p><b>NOTE</b> this feature is available since release 3.2.</p>
 
       <subsection name="Using plain old Digester APIs">
-        <p><code>ObjectCreateRule</code> has a new API to configure the
constructor arguments that have to be extracted
-        from the of the matching XML element attributes; given for example the XML snippet
below:</p>
+        <p><code>ObjectCreateRule</code> has new APIs to configure the
constructor arguments types; given for example
+        the XML snippet below:</p>
         <source>&lt;root&gt;
-  &lt;bean super="true" rate="9.99" /&gt;
+  &lt;bean super="true"&gt;
+    &lt;rate&gt;9.99&lt;rate/&gt;
+  &lt;/bean&gt;
 &lt;/root&gt;</source>
         <p>That has to be mapped to the bean:</p>
         <source>class MyBean
@@ -52,12 +54,12 @@ limitations under the License.
 }</source>
         <p>Then the <code>Digester</code> instance can be configured as
below:</p>
         <source>ObjectCreateRule createRule = new ObjectCreateRule( MyBean.class );
-createRule.addConstructorArgument( "rate", java.lang.Double.class );
-createRule.addConstructorArgument( "super", java.lang.Boolean.class );
+createRule.setConstructorArgumentTypes( boolean.class, double.class );
 
 Digester digester = new Digester();
-digester.addRule( "root/bean", createRule );</source>
-        <p><b>NOTE</b> The order that the arguments are expressed matters!</p>
+digester.addRule( "root/bean", createRule );
+digester.addCallParam( "root/bean", 1, "super" );
+digester.addCallParam( "root/bean/rate", 0 );</source>
       </subsection>
 
       <subsection name="Using the RulesBinder APIs">
@@ -69,9 +71,10 @@ digester.addRule( "root/bean", createRul
     protected void configure()
     {
         forPattern( "root/bean" )
-            .createObject().ofType( MyBean.class )
-                .addConstructorArgument( "rate" ).ofType( Double.class )
-                .addConstructorArgument( "super" ).ofType( Boolean.class );
+            .createObject().ofType( MyBean.class ).usingConstructor( boolean.class, double.class
)
+            .then()
+            .callParam().fromAttribute( "super" ).ofIndex( 1 );
+        forPattern( "root/bean/rate" ).callParam().ofIndex( 0 );
     }
 
 } );</source>
@@ -86,14 +89,13 @@ digester.addRule( "root/bean", createRul
 {
 
     @ObjectCreate( pattern = "root/bean" )
-    public MyBean( @Attribute( "rate" ) Double rate, @Attribute( "super" ) Boolean super
)
+    public MyBean( @CallParam( pattern = "root/bean/rate" ) Double rate,
+                   @CallParam( pattern = "root/bean", attributeName = "super" ) Boolean super
)
     {
         ...
     }
 
 }</source>
-        <p><b>NOTE</b> it is not possible in Java, using reflection, retrieving
constructors/methods arguments names,
-        that's why the <code>Attribute</code> annotation has to be added.</p>
       </subsection>
 
       <subsection name="Using the XML meta-descriptor">
@@ -101,9 +103,11 @@ digester.addRule( "root/bean", createRul
         a new inner element <code>&lt;constructor-argument&gt;</code>:</p>
         <source>&lt;digester-rules&gt;
   &lt;pattern value="root/bean"&gt;
-    &lt;object-create-rule classname="MyBean"&gt;
+    &lt;object-create-rule classname="MyBean
+          paramtypes="java.lang.Double,java.lang.Boolean"&gt;
       &lt;constructor-argument attrname="rate" type="java.lang.Double" /&gt;
-      &lt;constructor-argument attrname="super" type="java.lang.Boolean" /&gt;
+      &lt;call-param-rule paramnumber="0" pattern="rate" /&gt;
+      &lt;call-param-rule paramnumber="1" attrname="super" /&gt;
     &lt;/object-create-rule&gt;
   &lt;/pattern&gt;
 &lt;/digester-rules&gt;</source>



Mime
View raw message