Fix Version/s: 14
Compatibility Risk Description:This is a clarification. No change to the specification or implementation.
Interface Kind:Java API
Remove an ambiguous and unfinished specification from org.xml.sax.ContentHandler and ErrorHandler. Clarify their relationship with regard to ContentHandler's endDocument and ErrorHandler's fatalError methods.
ErrorHandler and ContentHandler have an ambiguous specification that warns there is a contradiction between the two. Such an unfinished specification should not have been published in a formal release.
Remove the unfinished section. Clarify the specifications for the ContentHandler and ErrorHandler in accordance with the W3C XML 1.0 Recommendation and the current status of the JDK.
Removed the sections beginning with "There is an apparent contradiction..." in both ContentHandler and ErrorHandler.
In ErrorHandler.fatalError, a definition of fatal errors is added along with clarification of what the parser implementation may do and applications expect in the event of a fatal error.
For ContentHandler.endDocument, a clarification is made to the definition of endDocument, that is, it is the end of a normal processing. Applications therefore shall not expect the method be called in the event of a fatal error.
New javadoc in html format is copied below:
void endDocument() throws SAXException Receive notification of the end of a document. This method is invoked by the parser to signal it has reached the end of the document after successfully completing the parsing process. After the event, the parser will return the control to the application. API Note: In case of a fatal error, the parser may choose to stop the parsing process with a SAXException, in which case, this method will never be called. Refer to ErrorHandler.fatalError(org.xml.sax.SAXParseException). Throws: SAXException - any SAX exception, possibly wrapping another exception See Also: startDocument()
void fatalError(SAXParseException exception) throws SAXException Receive notification of a non-recoverable, fatal error. As defined in section 1.2 of the W3C XML 1.0 Recommendation, fatal errors are those that would make it impossible for a parser to continue normal processing. These include violation of a well-formedness constraint, invalid encoding, and forbidden structural errors as described in the W3C XML 1.0 Recommendation. API Note: An application must assume that the parser can no longer perform normal processing after reporting a fatal error and may stop by throwing a SAXException without calling ContentHandler.endDocument(). In addition, the parser cannot be expected to be able to return accurate information about the logical structure on the rest of the document even if it may be able to resume parsing. Implementation Note: After invoking this method, the parser may stop processing by throwing a SAXException, or implement a feature that can direct it to continue after a fatal error. In the later case, it may report events on the rest of the document without any guarantee of correctness. Parameters: exception - The error information encapsulated in a SAXParseException. Throws: SAXException - if the application chooses to discontinue the parsing