commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rdon...@apache.org
Subject cvs commit: jakarta-commons/digester/src/java/org/apache/commons/digester package.html
Date Tue, 13 Jan 2004 20:23:26 GMT
rdonkin     2004/01/13 12:23:26

  Modified:    digester/src/java/org/apache/commons/digester package.html
  Log:
  Added debugging tips concerning SAX error handling.
  
  Revision  Changes    Path
  1.25      +41 -1     jakarta-commons/digester/src/java/org/apache/commons/digester/package.html
  
  Index: package.html
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/digester/src/java/org/apache/commons/digester/package.html,v
  retrieving revision 1.24
  retrieving revision 1.25
  diff -u -r1.24 -r1.25
  --- package.html	6 Jan 2004 22:15:57 -0000	1.24
  +++ package.html	13 Jan 2004 20:23:25 -0000	1.25
  @@ -19,6 +19,7 @@
   <a href="#doc.Namespace">[Namespace Aware Parsing]</a>
   <a href="#doc.Pluggable">[Pluggable Rules Processing]</a>
   <a href="#doc.RuleSets">[Encapsulated Rule Sets]</a>
  +<a href="#doc.troubleshooting">[Troubleshooting]</a>
   <a href="#doc.FAQ">[FAQ]</a>
   <a href="#doc.Limits">[Known Limitations]</a>
   </div>
  @@ -992,7 +993,46 @@
       the same set of nested elements at different nesting levels within an
       XML document.</li>
   </ul>
  -
  +<a name="doc.troubleshooting"></a>
  +<h3>Troubleshooting</h3>
  +<h4>Debugging Exceptions</h4>
  +<p>
  +<code>Digester</code> is based on <a href='http://www.saxproject.org'>SAX</a>.
  +Digestion throws two kinds of <code>Exception</code>:
  +</p>
  +<ul>
  +    <li><code>java.io.IOException</code></li>
  +    <li><code>org.xml.sax.SAXException</code></li>
  +</ul>
  +<p>
  +The first is rarely thrown and indicates the kind of fundemental IO exception
  +that developers know all about. The second is thrown by SAX parsers when the processing
  +of the XML cannot be completed. So, to diagnose the cause a certain familiarity with 
  +the way that SAX error handling works is very useful. 
  +</p>
  +<h5>Diagnosing SAX Exceptions</h5>
  +<p>
  +This is a short, potted guide to SAX error handling strategies. It's not intended as a
  +proper guide to error handling in SAX.
  +</p>
  +<p>
  +When a SAX parser encounters a problem with the xml (well, ok - sometime after it 
  +encounters a problem) it will throw a 
  +<a href='http://www.saxproject.org/apidoc/org/xml/sax/SAXParseException.html'>
  +SAXParseException</a>. This is a subclass of <code>SAXException</code>
and contains
  +a bit of extra information about what exactly when wrong - and more importantly,
  +where it went wrong. If you catch an exception of this sort, you can be sure that
  +the problem is with the XML and not <code>Digester</code> or your rules.
  +It is usually a good idea to catch this exception and log the extra information
  +to help with diagnosing the reason for the failure.
  +</p>
  +<p>
  +General <a href='http://www.saxproject.org/apidoc/org/xml/sax/SAXException.html'>
  +SAXException</a>'s may wrap a causal exception. When exceptions are
  +throw by <code>Digester</code> each of these will be wrapped into a 
  +<code>SAXException</code> and rethrown. So, catch these and examine the wrapped
  +exception to diagnose what went wrong.
  +</p>
   <a name="doc.FAQ"></a>
   <h3>Frequently Asked Questions</h3>
   <p><ul>
  
  
  

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


Mime
View raw message