[Jakarta Commons Wiki] New: Digester/FAQ

[co...@jakarta.apache.org]

   Date: 2004-07-02T20:29:53
   Editor: SimonKitching <si...@ecnetwork.co.nz>
   Wiki: Jakarta Commons Wiki
   Page: Digester/FAQ
   URL: http://wiki.apache.org/jakarta-commons/Digester/FAQ

   Created FAQ

New Page:

##language:en

== The Apache Jakarta Commons Digester Frequently Asked Questions Page ==

=== Introduction ===

This page is intended to gather answers to questions that are regularly
asked on the digester email lists.

If you discovered something about the Digester that you think other people 
may find useful, please edit this page to add that information.

=== Why doesn't Digester throw SAXParseException when processing bad XML? ===

The Digester class extends org.xml.sax.helpers.!DefaultHandler, and the default
implementation it inherits from there is to completely ignore errors
reported during parsing.

You need to implement your own subclass of org.xml.sax.!ErrorHandler, and
ensure the class looks something like the following:

{{{
public class MyErrorHandler {
  void warning(SAXParseException ex) {
     // stop processing on warnings
    throw ex;
  }

  void error(SAXParseException ex) {
     // stop processing on errors
    throw ex;
  }

  void fatalError(SAXParseException ex) {
     // stop processing on fatal errors
    throw ex;
  }
}
}}}

You then need to tell Digester to use your errorhandler class, as follows:
{{{
  MyErrorHandler eh = new MyErrorHandler();
  digester.setErrorHandler(eh);
}}}

=== Can I reuse a Digester instance to parse more than one xml document? ===

Well, some people do. However this is not currently recommended.

The problems with reusing a Digester instance aren't related to multi-thread
synchronization. The problem is that the Digester class has quite a few member
variables whose values "evolve" as SAX events are received during a parse.

When reusing the Digester instance, you therefore need to ensure that all those
members are reset back to their initial states before the second parse begins. 

The "clear()" method makes a stab at resetting these, but it is actually rather
a difficult problem.

If you are determined to reuse Digester instances, then at the least you should
call the clear() method before each parse, and <i>must</i> call it if the
Digester parse terminates due to an exception during a parse. This method is 
called automatically when the SAX event "endDocument" is received; however when 
a parse fails part-way through, this event is never generated so the clear() 
method is never invoked. 

A much cleaner solution is simply to create a new Digester instance for each XML
document parsed. If you are concerned about performance then you might want to 
create a !RulesBase object, add rule instances to it, then reuse that object but 
create a separate Digester object each time. Unlike the Digester class, the Rule
and !RulesBase classes are not supposed to be modified by the parsing, ie are 
"stateless" with respect to the sax parsing stage and so are pretty safe to reuse.


---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org