Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8229738

Remove ambiguous/unfinished specification from ErrorHandler and ContentHandler

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 14
    • Component/s: xml
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      This is a clarification. No change to the specification or implementation.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      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 

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                joehw Joe Wang
                Reporter:
                joehw Joe Wang
                Reviewed By:
                Daniel Fuchs, Lance Andersen
              • Votes:
                0 Vote for this issue
                Watchers:
                1 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: