001: // SAX error handler.
002: // http://www.saxproject.org
003: // No warranty; no copyright -- use this as you will.
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: * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
014: * for further information.
015: * </blockquote>
016: *
017: * <p>If a SAX application needs to implement customized error
018: * handling, it must implement this interface and then register an
019: * instance with the XML reader using the
020: * {@link org.xml.sax.XMLReader#setErrorHandler setErrorHandler}
021: * method. The parser will then report all errors and warnings
022: * through this interface.</p>
023: *
024: * <p><strong>WARNING:</strong> If an application does <em>not</em>
025: * register an ErrorHandler, XML parsing errors will go unreported,
026: * except that <em>SAXParseException</em>s will be thrown for fatal errors.
027: * In order to detect validity errors, an ErrorHandler that does something
028: * with {@link #error error()} calls must be registered.</p>
029: *
030: * <p>For XML processing errors, a SAX driver must use this interface
031: * in preference to throwing an exception: it is up to the application
032: * to decide whether to throw an exception for different types of
033: * errors and warnings. Note, however, that there is no requirement that
034: * the parser continue to report additional errors after a call to
035: * {@link #fatalError fatalError}. In other words, a SAX driver class
036: * may throw an exception after reporting any fatalError.
037: * Also parsers may throw appropriate exceptions for non-XML errors.
038: * For example, {@link XMLReader#parse XMLReader.parse()} would throw
039: * an IOException for errors accessing entities or the document.</p>
040: *
041: * @since SAX 1.0
042: * @author David Megginson
043: * @version 2.0.1+ (sax2r3pre1)
044: * @see org.xml.sax.XMLReader#setErrorHandler
045: * @see org.xml.sax.SAXParseException
046: */
047: public interface ErrorHandler {
048:
049: /**
050: * Receive notification of a warning.
051: *
052: * <p>SAX parsers will use this method to report conditions that
053: * are not errors or fatal errors as defined by the XML
054: * recommendation. The default behaviour is to take no
055: * action.</p>
056: *
057: * <p>The SAX parser must continue to provide normal parsing events
058: * after invoking this method: it should still be possible for the
059: * application to process the document through to the end.</p>
060: *
061: * <p>Filters may use this method to report other, non-XML warnings
062: * as well.</p>
063: *
064: * @param exception The warning information encapsulated in a
065: * SAX parse exception.
066: * @exception org.xml.sax.SAXException Any SAX exception, possibly
067: * wrapping another exception.
068: * @see org.xml.sax.SAXParseException
069: */
070: public abstract void warning(SAXParseException exception)
071: throws SAXException;
072:
073: /**
074: * Receive notification of a recoverable error.
075: *
076: * <p>This corresponds to the definition of "error" in section 1.2
077: * of the W3C XML 1.0 Recommendation. For example, a validating
078: * parser would use this callback to report the violation of a
079: * validity constraint. The default behaviour is to take no
080: * action.</p>
081: *
082: * <p>The SAX parser must continue to provide normal parsing
083: * events after invoking this method: it should still be possible
084: * for the application to process the document through to the end.
085: * If the application cannot do so, then the parser should report
086: * a fatal error even if the XML recommendation does not require
087: * it to do so.</p>
088: *
089: * <p>Filters may use this method to report other, non-XML errors
090: * as well.</p>
091: *
092: * @param exception The error information encapsulated in a
093: * SAX parse exception.
094: * @exception org.xml.sax.SAXException Any SAX exception, possibly
095: * wrapping another exception.
096: * @see org.xml.sax.SAXParseException
097: */
098: public abstract void error(SAXParseException exception)
099: throws SAXException;
100:
101: /**
102: * Receive notification of a non-recoverable error.
103: *
104: * <p><strong>There is an apparent contradiction between the
105: * documentation for this method and the documentation for {@link
106: * org.xml.sax.ContentHandler#endDocument}. Until this ambiguity
107: * is resolved in a future major release, clients should make no
108: * assumptions about whether endDocument() will or will not be
109: * invoked when the parser has reported a fatalError() or thrown
110: * an exception.</strong></p>
111: *
112: * <p>This corresponds to the definition of "fatal error" in
113: * section 1.2 of the W3C XML 1.0 Recommendation. For example, a
114: * parser would use this callback to report the violation of a
115: * well-formedness constraint.</p>
116: *
117: * <p>The application must assume that the document is unusable
118: * after the parser has invoked this method, and should continue
119: * (if at all) only for the sake of collecting additional error
120: * messages: in fact, SAX parsers are free to stop reporting any
121: * other events once this method has been invoked.</p>
122: *
123: * @param exception The error information encapsulated in a
124: * SAX parse exception.
125: * @exception org.xml.sax.SAXException Any SAX exception, possibly
126: * wrapping another exception.
127: * @see org.xml.sax.SAXParseException
128: */
129: public abstract void fatalError(SAXParseException exception)
130: throws SAXException;
131:
132: }
133:
134: // end of ErrorHandler.java
|