001// SAX error handler. 002// No warranty; no copyright -- use this as you will. 003// $Id: ErrorHandler.java,v 1.1 2001/03/05 21:40:05 jstrachan Exp $ 004 005package org.xml.sax; 006 007 008/** 009 * Basic interface for SAX error handlers. 010 * 011 * <blockquote> 012 * <em>This module, both source code and documentation, is in the 013 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 014 * </blockquote> 015 * 016 * <p>If a SAX application needs to implement customized error 017 * handling, it must implement this interface and then register an 018 * instance with the XML reader using the 019 * {@link org.xml.sax.XMLReader#setErrorHandler setErrorHandler} 020 * method. The parser will then report all errors and warnings 021 * through this interface.</p> 022 * 023 * <p><strong>WARNING:</strong> If an application does <em>not</em> 024 * register an ErrorHandler, XML parsing errors will go unreported 025 * and bizarre behaviour may result.</p> 026 * 027 * <p>For XML processing errors, a SAX driver must use this interface 028 * instead of throwing an exception: it is up to the application 029 * to decide whether to throw an exception for different types of 030 * errors and warnings. Note, however, that there is no requirement that 031 * the parser continue to provide useful information after a call to 032 * {@link #fatalError fatalError} (in other words, a SAX driver class 033 * could catch an exception and report a fatalError).</p> 034 * 035 * @since SAX 1.0 036 * @author David Megginson, 037 * <a href="mailto:sax@megginson.com">sax@megginson.com</a> 038 * @version 2.0 039 * @see org.xml.sax.Parser#setErrorHandler 040 * @see org.xml.sax.SAXParseException 041 */ 042public interface ErrorHandler { 043 044 045 /** 046 * Receive notification of a warning. 047 * 048 * <p>SAX parsers will use this method to report conditions that 049 * are not errors or fatal errors as defined by the XML 1.0 050 * recommendation. The default behaviour is to take no action.</p> 051 * 052 * <p>The SAX parser must continue to provide normal parsing events 053 * after invoking this method: it should still be possible for the 054 * application to process the document through to the end.</p> 055 * 056 * <p>Filters may use this method to report other, non-XML warnings 057 * as well.</p> 058 * 059 * @param exception The warning information encapsulated in a 060 * SAX parse exception. 061 * @exception org.xml.sax.SAXException Any SAX exception, possibly 062 * wrapping another exception. 063 * @see org.xml.sax.SAXParseException 064 */ 065 public abstract void warning (SAXParseException exception) 066 throws SAXException; 067 068 069 /** 070 * Receive notification of a recoverable error. 071 * 072 * <p>This corresponds to the definition of "error" in section 1.2 073 * of the W3C XML 1.0 Recommendation. For example, a validating 074 * parser would use this callback to report the violation of a 075 * validity constraint. The default behaviour is to take no 076 * action.</p> 077 * 078 * <p>The SAX parser must continue to provide normal parsing events 079 * after invoking this method: it should still be possible for the 080 * application to process the document through to the end. If the 081 * application cannot do so, then the parser should report a fatal 082 * error even if the XML 1.0 recommendation does not require it to 083 * do so.</p> 084 * 085 * <p>Filters may use this method to report other, non-XML errors 086 * as well.</p> 087 * 088 * @param exception The error information encapsulated in a 089 * SAX parse exception. 090 * @exception org.xml.sax.SAXException Any SAX exception, possibly 091 * wrapping another exception. 092 * @see org.xml.sax.SAXParseException 093 */ 094 public abstract void error (SAXParseException exception) 095 throws SAXException; 096 097 098 /** 099 * Receive notification of a non-recoverable error. 100 * 101 * <p>This corresponds to the definition of "fatal error" in 102 * section 1.2 of the W3C XML 1.0 Recommendation. For example, a 103 * parser would use this callback to report the violation of a 104 * well-formedness constraint.</p> 105 * 106 * <p>The application must assume that the document is unusable 107 * after the parser has invoked this method, and should continue 108 * (if at all) only for the sake of collecting addition error 109 * messages: in fact, SAX parsers are free to stop reporting any 110 * other events once this method has been invoked.</p> 111 * 112 * @param exception The error information encapsulated in a 113 * SAX parse exception. 114 * @exception org.xml.sax.SAXException Any SAX exception, possibly 115 * wrapping another exception. 116 * @see org.xml.sax.SAXParseException 117 */ 118 public abstract void fatalError (SAXParseException exception) 119 throws SAXException; 120 121} 122 123// end of ErrorHandler.java