001: // SAX error handler.
002: // http://www.saxproject.org
003: // No warranty; no copyright -- use this as you will.
004: // $Id: ErrorHandler.java,v 1.1.1.1 2002/05/03 23:29:40 yuvalo Exp $
005:
006: package org.xml.sax;
007:
008: /**
009: * Basic interface for SAX error handlers.
010: *
011: * <blockquote>
012: * <em>This module, both source code and documentation, is in the
013: * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
014: * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
015: * for further information.
016: * </blockquote>
017: *
018: * <p>If a SAX application needs to implement customized error
019: * handling, it must implement this interface and then register an
020: * instance with the XML reader using the
021: * {@link org.xml.sax.XMLReader#setErrorHandler setErrorHandler}
022: * method. The parser will then report all errors and warnings
023: * through this interface.</p>
024: *
025: * <p><strong>WARNING:</strong> If an application does <em>not</em>
026: * register an ErrorHandler, XML parsing errors will go unreported
027: * and bizarre behaviour may result.</p>
028: *
029: * <p>For XML processing errors, a SAX driver must use this interface
030: * instead of throwing an exception: it is up to the application
031: * to decide whether to throw an exception for different types of
032: * errors and warnings. Note, however, that there is no requirement that
033: * the parser continue to provide useful information after a call to
034: * {@link #fatalError fatalError} (in other words, a SAX driver class
035: * could catch an exception and report a fatalError).</p>
036: *
037: * @since SAX 1.0
038: * @author David Megginson
039: * @version 2.0.1 (sax2r2)
040: * @see org.xml.sax.XMLReader#setErrorHandler
041: * @see org.xml.sax.SAXParseException
042: */
043: public interface ErrorHandler {
044:
045: /**
046: * Receive notification of a warning.
047: *
048: * <p>SAX parsers will use this method to report conditions that
049: * are not errors or fatal errors as defined by the XML 1.0
050: * recommendation. The default behaviour is to take no action.</p>
051: *
052: * <p>The SAX parser must continue to provide normal parsing events
053: * after invoking this method: it should still be possible for the
054: * application to process the document through to the end.</p>
055: *
056: * <p>Filters may use this method to report other, non-XML warnings
057: * as well.</p>
058: *
059: * @param exception The warning information encapsulated in a
060: * SAX parse exception.
061: * @exception org.xml.sax.SAXException Any SAX exception, possibly
062: * wrapping another exception.
063: * @see org.xml.sax.SAXParseException
064: */
065: public abstract void warning(SAXParseException exception)
066: throws SAXException;
067:
068: /**
069: * Receive notification of a recoverable error.
070: *
071: * <p>This corresponds to the definition of "error" in section 1.2
072: * of the W3C XML 1.0 Recommendation. For example, a validating
073: * parser would use this callback to report the violation of a
074: * validity constraint. The default behaviour is to take no
075: * action.</p>
076: *
077: * <p>The SAX parser must continue to provide normal parsing events
078: * after invoking this method: it should still be possible for the
079: * application to process the document through to the end. If the
080: * application cannot do so, then the parser should report a fatal
081: * error even if the XML 1.0 recommendation does not require it to
082: * do so.</p>
083: *
084: * <p>Filters may use this method to report other, non-XML errors
085: * as well.</p>
086: *
087: * @param exception The error information encapsulated in a
088: * SAX parse exception.
089: * @exception org.xml.sax.SAXException Any SAX exception, possibly
090: * wrapping another exception.
091: * @see org.xml.sax.SAXParseException
092: */
093: public abstract void error(SAXParseException exception)
094: throws SAXException;
095:
096: /**
097: * Receive notification of a non-recoverable error.
098: *
099: * <p>This corresponds to the definition of "fatal error" in
100: * section 1.2 of the W3C XML 1.0 Recommendation. For example, a
101: * parser would use this callback to report the violation of a
102: * well-formedness constraint.</p>
103: *
104: * <p>The application must assume that the document is unusable
105: * after the parser has invoked this method, and should continue
106: * (if at all) only for the sake of collecting addition error
107: * messages: in fact, SAX parsers are free to stop reporting any
108: * other events once this method has been invoked.</p>
109: *
110: * @param exception The error information encapsulated in a
111: * SAX parse exception.
112: * @exception org.xml.sax.SAXException Any SAX exception, possibly
113: * wrapping another exception.
114: * @see org.xml.sax.SAXParseException
115: */
116: public abstract void fatalError(SAXParseException exception)
117: throws SAXException;
118:
119: }
120:
121: // end of ErrorHandler.java
|