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.10 2004/03/08 13:01:00 dmegginson 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 140
