After looking at the clear method, I'm not sure what the original intention of
the method was. It may be that it was never intended to be a public method at
all. I will ask on the email lists and see if anyone knows; digester arrived in
commons from the Tomcat project with this method already present and declared
It may be possible to perform repeated parses with the same Digester object
under some circumstances, but I wouldn't bet on it. If this is what you are
trying to achieve, I suggest you change your code to create a new Digester
object for each input document instead.
The root variable can't just be reset to null from within the clear method,
because clear() is called automatically at the end of the parse() method. This
leads me to think that maybe it is just intended to free up any memory and is
not meant to be used directly [ie shouldn't be public]. And while it could be
reset from the start of the parse method, there are heaps of other variables
that would also need to be reset in order to safely perform a second parse with
the same Digester object, eg namespaces and matches.
I have therefore added a javadoc comment to the clear method saying it shouldn't
be used. I think it might even be a good idea to deprecate it so it can be
removed in the release-after-next.
I don't believe your proposed patch for removing the root member entirely will
work correctly, unfortunately. The digester's parse method can be called without
any object present on the stack at start. In this case, the digester stack is
empty when the parse method returns. Your new getRoot method will therefore fail
to return the "first created object". See the "Catalog" example in CVS for an
app that would fail with this patch.
I'd like to leave this bug open as a reminder to think about the clear method a
bit more before the next release.
James, please add any comments you have to this bug entry.
And by the way, the attached patch file is all screwed up, due to windows/unix
line feed differences....