RFR: 8264148: Update spec for exceptions retrofitted for exception chaining

[Joe Darcy]

On Thu, 25 Mar 2021 18:52:54 GMT, Stuart Marks <smarks at openjdk.org> wrote:

>> 8264148: Update spec for exceptions retrofitted for exception chaining
>
> The removal of the obsolescent "As of release 1.4, this exception has been retrofitted..." is good. Changing the calls from the other exception-getting methods to `getCause()` is also good. I'm less sure of the utility of deprecating these older methods. The deprecation will issue warning messages; is there any benefit to the calling code to migrating from the older methods to `getCause()`? If they're exactly equivalent, then I think the benefits are small, compared to the cost of dealing with warnings. Thus for most of these cases I think that not deprecating the older methods is reasonable, and perhaps the explanation should be converted to an `@apiNote`.
> 
> (The considerations for the JDK itself are different, though, which is why I support changing the call sites.)
> 
> One special case is the **public field** in `WriteAbortedException`. This is really bad and something ought to be done about this, including deprecation, and maybe more. This implies that the exception is mutable, right? Hrrmph. Isn't there a general rule that once the cause has been set (either via a constructor or via initCause) the exception is immutable? Maybe the field should be deprecated, and `getCause()` should return the cause from the superclass. That's a behavior change of course, and I don't know how to assess the compatibility impact. But the current situation just seems wrong.

Some discussion of the proposed changes here. While the history with respect to the introduction of the chained exception mechanism may have been relevant in times past, those comments have little utility today. Per guidance from Dr. Deprecator, I've removed deprecation of the redundant methods and only kept deprecation of the mutable field in WriteAbortedException.

The legacy wrapped exception accessing methods in ClassNotFoundException, ExceptionInInitializerError, and UndeclaredThrowableException are equivalent to getCause. The legacy method in PrivilegedActionException returns the same value, but narrowed to Exception rather than Throwable.

Once the rest of the change is agree to, I'll update copyrights and do a CSR for the deprecation and other spec changes.

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

PR: https://git.openjdk.java.net/jdk/pull/3182