1adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project// SAX error handler. 2adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project// http://www.saxproject.org 3adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project// No warranty; no copyright -- use this as you will. 4adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project// $Id: ErrorHandler.java,v 1.10 2004/03/08 13:01:00 dmegginson Exp $ 5adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 6adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpackage org.xml.sax; 7adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 8adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 9adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/** 10adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Basic interface for SAX error handlers. 11adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 12adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <blockquote> 13adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <em>This module, both source code and documentation, is in the 14adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 15adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> 16adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * for further information. 17adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </blockquote> 18adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 19adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>If a SAX application needs to implement customized error 20adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * handling, it must implement this interface and then register an 21adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * instance with the XML reader using the 22adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * {@link org.xml.sax.XMLReader#setErrorHandler setErrorHandler} 23adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * method. The parser will then report all errors and warnings 24adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * through this interface.</p> 25adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 26adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>WARNING:</strong> If an application does <em>not</em> 27adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * register an ErrorHandler, XML parsing errors will go unreported, 28adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * except that <em>SAXParseException</em>s will be thrown for fatal errors. 29adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * In order to detect validity errors, an ErrorHandler that does something 30adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * with {@link #error error()} calls must be registered.</p> 31adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 32f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p>For XML processing errors, a SAX driver must use this interface 33f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * in preference to throwing an exception: it is up to the application 34f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * to decide whether to throw an exception for different types of 35f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * errors and warnings. Note, however, that there is no requirement that 36f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the parser continue to report additional errors after a call to 37f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * {@link #fatalError fatalError}. In other words, a SAX driver class 38adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * may throw an exception after reporting any fatalError. 39adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Also parsers may throw appropriate exceptions for non-XML errors. 40adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * For example, {@link XMLReader#parse XMLReader.parse()} would throw 41adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * an IOException for errors accessing entities or the document.</p> 42adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 43adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @since SAX 1.0 44adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @author David Megginson 45adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @version 2.0.1+ (sax2r3pre1) 46adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see org.xml.sax.XMLReader#setErrorHandler 47f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @see org.xml.sax.SAXParseException 48adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 49adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpublic interface ErrorHandler { 50f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 51f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 52adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 53adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Receive notification of a warning. 54adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 55adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>SAX parsers will use this method to report conditions that 56adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * are not errors or fatal errors as defined by the XML 57adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * recommendation. The default behaviour is to take no 58adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * action.</p> 59adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 60adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>The SAX parser must continue to provide normal parsing events 61adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * after invoking this method: it should still be possible for the 62adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * application to process the document through to the end.</p> 63adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 64adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>Filters may use this method to report other, non-XML warnings 65adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * as well.</p> 66adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 67adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param exception The warning information encapsulated in a 68adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * SAX parse exception. 69adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @exception org.xml.sax.SAXException Any SAX exception, possibly 70adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * wrapping another exception. 71f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @see org.xml.sax.SAXParseException 72adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 73adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public abstract void warning (SAXParseException exception) 74adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws SAXException; 75f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 76f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 77adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 78adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Receive notification of a recoverable error. 79adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 80adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>This corresponds to the definition of "error" in section 1.2 81adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * of the W3C XML 1.0 Recommendation. For example, a validating 82adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * parser would use this callback to report the violation of a 83adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * validity constraint. The default behaviour is to take no 84adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * action.</p> 85adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 86adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>The SAX parser must continue to provide normal parsing 87adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * events after invoking this method: it should still be possible 88adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * for the application to process the document through to the end. 89adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * If the application cannot do so, then the parser should report 90adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * a fatal error even if the XML recommendation does not require 91adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * it to do so.</p> 92adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 93adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>Filters may use this method to report other, non-XML errors 94adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * as well.</p> 95adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 96adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param exception The error information encapsulated in a 97adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * SAX parse exception. 98adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @exception org.xml.sax.SAXException Any SAX exception, possibly 99adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * wrapping another exception. 100f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @see org.xml.sax.SAXParseException 101adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 102adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public abstract void error (SAXParseException exception) 103adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws SAXException; 104f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 105f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 106adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 107adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Receive notification of a non-recoverable error. 108adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 109adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p><strong>There is an apparent contradiction between the 110adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * documentation for this method and the documentation for {@link 111adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * org.xml.sax.ContentHandler#endDocument}. Until this ambiguity 112adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * is resolved in a future major release, clients should make no 113adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * assumptions about whether endDocument() will or will not be 114adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * invoked when the parser has reported a fatalError() or thrown 115adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * an exception.</strong></p> 116adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 117adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>This corresponds to the definition of "fatal error" in 118adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * section 1.2 of the W3C XML 1.0 Recommendation. For example, a 119adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * parser would use this callback to report the violation of a 120adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * well-formedness constraint.</p> 121adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 122adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <p>The application must assume that the document is unusable 123adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * after the parser has invoked this method, and should continue 124adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (if at all) only for the sake of collecting additional error 125adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * messages: in fact, SAX parsers are free to stop reporting any 126adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * other events once this method has been invoked.</p> 127adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 128adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param exception The error information encapsulated in a 129f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * SAX parse exception. 130adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @exception org.xml.sax.SAXException Any SAX exception, possibly 131adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * wrapping another exception. 132adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @see org.xml.sax.SAXParseException 133adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 134adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public abstract void fatalError (SAXParseException exception) 135adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throws SAXException; 136f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 137adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project} 138adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 139adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project// end of ErrorHandler.java 140