RFR: 8336843: Deprecate java.util.zip.ZipError for removal [v2]

[Eirik Bjørsnøs]

On Tue, 27 Aug 2024 15:51:24 GMT, Eirik Bjørsnøs <eirbjo at openjdk.org> wrote:

>> Please review this PR which suggests to deprecate the unused class `java.util.zip.ZipError` for removal.
>> 
>> The class has been unsed by OpenJDK since  the ZIP API was rewritten from native to Java in JDK 9.
>> 
>> I opted to not explain the reason for the deprecation in detail, but instead simply point to `ZipException` as an alternative. Should more explanation be desired, I could prepend that with a note saying that the class is unused since JDK 9.
>> 
>> A CSR for this API update has been drafted, I'll update the Specification section there once we reach a concensus on the deprecation note in this PR.
>> 
>> This deprecation was initially suggested here: https://mail.openjdk.org/pipermail/core-libs-dev/2024-June/125720.html
>
> Eirik Bjørsnøs has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Extend the deprecation note to mention that the error became obsolete in JDK 9 and to mention that code may be updated to catch the super class InternalError

JEP-277, "Enhanced Deprecation" includes the following recommendations:

*It is strongly recommended that the reasons for deprecating an API be described in that API's documentation comments. In addition, it is also recommended that potential replacement APIs be discussed and linked from the documentation.*

The reason we are deprecating this class is mainly that it became obsolete in JDK 9. I think we should say just that, and not elaborate with more details of the history of the class.

The recommended API replacement depends a bit on whether the code catches or throws `ZipError`, but also depends on whether the code needs to support running on Java 8 and catching `ZipError` there. Here I think we should mention the use case of catching ZipError when running on Java 8 and briefly point in the direction of the super class `InternalError`.

I think I would prefer to not update the class comment.

Based on the above, the PR now suggests the following documentation comment:


/**
 * Signals that an unrecoverable error has occurred.
 * @deprecated This error became obsolete in JDK 9. Use
 * {@link ZipException} instead. Code needing to catch this
 * error when running on JDK 8 or earlier releases may catch
 * the parent {@link InternalError} instead.
 */

-------------

PR Comment: https://git.openjdk.org/jdk/pull/20642#issuecomment-2312939453