ErrorHandler
Stay organized with collections
Save and categorize content based on your preferences.
|
Known Indirect Subclasses
|
Basic interface for SAX error handlers.
This module, both source code and documentation, is in the
Public Domain, and comes with NO WARRANTY.
See http://www.saxproject.org
for further information.
If a SAX application needs to implement customized error
handling, it must implement this interface and then register an
instance with the XML reader using the
setErrorHandler
method. The parser will then report all errors and warnings
through this interface.
WARNING: If an application does not
register an ErrorHandler, XML parsing errors will go unreported,
except that SAXParseExceptions will be thrown for fatal errors.
In order to detect validity errors, an ErrorHandler that does something
with error() calls must be registered.
For XML processing errors, a SAX driver must use this interface
in preference to throwing an exception: it is up to the application
to decide whether to throw an exception for different types of
errors and warnings. Note, however, that there is no requirement that
the parser continue to report additional errors after a call to
fatalError. In other words, a SAX driver class
may throw an exception after reporting any fatalError.
Also parsers may throw appropriate exceptions for non-XML errors.
For example, XMLReader.parse() would throw
an IOException for errors accessing entities or the document.
Public Method Summary
|
abstract
void
|
|
|
abstract
void
|
|
|
abstract
void
|
|
Public Methods
public
abstract
void
error
(SAXParseException exception)
Receive notification of a recoverable error.
This corresponds to the definition of "error" in section 1.2
of the W3C XML 1.0 Recommendation. For example, a validating
parser would use this callback to report the violation of a
validity constraint. The default behaviour is to take no
action.
The SAX parser must continue to provide normal parsing
events after invoking this method: it should still be possible
for the application to process the document through to the end.
If the application cannot do so, then the parser should report
a fatal error even if the XML recommendation does not require
it to do so.
Filters may use this method to report other, non-XML errors
as well.
Parameters
| exception |
The error information encapsulated in a
SAX parse exception. |
Throws
| SAXException |
Any SAX exception, possibly
wrapping another exception. |
public
abstract
void
fatalError
(SAXParseException exception)
Receive notification of a non-recoverable error.
There is an apparent contradiction between the
documentation for this method and the documentation for ContentHandler.endDocument(). Until this ambiguity
is resolved in a future major release, clients should make no
assumptions about whether endDocument() will or will not be
invoked when the parser has reported a fatalError() or thrown
an exception.
This corresponds to the definition of "fatal error" in
section 1.2 of the W3C XML 1.0 Recommendation. For example, a
parser would use this callback to report the violation of a
well-formedness constraint.
The application must assume that the document is unusable
after the parser has invoked this method, and should continue
(if at all) only for the sake of collecting additional error
messages: in fact, SAX parsers are free to stop reporting any
other events once this method has been invoked.
Parameters
| exception |
The error information encapsulated in a
SAX parse exception. |
Throws
| SAXException |
Any SAX exception, possibly
wrapping another exception. |
public
abstract
void
warning
(SAXParseException exception)
Receive notification of a warning.
SAX parsers will use this method to report conditions that
are not errors or fatal errors as defined by the XML
recommendation. The default behaviour is to take no
action.
The SAX parser must continue to provide normal parsing events
after invoking this method: it should still be possible for the
application to process the document through to the end.
Filters may use this method to report other, non-XML warnings
as well.
Parameters
| exception |
The warning information encapsulated in a
SAX parse exception. |
Throws
| SAXException |
Any SAX exception, possibly
wrapping another exception. |
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-07-10 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-07-10 UTC."],[[["\u003cp\u003e\u003ccode\u003eErrorHandler\u003c/code\u003e is a basic interface for handling errors during SAX XML parsing.\u003c/p\u003e\n"],["\u003cp\u003eApplications must register an \u003ccode\u003eErrorHandler\u003c/code\u003e with the XML reader to receive error and warning notifications.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eErrorHandler\u003c/code\u003e provides three methods for handling different error severities: \u003ccode\u003eerror\u003c/code\u003e, \u003ccode\u003efatalError\u003c/code\u003e, and \u003ccode\u003ewarning\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eIf an \u003ccode\u003eErrorHandler\u003c/code\u003e isn't registered, parsing errors might go unreported, with only fatal errors throwing \u003ccode\u003eSAXParseException\u003c/code\u003es.\u003c/p\u003e\n"],["\u003cp\u003eSAX drivers prioritize using \u003ccode\u003eErrorHandler\u003c/code\u003e for reporting XML processing errors instead of directly throwing exceptions.\u003c/p\u003e\n"]]],["The `ErrorHandler` interface is used for customized SAX error handling. Applications must implement this interface and register it with an XML reader to receive error reports. The parser uses this interface for errors and warnings, instead of throwing exceptions, giving applications control over how to handle them. Key actions include receiving notifications of recoverable errors via `error()`, non-recoverable errors via `fatalError()`, and warnings via `warning()`, all using `SAXParseException`. Unregistered handlers lead to unreported errors, except for fatal errors.\n"],null,["public interface **ErrorHandler** \n\n|---|---|---|\n| Known Indirect Subclasses [DefaultHandler](../../../../reference/org/xml/sax/helpers/DefaultHandler.html), [DefaultHandler2](../../../../reference/org/xml/sax/ext/DefaultHandler2.html), [HandlerBase](../../../../reference/org/xml/sax/HandlerBase.html), [XMLFilterImpl](../../../../reference/org/xml/sax/helpers/XMLFilterImpl.html) |---------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [DefaultHandler](../../../../reference/org/xml/sax/helpers/DefaultHandler.html) | Default base class for SAX2 event handlers. | | [DefaultHandler2](../../../../reference/org/xml/sax/ext/DefaultHandler2.html) | This class extends the SAX2 base handler class to support the SAX2 [LexicalHandler](../../../../reference/org/xml/sax/ext/LexicalHandler.html), [DeclHandler](../../../../reference/org/xml/sax/ext/DeclHandler.html), and [EntityResolver2](../../../../reference/org/xml/sax/ext/EntityResolver2.html) extensions. | | [HandlerBase](../../../../reference/org/xml/sax/HandlerBase.html) | *This class is deprecated. This class works with the deprecated [DocumentHandler](../../../../reference/org/xml/sax/DocumentHandler.html) interface. It has been replaced by the SAX2 [DefaultHandler](../../../../reference/org/xml/sax/helpers/DefaultHandler.html) class.* | | [XMLFilterImpl](../../../../reference/org/xml/sax/helpers/XMLFilterImpl.html) | Base class for deriving an XML filter. | |||\n\nBasic interface for SAX error handlers.\n\n\u003e *This module, both source code and documentation, is in the\n\u003e Public Domain, and comes with **NO WARRANTY**.* See \u003chttp://www.saxproject.org\u003e for further information.\n\nIf a SAX application needs to implement customized error\nhandling, it must implement this interface and then register an\ninstance with the XML reader using the\n[setErrorHandler](../../../../reference/org/xml/sax/XMLReader.html#setErrorHandler(org.xml.sax.ErrorHandler))\nmethod. The parser will then report all errors and warnings\nthrough this interface.\n\n**WARNING:** If an application does *not*\nregister an ErrorHandler, XML parsing errors will go unreported,\nexcept that *SAXParseException* s will be thrown for fatal errors.\nIn order to detect validity errors, an ErrorHandler that does something\nwith [error()](../../../../reference/org/xml/sax/ErrorHandler.html#error(org.xml.sax.SAXParseException)) calls must be registered.\n\nFor XML processing errors, a SAX driver must use this interface\nin preference to throwing an exception: it is up to the application\nto decide whether to throw an exception for different types of\nerrors and warnings. Note, however, that there is no requirement that\nthe parser continue to report additional errors after a call to\n[fatalError](../../../../reference/org/xml/sax/ErrorHandler.html#fatalError(org.xml.sax.SAXParseException)). In other words, a SAX driver class\nmay throw an exception after reporting any fatalError.\nAlso parsers may throw appropriate exceptions for non-XML errors.\nFor example, [XMLReader.parse()](../../../../reference/org/xml/sax/XMLReader.html#parse(java.lang.String)) would throw\nan IOException for errors accessing entities or the document.\n\n\u003cbr /\u003e\n\nSee Also\n\n- [XMLReader.setErrorHandler(ErrorHandler)](../../../../reference/org/xml/sax/XMLReader.html#setErrorHandler(org.xml.sax.ErrorHandler))\n- [SAXParseException](../../../../reference/org/xml/sax/SAXParseException.html) \n\nPublic Method Summary\n\n|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| abstract void | [error](../../../../reference/org/xml/sax/ErrorHandler.html#error(org.xml.sax.SAXParseException))([SAXParseException](../../../../reference/org/xml/sax/SAXParseException.html) exception) Receive notification of a recoverable error. |\n| abstract void | [fatalError](../../../../reference/org/xml/sax/ErrorHandler.html#fatalError(org.xml.sax.SAXParseException))([SAXParseException](../../../../reference/org/xml/sax/SAXParseException.html) exception) Receive notification of a non-recoverable error. |\n| abstract void | [warning](../../../../reference/org/xml/sax/ErrorHandler.html#warning(org.xml.sax.SAXParseException))([SAXParseException](../../../../reference/org/xml/sax/SAXParseException.html) exception) Receive notification of a warning. |\n\nPublic Methods \n\npublic abstract void\n**error**\n([SAXParseException](../../../../reference/org/xml/sax/SAXParseException.html) exception) \nReceive notification of a recoverable error.\n\nThis corresponds to the definition of \"error\" in section 1.2\nof the W3C XML 1.0 Recommendation. For example, a validating\nparser would use this callback to report the violation of a\nvalidity constraint. The default behaviour is to take no\naction.\n\nThe SAX parser must continue to provide normal parsing\nevents after invoking this method: it should still be possible\nfor the application to process the document through to the end.\nIf the application cannot do so, then the parser should report\na fatal error even if the XML recommendation does not require\nit to do so.\n\nFilters may use this method to report other, non-XML errors\nas well.\n\n\u003cbr /\u003e\n\nParameters\n\n| exception | The error information encapsulated in a SAX parse exception. |\n|-----------|--------------------------------------------------------------|\n\nThrows\n\n| [SAXException](../../../../reference/org/xml/sax/SAXException.html) | Any SAX exception, possibly wrapping another exception. |\n|---------------------------------------------------------------------|---------------------------------------------------------|\n\nSee Also\n\n- [SAXParseException](../../../../reference/org/xml/sax/SAXParseException.html) \n\npublic abstract void\n**fatalError**\n([SAXParseException](../../../../reference/org/xml/sax/SAXParseException.html) exception) \nReceive notification of a non-recoverable error.\n\n**There is an apparent contradiction between the\ndocumentation for this method and the documentation for [ContentHandler.endDocument()](../../../../reference/org/xml/sax/ContentHandler.html#endDocument()). Until this ambiguity\nis resolved in a future major release, clients should make no\nassumptions about whether endDocument() will or will not be\ninvoked when the parser has reported a fatalError() or thrown\nan exception.**\n\nThis corresponds to the definition of \"fatal error\" in\nsection 1.2 of the W3C XML 1.0 Recommendation. For example, a\nparser would use this callback to report the violation of a\nwell-formedness constraint.\n\nThe application must assume that the document is unusable\nafter the parser has invoked this method, and should continue\n(if at all) only for the sake of collecting additional error\nmessages: in fact, SAX parsers are free to stop reporting any\nother events once this method has been invoked.\n\n\u003cbr /\u003e\n\nParameters\n\n| exception | The error information encapsulated in a SAX parse exception. |\n|-----------|--------------------------------------------------------------|\n\nThrows\n\n| [SAXException](../../../../reference/org/xml/sax/SAXException.html) | Any SAX exception, possibly wrapping another exception. |\n|---------------------------------------------------------------------|---------------------------------------------------------|\n\nSee Also\n\n- [SAXParseException](../../../../reference/org/xml/sax/SAXParseException.html) \n\npublic abstract void\n**warning**\n([SAXParseException](../../../../reference/org/xml/sax/SAXParseException.html) exception) \nReceive notification of a warning.\n\nSAX parsers will use this method to report conditions that\nare not errors or fatal errors as defined by the XML\nrecommendation. The default behaviour is to take no\naction.\n\nThe SAX parser must continue to provide normal parsing events\nafter invoking this method: it should still be possible for the\napplication to process the document through to the end.\n\nFilters may use this method to report other, non-XML warnings\nas well.\n\n\u003cbr /\u003e\n\nParameters\n\n| exception | The warning information encapsulated in a SAX parse exception. |\n|-----------|----------------------------------------------------------------|\n\nThrows\n\n| [SAXException](../../../../reference/org/xml/sax/SAXException.html) | Any SAX exception, possibly wrapping another exception. |\n|---------------------------------------------------------------------|---------------------------------------------------------|\n\nSee Also\n\n- [SAXParseException](../../../../reference/org/xml/sax/SAXParseException.html)"]]
