arabica/SAX/ErrorHandler.h
2002-06-21 11:16:28 +00:00

114 lines
4 KiB
C++

#ifndef ErrorHandlerH
#define ErrorHandlerH
// EntityResolver.h
// $Id$
#include <string>
#include <SAX/SAXException.h>
namespace SAX
{
/**
* Basic interface for SAX error handlers.
*
* <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 basic_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
* and bizarre behaviour may result.</p>
*
* <p>For XML processing errors, a SAX driver must use this interface
* instead of 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 provide useful information after a call to
* {@link #fatalError fatalError} (in other words, a SAX driver class
* could catch an exception and report a fatalError).</p>
*
* @since SAX 1.0
* @author Jez Higgins,
* <a href="mailto:jez@jezuk.co.uk">jez@jezuk.co.uk</a>
* @version 2.0
* @see basic_Parser#setErrorHandler
* @see basic_SAXParseException
*/
class ErrorHandler
{
public:
virtual ~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 1.0
* 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.
* @see basic_SAXParseException
*/
virtual void warning(const SAXException& exception) = 0;
/**
* 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 1.0 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.
* @see basic_SAXParseException
*/
virtual void error(const SAXException& exception) = 0;
/**
* Receive notification of a non-recoverable error.
*
* <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 addition 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.
* @see basic_SAXParseException
*/
virtual void fatalError(const SAXException& exception) = 0;
}; // class ErrorHandler
}; // namespace SAX
#endif
//end of file