Home » xml-commons-external-1.4.01-src » org.xml » sax » [javadoc | source]

    1   // SAX error handler.
    2   // http://www.saxproject.org
    3   // No warranty; no copyright -- use this as you will.
    4   // $Id: ErrorHandler.java 226184 2005-04-08 10:53:24Z neeraj $
    5   
    6   package org.xml.sax;
    7   
    8   
    9   /**
   10    * Basic interface for SAX error handlers.
   11    *
   12    * <blockquote>
   13    * <em>This module, both source code and documentation, is in the
   14    * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
   15    * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
   16    * for further information.
   17    * </blockquote>
   18    *
   19    * <p>If a SAX application needs to implement customized error
   20    * handling, it must implement this interface and then register an
   21    * instance with the XML reader using the
   22    * {@link org.xml.sax.XMLReader#setErrorHandler setErrorHandler}
   23    * method.  The parser will then report all errors and warnings
   24    * through this interface.</p>
   25    *
   26    * <p><strong>WARNING:</strong> If an application does <em>not</em>
   27    * register an ErrorHandler, XML parsing errors will go unreported,
   28    * except that <em>SAXParseException</em>s will be thrown for fatal errors.
   29    * In order to detect validity errors, an ErrorHandler that does something
   30    * with {@link #error error()} calls must be registered.</p>
   31    *
   32    * <p>For XML processing errors, a SAX driver must use this interface 
   33    * in preference to throwing an exception: it is up to the application 
   34    * to decide whether to throw an exception for different types of 
   35    * errors and warnings.  Note, however, that there is no requirement that 
   36    * the parser continue to report additional errors after a call to 
   37    * {@link #fatalError fatalError}.  In other words, a SAX driver class 
   38    * may throw an exception after reporting any fatalError.
   39    * Also parsers may throw appropriate exceptions for non-XML errors.
   40    * For example, {@link XMLReader#parse XMLReader.parse()} would throw
   41    * an IOException for errors accessing entities or the document.</p>
   42    *
   43    * @since SAX 1.0
   44    * @author David Megginson
   45    * @version 2.0.1+ (sax2r3pre1)
   46    * @see org.xml.sax.XMLReader#setErrorHandler
   47    * @see org.xml.sax.SAXParseException 
   48    */
   49   public interface ErrorHandler {
   50       
   51       
   52       /**
   53        * Receive notification of a warning.
   54        *
   55        * <p>SAX parsers will use this method to report conditions that
   56        * are not errors or fatal errors as defined by the XML
   57        * recommendation.  The default behaviour is to take no
   58        * action.</p>
   59        *
   60        * <p>The SAX parser must continue to provide normal parsing events
   61        * after invoking this method: it should still be possible for the
   62        * application to process the document through to the end.</p>
   63        *
   64        * <p>Filters may use this method to report other, non-XML warnings
   65        * as well.</p>
   66        *
   67        * @param exception The warning information encapsulated in a
   68        *                  SAX parse exception.
   69        * @exception org.xml.sax.SAXException Any SAX exception, possibly
   70        *            wrapping another exception.
   71        * @see org.xml.sax.SAXParseException 
   72        */
   73       public abstract void warning (SAXParseException exception)
   74   	throws SAXException;
   75       
   76       
   77       /**
   78        * Receive notification of a recoverable error.
   79        *
   80        * <p>This corresponds to the definition of "error" in section 1.2
   81        * of the W3C XML 1.0 Recommendation.  For example, a validating
   82        * parser would use this callback to report the violation of a
   83        * validity constraint.  The default behaviour is to take no
   84        * action.</p>
   85        *
   86        * <p>The SAX parser must continue to provide normal parsing
   87        * events after invoking this method: it should still be possible
   88        * for the application to process the document through to the end.
   89        * If the application cannot do so, then the parser should report
   90        * a fatal error even if the XML recommendation does not require
   91        * it to do so.</p>
   92        *
   93        * <p>Filters may use this method to report other, non-XML errors
   94        * as well.</p>
   95        *
   96        * @param exception The error information encapsulated in a
   97        *                  SAX parse exception.
   98        * @exception org.xml.sax.SAXException Any SAX exception, possibly
   99        *            wrapping another exception.
  100        * @see org.xml.sax.SAXParseException 
  101        */
  102       public abstract void error (SAXParseException exception)
  103   	throws SAXException;
  104       
  105       
  106       /**
  107        * Receive notification of a non-recoverable error.
  108        *
  109        * <p><strong>There is an apparent contradiction between the
  110        * documentation for this method and the documentation for {@link
  111        * org.xml.sax.ContentHandler#endDocument}.  Until this ambiguity
  112        * is resolved in a future major release, clients should make no
  113        * assumptions about whether endDocument() will or will not be
  114        * invoked when the parser has reported a fatalError() or thrown
  115        * an exception.</strong></p>
  116        *
  117        * <p>This corresponds to the definition of "fatal error" in
  118        * section 1.2 of the W3C XML 1.0 Recommendation.  For example, a
  119        * parser would use this callback to report the violation of a
  120        * well-formedness constraint.</p>
  121        *
  122        * <p>The application must assume that the document is unusable
  123        * after the parser has invoked this method, and should continue
  124        * (if at all) only for the sake of collecting additional error
  125        * messages: in fact, SAX parsers are free to stop reporting any
  126        * other events once this method has been invoked.</p>
  127        *
  128        * @param exception The error information encapsulated in a
  129        *                  SAX parse exception.  
  130        * @exception org.xml.sax.SAXException Any SAX exception, possibly
  131        *            wrapping another exception.
  132        * @see org.xml.sax.SAXParseException
  133        */
  134       public abstract void fatalError (SAXParseException exception)
  135   	throws SAXException;
  136       
  137   }
  138   
  139   // end of ErrorHandler.java

Home » xml-commons-external-1.4.01-src » org.xml » sax » [javadoc | source]