RE: Digester - addSetTop vs. addSetNext

[Ri...@ubsw.com]

Does someone have a minute to explain the difference between addSetTop 
vs. addSetNext?


Visit our website at http://www.ubswarburg.com

This message contains confidential information and is intended only 
for the individual named.  If you are not the named addressee you 
should not disseminate, distribute or copy this e-mail.  Please 
notify the sender immediately by e-mail if you have received this 
e-mail by mistake and delete this e-mail from your system.

E-mail transmission cannot be guaranteed to be secure or error-free 
as information could be intercepted, corrupted, lost, destroyed, 
arrive late or incomplete, or contain viruses.  The sender therefore 
does not accept liability for any errors or omissions in the contents 
of this message which arise as a result of e-mail transmission.  If 
verification is required please request a hard-copy version.  This 
message is provided for informational purposes and should not be 
construed as a solicitation or offer to buy or sell any securities or 
related financial instruments.

Re: Digester - addSetTop vs. addSetNext

["Craig R. McClanahan" <Cr...@eng.sun.com>]

Richard.Cammarano@ubsw.com wrote:

> Does someone have a minute to explain the difference between addSetTop
> vs. addSetNext?
>

Sure ... and in return I will ask you to help me name these rules more
clearly :-).

Consider that, while a DIgester is running, you are creating a stack of
objects.  New objects are pushed when you execute an "object create" rule,
and they are popped off when that tag is finished.  So, let's assume that
you've got object create rules for patterns "A", "A/B", and "A/B/C" like
this:

    digester.addObjectCreate("A", "MyClassA");
    digester.addObjectCreate("A/B", "MyClassB");
    digester.addObjectCreate("A/B/C", "MyClassC");

and you process the following XML:

    <A>
        <B>
            <C/>
        </B>
    </A>

As you are processing tag C (just after the "object create" rule has been
executed), the stack looks like this, with the most recently added object
at the top:

    MyObjectC
    MyObjectB
    MyObjectA

Now, it is very commonly the case that you want to relate these objects in
some sort of parent-child hierarchy.  To enable this, your MyClassB class
has a "addC" method that takes a "MyClassC" as a parameter.  We want a
call to this method generated automatically, so we add the following rule:

    digester.addSetNext("A/B/C", "addC", "MyClassC");

which tells the Digester to call a method on the *next to top* object on
the stack (MyObjectB, in this case).  The method called is "addC", and the
parameter that is passed is the *top* object on the stack.  The third
argument says that the addC method expects an object of class "MyClassC",
which we are assuming is the class type of MyObjectC.

Now, what would be different if we used setTop() instead?  In that case,
Digester would call a method on the *top* object of the stack (MyObjectC),
passing the *next to top* object (MyObjectB) as the argument.  In other
words, the order of calling is reversed.

In my own experience, I tend to use "set next" rules more often, because I
usually model my parent-child relationships by having an "addChild" type
method in the parent.  The "set top" rule would be useful if you have a
"setParent" type method in the child class, instead.

For a concrete example of using Digester, look at the initMapping() method
of the org.apache.struts.action.ActionServlet class (i.e. the controller
servlet in Struts).  You will see how it sets up the rules that parse the
"action.xml" file, including several cases where a "set next" type rule is
used as I described above.

Does that help?

Craig McClanahan

====================
See you at ApacheCon Europe <http://www.apachecon.com>!
Session VS01 (23-Oct 13h00-17h00):  Sun Technical Briefing
Session T06  (24-Oct 14h00-15h00):  Migrating Apache JServ
                                    Applications to Tomcat