Summary

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.

Problem

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.

Solution

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.

Specification

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.

Specdiff: attached

Link: http://cr.openjdk.java.net/~joehw/jdk14/8229388/specdiff_02/overview-summary.html

New javadoc in html format is copied below:

Package org.xml.sax

Interface ContentHandler

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() 

Package org.xml.sax

Interface ErrorHandler

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