/* |
|
* Copyright (c) 2000, 2012, Oracle and/or its affiliates. All rights reserved. |
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
* |
|
* This code is free software; you can redistribute it and/or modify it |
|
* under the terms of the GNU General Public License version 2 only, as |
|
* published by the Free Software Foundation. Oracle designates this |
|
* particular file as subject to the "Classpath" exception as provided |
|
* by Oracle in the LICENSE file that accompanied this code. |
|
* |
|
* This code is distributed in the hope that it will be useful, but WITHOUT |
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
* version 2 for more details (a copy is included in the LICENSE file that |
|
* accompanied this code). |
|
* |
|
* You should have received a copy of the GNU General Public License version |
|
* 2 along with this work; if not, write to the Free Software Foundation, |
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
* |
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
* or visit www.oracle.com if you need additional information or have any |
|
* questions. |
|
*/ |
|
// SAX error handler. |
|
// http://www.saxproject.org |
|
// No warranty; no copyright -- use this as you will. |
|
// $Id: ErrorHandler.java,v 1.2 2004/11/03 22:44:52 jsuttor Exp $ |
|
package jdk.internal.org.xml.sax; |
|
/** |
|
* Basic interface for SAX error handlers. |
|
* |
|
* <blockquote> |
|
* <em>This module, both source code and documentation, is in the |
|
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> |
|
* See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> |
|
* for further information. |
|
* </blockquote> |
|
* |
|
* <p>If a SAX application needs to implement customized error |
|
* handling, it must implement this interface and then register an |
|
* instance with the XML reader using the |
|
* {@link org.xml.sax.XMLReader#setErrorHandler setErrorHandler} |
|
* method. The parser will then report all errors and warnings |
|
* through this interface.</p> |
|
* |
|
* <p><strong>WARNING:</strong> If an application does <em>not</em> |
|
* register an ErrorHandler, XML parsing errors will go unreported, |
|
* except that <em>SAXParseException</em>s will be thrown for fatal errors. |
|
* In order to detect validity errors, an ErrorHandler that does something |
|
* with {@link #error error()} calls must be registered.</p> |
|
* |
|
* <p>For XML processing errors, a SAX driver must use this interface |
|
* in preference to throwing an exception: it is up to the application |
|
* to decide whether to throw an exception for different types of |
|
* errors and warnings. Note, however, that there is no requirement that |
|
* the parser continue to report additional errors after a call to |
|
* {@link #fatalError fatalError}. In other words, a SAX driver class |
|
* may throw an exception after reporting any fatalError. |
|
* Also parsers may throw appropriate exceptions for non-XML errors. |
|
* For example, {@link XMLReader#parse XMLReader.parse()} would throw |
|
* an IOException for errors accessing entities or the document.</p> |
|
* |
|
* @since SAX 1.0 |
|
* @author David Megginson |
|
* @see org.xml.sax.XMLReader#setErrorHandler |
|
* @see org.xml.sax.SAXParseException |
|
*/ |
|
public interface ErrorHandler { |
|
/** |
|
* Receive notification of a warning. |
|
* |
|
* <p>SAX parsers will use this method to report conditions that |
|
* are not errors or fatal errors as defined by the XML |
|
* recommendation. The default behaviour is to take no |
|
* action.</p> |
|
* |
|
* <p>The SAX parser must continue to provide normal parsing events |
|
* after invoking this method: it should still be possible for the |
|
* application to process the document through to the end.</p> |
|
* |
|
* <p>Filters may use this method to report other, non-XML warnings |
|
* as well.</p> |
|
* |
|
* @param exception The warning information encapsulated in a |
|
* SAX parse exception. |
|
* @exception org.xml.sax.SAXException Any SAX exception, possibly |
|
* wrapping another exception. |
|
* @see org.xml.sax.SAXParseException |
|
*/ |
|
public abstract void warning (SAXParseException exception) |
|
throws SAXException; |
|
/** |
|
* Receive notification of a recoverable error. |
|
* |
|
* <p>This corresponds to the definition of "error" in section 1.2 |
|
* of the W3C XML 1.0 Recommendation. For example, a validating |
|
* parser would use this callback to report the violation of a |
|
* validity constraint. The default behaviour is to take no |
|
* action.</p> |
|
* |
|
* <p>The SAX parser must continue to provide normal parsing |
|
* events after invoking this method: it should still be possible |
|
* for the application to process the document through to the end. |
|
* If the application cannot do so, then the parser should report |
|
* a fatal error even if the XML recommendation does not require |
|
* it to do so.</p> |
|
* |
|
* <p>Filters may use this method to report other, non-XML errors |
|
* as well.</p> |
|
* |
|
* @param exception The error information encapsulated in a |
|
* SAX parse exception. |
|
* @exception org.xml.sax.SAXException Any SAX exception, possibly |
|
* wrapping another exception. |
|
* @see org.xml.sax.SAXParseException |
|
*/ |
|
public abstract void error (SAXParseException exception) |
|
throws SAXException; |
|
/** |
|
* Receive notification of a non-recoverable error. |
|
* |
|
* <p><strong>There is an apparent contradiction between the |
|
* documentation for this method and the documentation for {@link |
|
* org.xml.sax.ContentHandler#endDocument}. Until this ambiguity |
|
* is resolved in a future major release, clients should make no |
|
* assumptions about whether endDocument() will or will not be |
|
* invoked when the parser has reported a fatalError() or thrown |
|
* an exception.</strong></p> |
|
* |
|
* <p>This corresponds to the definition of "fatal error" in |
|
* section 1.2 of the W3C XML 1.0 Recommendation. For example, a |
|
* parser would use this callback to report the violation of a |
|
* well-formedness constraint.</p> |
|
* |
|
* <p>The application must assume that the document is unusable |
|
* after the parser has invoked this method, and should continue |
|
* (if at all) only for the sake of collecting additional error |
|
* messages: in fact, SAX parsers are free to stop reporting any |
|
* other events once this method has been invoked.</p> |
|
* |
|
* @param exception The error information encapsulated in a |
|
* SAX parse exception. |
|
* @exception org.xml.sax.SAXException Any SAX exception, possibly |
|
* wrapping another exception. |
|
* @see org.xml.sax.SAXParseException |
|
*/ |
|
public abstract void fatalError (SAXParseException exception) |
|
throws SAXException; |
|
} |
|
// end of ErrorHandler.java |