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