View Javadoc
1   /*
2    * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  // SAX error handler.
27  // http://www.saxproject.org
28  // No warranty; no copyright -- use this as you will.
29  // $Id: ErrorHandler.java,v 1.2 2004/11/03 22:44:52 jsuttor Exp $
30  
31  package org.xml.sax;
32  
33  
34  /**
35   * Basic interface for SAX error handlers.
36   *
37   * <blockquote>
38   * <em>This module, both source code and documentation, is in the
39   * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
40   * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>;
41   * for further information.
42   * </blockquote>
43   *
44   * <p>If a SAX application needs to implement customized error
45   * handling, it must implement this interface and then register an
46   * instance with the XML reader using the
47   * {@link org.xml.sax.XMLReader#setErrorHandler setErrorHandler}
48   * method.  The parser will then report all errors and warnings
49   * through this interface.</p>
50   *
51   * <p><strong>WARNING:</strong> If an application does <em>not</em>
52   * register an ErrorHandler, XML parsing errors will go unreported,
53   * except that <em>SAXParseException</em>s will be thrown for fatal errors.
54   * In order to detect validity errors, an ErrorHandler that does something
55   * with {@link #error error()} calls must be registered.</p>
56   *
57   * <p>For XML processing errors, a SAX driver must use this interface
58   * in preference to throwing an exception: it is up to the application
59   * to decide whether to throw an exception for different types of
60   * errors and warnings.  Note, however, that there is no requirement that
61   * the parser continue to report additional errors after a call to
62   * {@link #fatalError fatalError}.  In other words, a SAX driver class
63   * may throw an exception after reporting any fatalError.
64   * Also parsers may throw appropriate exceptions for non-XML errors.
65   * For example, {@link XMLReader#parse XMLReader.parse()} would throw
66   * an IOException for errors accessing entities or the document.</p>
67   *
68   * @since SAX 1.0
69   * @author David Megginson
70   * @see org.xml.sax.XMLReader#setErrorHandler
71   * @see org.xml.sax.SAXParseException
72   */
73  public interface ErrorHandler {
74  
75  
76      /**
77       * Receive notification of a warning.
78       *
79       * <p>SAX parsers will use this method to report conditions that
80       * are not errors or fatal errors as defined by the XML
81       * recommendation.  The default behaviour is to take no
82       * action.</p>
83       *
84       * <p>The SAX parser must continue to provide normal parsing events
85       * after invoking this method: it should still be possible for the
86       * application to process the document through to the end.</p>
87       *
88       * <p>Filters may use this method to report other, non-XML warnings
89       * as well.</p>
90       *
91       * @param exception The warning information encapsulated in a
92       *                  SAX parse exception.
93       * @exception org.xml.sax.SAXException Any SAX exception, possibly
94       *            wrapping another exception.
95       * @see org.xml.sax.SAXParseException
96       */
97      public abstract void warning (SAXParseException exception)
98          throws SAXException;
99  
100 
101     /**
102      * Receive notification of a recoverable error.
103      *
104      * <p>This corresponds to the definition of "error" in section 1.2
105      * of the W3C XML 1.0 Recommendation.  For example, a validating
106      * parser would use this callback to report the violation of a
107      * validity constraint.  The default behaviour is to take no
108      * action.</p>
109      *
110      * <p>The SAX parser must continue to provide normal parsing
111      * events after invoking this method: it should still be possible
112      * for the application to process the document through to the end.
113      * If the application cannot do so, then the parser should report
114      * a fatal error even if the XML recommendation does not require
115      * it to do so.</p>
116      *
117      * <p>Filters may use this method to report other, non-XML errors
118      * as well.</p>
119      *
120      * @param exception The error information encapsulated in a
121      *                  SAX parse exception.
122      * @exception org.xml.sax.SAXException Any SAX exception, possibly
123      *            wrapping another exception.
124      * @see org.xml.sax.SAXParseException
125      */
126     public abstract void error (SAXParseException exception)
127         throws SAXException;
128 
129 
130     /**
131      * Receive notification of a non-recoverable error.
132      *
133      * <p><strong>There is an apparent contradiction between the
134      * documentation for this method and the documentation for {@link
135      * org.xml.sax.ContentHandler#endDocument}.  Until this ambiguity
136      * is resolved in a future major release, clients should make no
137      * assumptions about whether endDocument() will or will not be
138      * invoked when the parser has reported a fatalError() or thrown
139      * an exception.</strong></p>
140      *
141      * <p>This corresponds to the definition of "fatal error" in
142      * section 1.2 of the W3C XML 1.0 Recommendation.  For example, a
143      * parser would use this callback to report the violation of a
144      * well-formedness constraint.</p>
145      *
146      * <p>The application must assume that the document is unusable
147      * after the parser has invoked this method, and should continue
148      * (if at all) only for the sake of collecting additional error
149      * messages: in fact, SAX parsers are free to stop reporting any
150      * other events once this method has been invoked.</p>
151      *
152      * @param exception The error information encapsulated in a
153      *                  SAX parse exception.
154      * @exception org.xml.sax.SAXException Any SAX exception, possibly
155      *            wrapping another exception.
156      * @see org.xml.sax.SAXParseException
157      */
158     public abstract void fatalError (SAXParseException exception)
159         throws SAXException;
160 
161 }
162 
163 // end of ErrorHandler.java