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