1 /* |
1 /* |
2 * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved. |
2 * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 * |
4 * |
5 * This code is free software; you can redistribute it and/or modify it |
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 |
6 * under the terms of the GNU General Public License version 2 only, as |
7 * published by the Free Software Foundation. Oracle designates this |
7 * published by the Free Software Foundation. Oracle designates this |
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
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 |
22 * or visit www.oracle.com if you need additional information or have any |
23 * questions. |
23 * questions. |
24 */ |
24 */ |
25 |
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; |
26 package org.xml.sax; |
32 |
27 |
33 |
28 |
34 /** |
29 /** |
35 * Basic interface for SAX error handlers. |
30 * 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 * |
31 * |
44 * <p>If a SAX application needs to implement customized error |
32 * <p>If a SAX application needs to implement customized error |
45 * handling, it must implement this interface and then register an |
33 * handling, it must implement this interface and then register an |
46 * instance with the XML reader using the |
34 * instance with the XML reader using the |
47 * {@link org.xml.sax.XMLReader#setErrorHandler setErrorHandler} |
35 * {@link org.xml.sax.XMLReader#setErrorHandler setErrorHandler} |
126 public abstract void error (SAXParseException exception) |
114 public abstract void error (SAXParseException exception) |
127 throws SAXException; |
115 throws SAXException; |
128 |
116 |
129 |
117 |
130 /** |
118 /** |
131 * Receive notification of a non-recoverable error. |
119 * Receive notification of a non-recoverable, fatal error. |
132 * |
120 * |
133 * <p><strong>There is an apparent contradiction between the |
121 * <p> |
134 * documentation for this method and the documentation for {@link |
122 * As defined in section 1.2 of the W3C XML 1.0 Recommendation, fatal errors |
135 * org.xml.sax.ContentHandler#endDocument}. Until this ambiguity |
123 * are those that would make it impossible for a parser to continue normal |
136 * is resolved in a future major release, clients should make no |
124 * processing. These include violation of a well-formedness constraint, |
137 * assumptions about whether endDocument() will or will not be |
125 * invalid encoding, and forbidden structural errors as described in the |
138 * invoked when the parser has reported a fatalError() or thrown |
126 * W3C XML 1.0 Recommendation. |
139 * an exception.</strong></p> |
|
140 * |
127 * |
141 * <p>This corresponds to the definition of "fatal error" in |
128 * @apiNote An application must assume that the parser can no longer perform |
142 * section 1.2 of the W3C XML 1.0 Recommendation. For example, a |
129 * normal processing after reporting a fatal error and may stop by throwing |
143 * parser would use this callback to report the violation of a |
130 * a {@link SAXException} without calling {@link ContentHandler#endDocument()}. |
144 * well-formedness constraint.</p> |
131 * In addition, the parser cannot be expected to be able to return accurate |
|
132 * information about the logical structure on the rest of the document even |
|
133 * if it may be able to resume parsing. |
145 * |
134 * |
146 * <p>The application must assume that the document is unusable |
135 * @implNote After invoking this method, the parser may stop processing by |
147 * after the parser has invoked this method, and should continue |
136 * throwing a {@link SAXException}, or implement a feature that can direct |
148 * (if at all) only for the sake of collecting additional error |
137 * it to continue after a fatal error. In the later case, it may report |
149 * messages: in fact, SAX parsers are free to stop reporting any |
138 * events on the rest of the document without any guarantee of correctness. |
150 * other events once this method has been invoked.</p> |
|
151 * |
139 * |
152 * @param exception The error information encapsulated in a |
140 * @param exception The error information encapsulated in a |
153 * SAX parse exception. |
141 * {@link SAXParseException}. |
154 * @exception org.xml.sax.SAXException Any SAX exception, possibly |
142 * @throws SAXException if the application chooses to discontinue the parsing |
155 * wrapping another exception. |
|
156 * @see org.xml.sax.SAXParseException |
|
157 */ |
143 */ |
158 public abstract void fatalError (SAXParseException exception) |
144 public abstract void fatalError (SAXParseException exception) |
159 throws SAXException; |
145 throws SAXException; |
160 |
146 |
161 } |
147 } |