ErrorHandler


1   // SAX error handler.
2   // http://www.saxproject.org
3   // No warranty; no copyright -- use this as you will.
4   // $Id: ErrorHandler.java,v 1.1.24.1 2004/05/01 08:34:39 jsuttor Exp $
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
140
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags