1berry/openjdk
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

8229388: ErrorHandler and ContentHandler contain ambiguous/unfinished specification

Browse Source 
Reviewed-by: lancea
This commit is contained in:
Joe Wang 2019-08-23 17:57:18 +00:00
parent 3ba89c3e98
commit 94e2e909a9
2 changed files with 29 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
src/java.xml/share/classes/org/xml/sax/ContentHandler.java
View File

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -130,19 +130,15 @@ public interface ContentHandler
/** /**
* Receive notification of the end of a document. * Receive notification of the end of a document.
* *
* <p><strong>There is an apparent contradiction between the * <p>
* documentation for this method and the documentation for {@link * This method is invoked by the parser to signal it has reached the end of
* org.xml.sax.ErrorHandler#fatalError}. Until this ambiguity is * the document after successfully completing the parsing process.
* resolved in a future major release, clients should make no * After the event, the parser will return the control to the application.
* assumptions about whether endDocument() will or will not be
* invoked when the parser has reported a fatalError() or thrown
* an exception.</strong></p>
* *
* <p>The SAX parser will invoke this method only once, and it will * @apiNote In case of a fatal error, the parser may choose to stop the
* be the last method invoked during the parse. The parser shall * parsing process with a {@link SAXException}, in which case, this method
* not invoke this method until it has either abandoned parsing * will never be called. Refer to
* (because of an unrecoverable error) or reached the end of * {@link ErrorHandler#fatalError(org.xml.sax.SAXParseException)}.
* input.</p>
* *
* @throws org.xml.sax.SAXException any SAX exception, possibly * @throws org.xml.sax.SAXException any SAX exception, possibly
* wrapping another exception * wrapping another exception

42
src/java.xml/share/classes/org/xml/sax/ErrorHandler.java
View File

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -128,32 +128,30 @@ public interface ErrorHandler {
/** /**
* Receive notification of a non-recoverable error. * Receive notification of a non-recoverable, fatal error.
* *
* <p><strong>There is an apparent contradiction between the * <p>
* documentation for this method and the documentation for {@link * As defined in section 1.2 of the W3C XML 1.0 Recommendation, fatal errors
* org.xml.sax.ContentHandler#endDocument}. Until this ambiguity * are those that would make it impossible for a parser to continue normal
* is resolved in a future major release, clients should make no * processing. These include violation of a well-formedness constraint,
* assumptions about whether endDocument() will or will not be * invalid encoding, and forbidden structural errors as described in the
* invoked when the parser has reported a fatalError() or thrown * W3C XML 1.0 Recommendation.
* an exception.</strong></p>
* *
* <p>This corresponds to the definition of "fatal error" in * @apiNote An application must assume that the parser can no longer perform
* section 1.2 of the W3C XML 1.0 Recommendation. For example, a * normal processing after reporting a fatal error and may stop by throwing
* parser would use this callback to report the violation of a * a {@link SAXException} without calling {@link ContentHandler#endDocument()}.
* well-formedness constraint.</p> * 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.
* *
* <p>The application must assume that the document is unusable * @implNote After invoking this method, the parser may stop processing by
* after the parser has invoked this method, and should continue * throwing a {@link SAXException}, or implement a feature that can direct
* (if at all) only for the sake of collecting additional error * it to continue after a fatal error. In the later case, it may report
* messages: in fact, SAX parsers are free to stop reporting any * events on the rest of the document without any guarantee of correctness.
* other events once this method has been invoked.</p>
* *
* @param exception The error information encapsulated in a * @param exception The error information encapsulated in a
* SAX parse exception. * {@link SAXParseException}.
* @exception org.xml.sax.SAXException Any SAX exception, possibly * @throws SAXException if the application chooses to discontinue the parsing
* wrapping another exception.
* @see org.xml.sax.SAXParseException
*/ */
public abstract void fatalError (SAXParseException exception) public abstract void fatalError (SAXParseException exception)
throws SAXException; throws SAXException;