| Frames | No Frames |
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.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