updated constructor documenation to current codebase
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/digester/trunk@1211627 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/site/xdoc/guide/constructor.xml b/src/site/xdoc/guide/constructor.xml
index 21dcc85..507c81e 100644
--- a/src/site/xdoc/guide/constructor.xml
+++ b/src/site/xdoc/guide/constructor.xml
@@ -24,21 +24,23 @@
</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><root>
- <bean super="true" rate="9.99" />
+ <bean super="true">
+ <rate>9.99<rate/>
+ </bean>
</root></source>
<p>That has to be mapped to the bean:</p>
<source>class MyBean
@@ -52,12 +54,12 @@
}</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 @@
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 @@
{
@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 @@
a new inner element <code><constructor-argument></code>:</p>
<source><digester-rules>
<pattern value="root/bean">
- <object-create-rule classname="MyBean">
+ <object-create-rule classname="MyBean
+ paramtypes="java.lang.Double,java.lang.Boolean">
<constructor-argument attrname="rate" type="java.lang.Double" />
- <constructor-argument attrname="super" type="java.lang.Boolean" />
+ <call-param-rule paramnumber="0" pattern="rate" />
+ <call-param-rule paramnumber="1" attrname="super" />
</object-create-rule>
</pattern>
</digester-rules></source>
