| // SAX error handler. |
| // http://www.saxproject.org |
| // No warranty; no copyright -- use this as you will. |
| // $Id: ErrorHandler.java,v 1.10 2004/12/11 15:41:09 dog Exp $ |
| |
| package org.xml.sax; |
| |
| |
| /** |
| * Basic interface for SAX error handlers. |
| * |
| * <blockquote> |
| * <em>This module, both source code and documentation, is in the |
| * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> |
| * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> |
| * for further information. |
| * </blockquote> |
| * |
| * <p>If a SAX application needs to implement customized error |
| * handling, it must implement this interface and then register an |
| * instance with the XML reader using the |
| * {@link org.xml.sax.XMLReader#setErrorHandler setErrorHandler} |
| * method. The parser will then report all errors and warnings |
| * through this interface.</p> |
| * |
| * <p><strong>WARNING:</strong> If an application does <em>not</em> |
| * register an ErrorHandler, XML parsing errors will go unreported, |
| * except that <em>SAXParseException</em>s will be thrown for fatal errors. |
| * In order to detect validity errors, an ErrorHandler that does something |
| * with {@link #error error()} calls must be registered.</p> |
| * |
| * <p>For XML processing errors, a SAX driver must use this interface |
| * in preference to throwing an exception: it is up to the application |
| * to decide whether to throw an exception for different types of |
| * errors and warnings. Note, however, that there is no requirement that |
| * the parser continue to report additional errors after a call to |
| * {@link #fatalError fatalError}. In other words, a SAX driver class |
| * may throw an exception after reporting any fatalError. |
| * Also parsers may throw appropriate exceptions for non-XML errors. |
| * For example, {@link XMLReader#parse XMLReader.parse()} would throw |
| * an IOException for errors accessing entities or the document.</p> |
| * |
| * @since SAX 1.0 |
| * @author David Megginson |
| * @version 2.0.1+ (sax2r3pre1) |
| * @see org.xml.sax.XMLReader#setErrorHandler |
| * @see org.xml.sax.SAXParseException |
| */ |
| public interface ErrorHandler { |
| |
| |
| /** |
| * Receive notification of a warning. |
| * |
| * <p>SAX parsers will use this method to report conditions that |
| * are not errors or fatal errors as defined by the XML |
| * recommendation. The default behaviour is to take no |
| * action.</p> |
| * |
| * <p>The SAX parser must continue to provide normal parsing events |
| * after invoking this method: it should still be possible for the |
| * application to process the document through to the end.</p> |
| * |
| * <p>Filters may use this method to report other, non-XML warnings |
| * as well.</p> |
| * |
| * @param exception The warning information encapsulated in a |
| * SAX parse exception. |
| * @exception org.xml.sax.SAXException Any SAX exception, possibly |
| * wrapping another exception. |
| * @see org.xml.sax.SAXParseException |
| */ |
| public abstract void warning (SAXParseException exception) |
| throws SAXException; |
| |
| |
| /** |
| * Receive notification of a recoverable error. |
| * |
| * <p>This corresponds to the definition of "error" in section 1.2 |
| * of the W3C XML 1.0 Recommendation. For example, a validating |
| * parser would use this callback to report the violation of a |
| * validity constraint. The default behaviour is to take no |
| * action.</p> |
| * |
| * <p>The SAX parser must continue to provide normal parsing |
| * events after invoking this method: it should still be possible |
| * for the application to process the document through to the end. |
| * If the application cannot do so, then the parser should report |
| * a fatal error even if the XML recommendation does not require |
| * it to do so.</p> |
| * |
| * <p>Filters may use this method to report other, non-XML errors |
| * as well.</p> |
| * |
| * @param exception The error information encapsulated in a |
| * SAX parse exception. |
| * @exception org.xml.sax.SAXException Any SAX exception, possibly |
| * wrapping another exception. |
| * @see org.xml.sax.SAXParseException |
| */ |
| public abstract void error (SAXParseException exception) |
| throws SAXException; |
| |
| |
| /** |
| * Receive notification of a non-recoverable error. |
| * |
| * <p><strong>There is an apparent contradiction between the |
| * documentation for this method and the documentation for {@link |
| * org.xml.sax.ContentHandler#endDocument}. Until this ambiguity |
| * is resolved in a future major release, clients should make no |
| * assumptions about whether endDocument() will or will not be |
| * invoked when the parser has reported a fatalError() or thrown |
| * an exception.</strong></p> |
| * |
| * <p>This corresponds to the definition of "fatal error" in |
| * section 1.2 of the W3C XML 1.0 Recommendation. For example, a |
| * parser would use this callback to report the violation of a |
| * well-formedness constraint.</p> |
| * |
| * <p>The application must assume that the document is unusable |
| * after the parser has invoked this method, and should continue |
| * (if at all) only for the sake of collecting additional error |
| * messages: in fact, SAX parsers are free to stop reporting any |
| * other events once this method has been invoked.</p> |
| * |
| * @param exception The error information encapsulated in a |
| * SAX parse exception. |
| * @exception org.xml.sax.SAXException Any SAX exception, possibly |
| * wrapping another exception. |
| * @see org.xml.sax.SAXParseException |
| */ |
| public abstract void fatalError (SAXParseException exception) |
| throws SAXException; |
| |
| } |
| |
| // end of ErrorHandler.java |
