org.xml.sax.ErrorHandler Maven / Gradle / Ivy
/*
* Portions Copyright 2000-2008 Sun Microsystems, Inc. All Rights
* Reserved. Use is subject to license terms.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
*
* This program 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.
*
* This program 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 at /legal/license.txt).
*
* 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 Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 or visit www.sun.com if you need additional
* information or have any questions.
*/
// ErrorHandler.java - SAX error handler.
// http://www.saxproject.org
// Written by David Megginson
// No warranty; no copyright -- use this as you will.
package org.xml.sax;
/**
* Basic interface for SAX error handlers.
*
* 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.
*
* WARNING: If an application does not
* register an ErrorHandler, XML parsing errors will go unreported,
* except that SAXParseExceptions 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.
*
* 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.
*
* @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.
*
* 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.
*
* 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.
*
* Filters may use this method to report other, non-XML warnings
* as well.
*
* @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.
*
* 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.
*
* 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.
*
* Filters may use this method to report other, non-XML errors
* as well.
*
* @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.
*
* 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.
*
* 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.
*
* 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.
*
* @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