001 // SAX error handler. 002 // http://www.saxproject.org 003 // No warranty; no copyright -- use this as you will. 004 // $Id: ErrorHandler.java,v 1.1 2004/12/23 22:38:42 mark Exp $ 005 006 package org.xml.sax; 007 008 009 /** 010 * Basic interface for SAX error handlers. 011 * 012 * <blockquote> 013 * <em>This module, both source code and documentation, is in the 014 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 015 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> 016 * for further information. 017 * </blockquote> 018 * 019 * <p>If a SAX application needs to implement customized error 020 * handling, it must implement this interface and then register an 021 * instance with the XML reader using the 022 * {@link org.xml.sax.XMLReader#setErrorHandler setErrorHandler} 023 * method. The parser will then report all errors and warnings 024 * through this interface.</p> 025 * 026 * <p><strong>WARNING:</strong> If an application does <em>not</em> 027 * register an ErrorHandler, XML parsing errors will go unreported, 028 * except that <em>SAXParseException</em>s will be thrown for fatal errors. 029 * In order to detect validity errors, an ErrorHandler that does something 030 * with {@link #error error()} calls must be registered.</p> 031 * 032 * <p>For XML processing errors, a SAX driver must use this interface 033 * in preference to throwing an exception: it is up to the application 034 * to decide whether to throw an exception for different types of 035 * errors and warnings. Note, however, that there is no requirement that 036 * the parser continue to report additional errors after a call to 037 * {@link #fatalError fatalError}. In other words, a SAX driver class 038 * may throw an exception after reporting any fatalError. 039 * Also parsers may throw appropriate exceptions for non-XML errors. 040 * For example, {@link XMLReader#parse XMLReader.parse()} would throw 041 * an IOException for errors accessing entities or the document.</p> 042 * 043 * @since SAX 1.0 044 * @author David Megginson 045 * @version 2.0.1+ (sax2r3pre1) 046 * @see org.xml.sax.XMLReader#setErrorHandler 047 * @see org.xml.sax.SAXParseException 048 */ 049 public interface ErrorHandler { 050 051 052 /** 053 * Receive notification of a warning. 054 * 055 * <p>SAX parsers will use this method to report conditions that 056 * are not errors or fatal errors as defined by the XML 057 * recommendation. The default behaviour is to take no 058 * action.</p> 059 * 060 * <p>The SAX parser must continue to provide normal parsing events 061 * after invoking this method: it should still be possible for the 062 * application to process the document through to the end.</p> 063 * 064 * <p>Filters may use this method to report other, non-XML warnings 065 * as well.</p> 066 * 067 * @param exception The warning information encapsulated in a 068 * SAX parse exception. 069 * @exception org.xml.sax.SAXException Any SAX exception, possibly 070 * wrapping another exception. 071 * @see org.xml.sax.SAXParseException 072 */ 073 public abstract void warning (SAXParseException exception) 074 throws SAXException; 075 076 077 /** 078 * Receive notification of a recoverable error. 079 * 080 * <p>This corresponds to the definition of "error" in section 1.2 081 * of the W3C XML 1.0 Recommendation. For example, a validating 082 * parser would use this callback to report the violation of a 083 * validity constraint. The default behaviour is to take no 084 * action.</p> 085 * 086 * <p>The SAX parser must continue to provide normal parsing 087 * events after invoking this method: it should still be possible 088 * for the application to process the document through to the end. 089 * If the application cannot do so, then the parser should report 090 * a fatal error even if the XML recommendation does not require 091 * it to do so.</p> 092 * 093 * <p>Filters may use this method to report other, non-XML errors 094 * as well.</p> 095 * 096 * @param exception The error information encapsulated in a 097 * SAX parse exception. 098 * @exception org.xml.sax.SAXException Any SAX exception, possibly 099 * 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