libjava/org/xml/sax/ErrorHandler.java

   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.4.2.3 2002/01/29 21:34:14 dbrownell 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  * and bizarre behaviour may result.</p>
  29  *
  30  * <p>For XML processing errors, a SAX driver must use this interface
  31  * instead of throwing an exception: it is up to the application
  32  * to decide whether to throw an exception for different types of
  33  * errors and warnings.  Note, however, that there is no requirement that
  34  * the parser continue to provide useful information after a call to
  35  * {@link #fatalError fatalError} (in other words, a SAX driver class
  36  * could catch an exception and report a fatalError).</p>
  37  *
  38  * @since SAX 1.0
  39  * @author David Megginson
  40  * @version 2.0.1 (sax2r2)
  41  * @see org.xml.sax.XMLReader#setErrorHandler
  42  * @see org.xml.sax.SAXParseException
  43  */
  44 public interface ErrorHandler {
  45
  46
  47     /**
  48      * Receive notification of a warning.
  49      *
  50      * <p>SAX parsers will use this method to report conditions that
  51      * are not errors or fatal errors as defined by the XML 1.0
  52      * recommendation.  The default behaviour is to take no action.</p>
  53      *
  54      * <p>The SAX parser must continue to provide normal parsing events
  55      * after invoking this method: it should still be possible for the
  56      * application to process the document through to the end.</p>
  57      *
  58      * <p>Filters may use this method to report other, non-XML warnings
  59      * as well.</p>
  60      *
  61      * @param exception The warning information encapsulated in a
  62      *                  SAX parse exception.
  63      * @exception org.xml.sax.SAXException Any SAX exception, possibly
  64      *            wrapping another exception.
  65      * @see org.xml.sax.SAXParseException
  66      */
  67     public abstract void warning (SAXParseException exception)
  68         throws SAXException;
  69
  70
  71     /**
  72      * Receive notification of a recoverable error.
  73      *
  74      * <p>This corresponds to the definition of "error" in section 1.2
  75      * of the W3C XML 1.0 Recommendation.  For example, a validating
  76      * parser would use this callback to report the violation of a
  77      * validity constraint.  The default behaviour is to take no
  78      * action.</p>
  79      *
  80      * <p>The SAX parser must continue to provide normal parsing events
  81      * after invoking this method: it should still be possible for the
  82      * application to process the document through to the end.  If the
  83      * application cannot do so, then the parser should report a fatal
  84      * error even if the XML 1.0 recommendation does not require it to
  85      * do so.</p>
  86      *
  87      * <p>Filters may use this method to report other, non-XML errors
  88      * as well.</p>
  89      *
  90      * @param exception The error information encapsulated in a
  91      *                  SAX parse exception.
  92      * @exception org.xml.sax.SAXException Any SAX exception, possibly
  93      *            wrapping another exception.
  94      * @see org.xml.sax.SAXParseException
  95      */
  96     public abstract void error (SAXParseException exception)
  97         throws SAXException;
  98
  99
 100     /**
 101      * Receive notification of a non-recoverable error.
 102      *
 103      * <p>This corresponds to the definition of "fatal error" in
 104      * section 1.2 of the W3C XML 1.0 Recommendation.  For example, a
 105      * parser would use this callback to report the violation of a
 106      * well-formedness constraint.</p>
 107      *
 108      * <p>The application must assume that the document is unusable
 109      * after the parser has invoked this method, and should continue
 110      * (if at all) only for the sake of collecting addition error
 111      * messages: in fact, SAX parsers are free to stop reporting any
 112      * other events once this method has been invoked.</p>
 113      *
 114      * @param exception The error information encapsulated in a
 115      *                  SAX parse exception.
 116      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 117      *            wrapping another exception.
 118      * @see org.xml.sax.SAXParseException
 119      */
 120     public abstract void fatalError (SAXParseException exception)
 121         throws SAXException;
 122
 123 }
 124
 125 // end of ErrorHandler.java