001: // SAX error handler.
002: // No warranty; no copyright -- use this as you will.
003: // $Id: ErrorHandler.java,v 1.1 2004/12/05 04:06:22 csilva Exp $
004:
005: package org.xml.sax;
006:
007: /**
008: * Basic interface for SAX error handlers.
009: *
010: * <p>If a SAX application needs to implement customized error
011: * handling, it must implement this interface and then register an
012: * instance with the SAX parser using the parser's setErrorHandler
013: * method. The parser will then report all errors and warnings
014: * through this interface.</p>
015: *
016: * <p> The parser shall use this interface instead of throwing an
017: * exception: it is up to the application whether to throw an
018: * exception for different types of errors and warnings. Note,
019: * however, that there is no requirement that the parser continue to
020: * provide useful information after a call to fatalError (in other
021: * words, a SAX driver class could catch an exception and report a
022: * fatalError).</p>
023: *
024: * <p>The HandlerBase class provides a default implementation of this
025: * interface, ignoring warnings and recoverable errors and throwing a
026: * SAXParseException for fatal errors. An application may extend
027: * that class rather than implementing the complete interface
028: * itself.</p>
029: *
030: * @author David Megginson (ak117@freenet.carleton.ca)
031: * @version 1.0
032: * @see org.xml.sax.Parser#setErrorHandler
033: * @see org.xml.sax.SAXParseException
034: * @see org.xml.sax.HandlerBase
035: */
036: public interface ErrorHandler {
037:
038: /**
039: * Receive notification of a warning.
040: *
041: * <p>SAX parsers will use this method to report conditions that
042: * are not errors or fatal errors as defined by the XML 1.0
043: * recommendation. The default behaviour is to take no action.</p>
044: *
045: * <p>The SAX parser must continue to provide normal parsing events
046: * after invoking this method: it should still be possible for the
047: * application to process the document through to the end.</p>
048: *
049: * @param exception The warning information encapsulated in a
050: * SAX parse exception.
051: * @exception org.xml.sax.SAXException Any SAX exception, possibly
052: * wrapping another exception.
053: * @see org.xml.sax.SAXParseException
054: */
055: public abstract void warning(SAXParseException exception)
056: throws SAXException;
057:
058: /**
059: * Receive notification of a recoverable error.
060: *
061: * <p>This corresponds to the definition of "error" in section 1.2
062: * of the W3C XML 1.0 Recommendation. For example, a validating
063: * parser would use this callback to report the violation of a
064: * validity constraint. The default behaviour is to take no
065: * action.</p>
066: *
067: * <p>The SAX parser must continue to provide normal parsing events
068: * after invoking this method: it should still be possible for the
069: * application to process the document through to the end. If the
070: * application cannot do so, then the parser should report a fatal
071: * error even if the XML 1.0 recommendation does not require it to
072: * do so.</p>
073: *
074: * @param exception The error information encapsulated in a
075: * SAX parse exception.
076: * @exception org.xml.sax.SAXException Any SAX exception, possibly
077: * wrapping another exception.
078: * @see org.xml.sax.SAXParseException
079: */
080: public abstract void error(SAXParseException exception)
081: throws SAXException;
082:
083: /**
084: * Receive notification of a non-recoverable error.
085: *
086: * <p>This corresponds to the definition of "fatal error" in
087: * section 1.2 of the W3C XML 1.0 Recommendation. For example, a
088: * parser would use this callback to report the violation of a
089: * well-formedness constraint.</p>
090: *
091: * <p>The application must assume that the document is unusable
092: * after the parser has invoked this method, and should continue
093: * (if at all) only for the sake of collecting addition error
094: * messages: in fact, SAX parsers are free to stop reporting any
095: * other events once this method has been invoked.</p>
096: *
097: * @param exception The error information encapsulated in a
098: * SAX parse exception.
099: * @exception org.xml.sax.SAXException Any SAX exception, possibly
100: * wrapping another exception.
101: * @see org.xml.sax.SAXParseException
102: */
103: public abstract void fatalError(SAXParseException exception)
104: throws SAXException;
105:
106: }
|