| 1 |
768 |
jeremybenn |
// 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
|
