Source for org.xml.sax.ErrorHandler

   1: // SAX error handler.
   2: // http://www.saxproject.org
   3: // No warranty; no copyright -- use this as you will.
   4: // $Id: ErrorHandler.java,v 1.1 2004/12/23 22:38:42 mark Exp $
   5: 
   6: package org.xml.sax;
   7: 
   8: 
   9: /**
  10:  * Basic interface for SAX error handlers.
  11:  *
  12:  * <blockquote>
  13:  * <em>This module, both source code and documentation, is in the
  14:  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  15:  * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
  16:  * for further information.
  17:  * </blockquote>
  18:  *
  19:  * <p>If a SAX application needs to implement customized error
  20:  * handling, it must implement this interface and then register an
  21:  * instance with the XML reader using the
  22:  * {@link org.xml.sax.XMLReader#setErrorHandler setErrorHandler}
  23:  * method.  The parser will then report all errors and warnings
  24:  * through this interface.</p>
  25:  *
  26:  * <p><strong>WARNING:</strong> If an application does <em>not</em>
  27:  * register an ErrorHandler, XML parsing errors will go unreported,
  28:  * except that <em>SAXParseException</em>s will be thrown for fatal errors.
  29:  * In order to detect validity errors, an ErrorHandler that does something
  30:  * with {@link #error error()} calls must be registered.</p>
  31:  *
  32:  * <p>For XML processing errors, a SAX driver must use this interface 
  33:  * in preference to throwing an exception: it is up to the application 
  34:  * to decide whether to throw an exception for different types of 
  35:  * errors and warnings.  Note, however, that there is no requirement that 
  36:  * the parser continue to report additional errors after a call to 
  37:  * {@link #fatalError fatalError}.  In other words, a SAX driver class 
  38:  * may throw an exception after reporting any fatalError.
  39:  * Also parsers may throw appropriate exceptions for non-XML errors.
  40:  * For example, {@link XMLReader#parse XMLReader.parse()} would throw
  41:  * an IOException for errors accessing entities or the document.</p>
  42:  *
  43:  * @since SAX 1.0
  44:  * @author David Megginson
  45:  * @version 2.0.1+ (sax2r3pre1)
  46:  * @see org.xml.sax.XMLReader#setErrorHandler
  47:  * @see org.xml.sax.SAXParseException 
  48:  */
  49: public interface ErrorHandler {
  50:     
  51:     
  52:     /**
  53:      * Receive notification of a warning.
  54:      *
  55:      * <p>SAX parsers will use this method to report conditions that
  56:      * are not errors or fatal errors as defined by the XML
  57:      * recommendation.  The default behaviour is to take no
  58:      * action.</p>
  59:      *
  60:      * <p>The SAX parser must continue to provide normal parsing events
  61:      * after invoking this method: it should still be possible for the
  62:      * application to process the document through to the end.</p>
  63:      *
  64:      * <p>Filters may use this method to report other, non-XML warnings
  65:      * as well.</p>
  66:      *
  67:      * @param exception The warning information encapsulated in a
  68:      *                  SAX parse exception.
  69:      * @exception org.xml.sax.SAXException Any SAX exception, possibly
  70:      *            wrapping another exception.
  71:      * @see org.xml.sax.SAXParseException 
  72:      */
  73:     public abstract void warning (SAXParseException exception)
  74:     throws SAXException;
  75:     
  76:     
  77:     /**
  78:      * Receive notification of a recoverable error.
  79:      *
  80:      * <p>This corresponds to the definition of "error" in section 1.2
  81:      * of the W3C XML 1.0 Recommendation.  For example, a validating
  82:      * parser would use this callback to report the violation of a
  83:      * validity constraint.  The default behaviour is to take no
  84:      * action.</p>
  85:      *
  86:      * <p>The SAX parser must continue to provide normal parsing
  87:      * events after invoking this method: it should still be possible
  88:      * for the application to process the document through to the end.
  89:      * If the application cannot do so, then the parser should report
  90:      * a fatal error even if the XML recommendation does not require
  91:      * it to do so.</p>
  92:      *
  93:      * <p>Filters may use this method to report other, non-XML errors
  94:      * as well.</p>
  95:      *
  96:      * @param exception The error information encapsulated in a
  97:      *                  SAX parse exception.
  98:      * @exception org.xml.sax.SAXException Any SAX exception, possibly
  99:      *            wrapping another exception.
 100:      * @see org.xml.sax.SAXParseException 
 101:      */
 102:     public abstract void error (SAXParseException exception)
 103:     throws SAXException;
 104:     
 105:     
 106:     /**
 107:      * Receive notification of a non-recoverable error.
 108:      *
 109:      * <p><strong>There is an apparent contradiction between the
 110:      * documentation for this method and the documentation for {@link
 111:      * org.xml.sax.ContentHandler#endDocument}.  Until this ambiguity
 112:      * is resolved in a future major release, clients should make no
 113:      * assumptions about whether endDocument() will or will not be
 114:      * invoked when the parser has reported a fatalError() or thrown
 115:      * an exception.</strong></p>
 116:      *
 117:      * <p>This corresponds to the definition of "fatal error" in
 118:      * section 1.2 of the W3C XML 1.0 Recommendation.  For example, a
 119:      * parser would use this callback to report the violation of a
 120:      * well-formedness constraint.</p>
 121:      *
 122:      * <p>The application must assume that the document is unusable
 123:      * after the parser has invoked this method, and should continue
 124:      * (if at all) only for the sake of collecting additional error
 125:      * messages: in fact, SAX parsers are free to stop reporting any
 126:      * other events once this method has been invoked.</p>
 127:      *
 128:      * @param exception The error information encapsulated in a
 129:      *                  SAX parse exception.  
 130:      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 131:      *            wrapping another exception.
 132:      * @see org.xml.sax.SAXParseException
 133:      */
 134:     public abstract void fatalError (SAXParseException exception)
 135:     throws SAXException;
 136:     
 137: }
 138: 
 139: // end of ErrorHandler.java