Summary

Remove obsolete notes about exception chaining history and deprecate an exposed mutable field.

Problem

Several exception classes included ad hoc mechanisms to return an exception "cause" before exception chaining was added as a general feature. The note describing this transition are no longer helpful.

Solution

Remove the notes and deprecate a mutable field.

Specification

--- a/src/java.base/share/classes/java/io/WriteAbortedException.java
+++ b/src/java.base/share/classes/java/io/WriteAbortedException.java
@@ -33,13 +33,6 @@ package java.io;
  * field. The stream is reset to it's initial state and all references
  * to objects already deserialized are discarded.
  *
- * <p>As of release 1.4, this exception has been retrofitted to conform to
- * the general purpose exception-chaining mechanism.  The "exception causing
- * the abort" that is provided at construction time and
- * accessed via the public {@link #detail} field is now known as the
- * <i>cause</i>, and may be accessed via the {@link Throwable#getCause()}
- * method, as well as the aforementioned "legacy field."
- *
  * @since   1.1
  */
 public class WriteAbortedException extends ObjectStreamException {
@@ -49,12 +42,13 @@ public class WriteAbortedException extends ObjectStreamException {
     /**
      * Exception that was caught while writing the ObjectStream.
      *
-     * <p>This field predates the general-purpose exception chaining facility.
-     * The {@link Throwable#getCause()} method is now the preferred means of
-     * obtaining this information.
+     * @deprecated This field predates the general-purpose exception
+     * chaining facility.  The {@link Throwable#getCause()} method is
+     * now the preferred means of obtaining this information.
      *
      * @serial
      */
+    @Deprecated(since="17")
     public Exception detail;


--- a/src/java.base/share/classes/java/lang/ClassNotFoundException.java
+++ b/src/java.base/share/classes/java/lang/ClassNotFoundException.java
@@ -42,13 +42,6 @@ import java.io.ObjectStreamField;
  * <p>
  * but no definition for the class with the specified name could be found.
  *
- * <p>As of release 1.4, this exception has been retrofitted to conform to
- * the general purpose exception-chaining mechanism.  The "optional exception
- * that was raised while loading the class" that may be provided at
- * construction time and accessed via the {@link #getException()} method is
- * now known as the <i>cause</i>, and may be accessed via the {@link
- * Throwable#getCause()} method, as well as the aforementioned "legacy method."
- *
  * @see     java.lang.Class#forName(java.lang.String)
  * @see     java.lang.ClassLoader#findSystemClass(java.lang.String)
  * @see     java.lang.ClassLoader#loadClass(java.lang.String, boolean)
@@ -95,7 +88,8 @@ public class ClassNotFoundException extends ReflectiveOperationException {
      * Returns the exception that was raised if an error occurred while
      * attempting to load the class. Otherwise, returns {@code null}.
      *
-     * <p>This method predates the general-purpose exception chaining facility.
+     * @apiNote
+     * This method predates the general-purpose exception chaining facility.
      * The {@link Throwable#getCause()} method is now the preferred means of
      * obtaining this information.
      *
diff --git a/src/java.base/share/classes/java/lang/ExceptionInInitializerError.java b/src/java.base/share/classes/java/lang/ExceptionInInitializerEr
ror.java
index 134eb113b53..ae4c5a02f6e 100644
--- a/src/java.base/share/classes/java/lang/ExceptionInInitializerError.java
+++ b/src/java.base/share/classes/java/lang/ExceptionInInitializerError.java
@@ -36,13 +36,6 @@ import java.io.ObjectStreamField;
  * exception occurred during evaluation of a static initializer or the
  * initializer for a static variable.
  *
- * <p>As of release 1.4, this exception has been retrofitted to conform to
- * the general purpose exception-chaining mechanism.  The "saved throwable
- * object" that may be provided at construction time and accessed via
- * the {@link #getException()} method is now known as the <i>cause</i>,
- * and may be accessed via the {@link Throwable#getCause()} method, as well
- * as the aforementioned "legacy method."
- *
  * @author  Frank Yellin
  * @since   1.1
  */
@@ -92,7 +85,8 @@ public class ExceptionInInitializerError extends LinkageError {
      * Returns the exception that occurred during a static initialization that
      * caused this error to be created.
      *
-     * <p>This method predates the general-purpose exception chaining facility.
+     * @apiNote
+     * This method predates the general-purpose exception chaining facility.
      * The {@link Throwable#getCause()} method is now the preferred means of
      * obtaining this information.
      *
diff --git a/src/java.base/share/classes/java/lang/reflect/InvocationTargetException.java b/src/java.base/share/classes/java/lang/reflect/Invocation
TargetException.java
index b5aa8f61336..12354bd10c6 100644
--- a/src/java.base/share/classes/java/lang/reflect/InvocationTargetException.java
+++ b/src/java.base/share/classes/java/lang/reflect/InvocationTargetException.java
@@ -29,13 +29,6 @@ package java.lang.reflect;
  * InvocationTargetException is a checked exception that wraps
  * an exception thrown by an invoked method or constructor.
  *
- * <p>As of release 1.4, this exception has been retrofitted to conform to
- * the general purpose exception-chaining mechanism.  The "target exception"
- * that is provided at construction time and accessed via the
- * {@link #getTargetException()} method is now known as the <i>cause</i>,
- * and may be accessed via the {@link Throwable#getCause()} method,
- * as well as the aforementioned "legacy method."
- *
  * @see Method
  * @see Constructor
  * @since 1.1
@@ -90,7 +83,8 @@ public class InvocationTargetException extends ReflectiveOperationException {
     /**
      * Get the thrown target exception.
      *
-     * <p>This method predates the general-purpose exception chaining facility.
+     * @apiNote
+     * This method predates the general-purpose exception chaining facility.
      * The {@link Throwable#getCause()} method is now the preferred means of
      * obtaining this information.
      *
@@ -107,6 +101,7 @@ public class InvocationTargetException extends ReflectiveOperationException {
diff --git a/src/java.base/share/classes/java/lang/reflect/UndeclaredThrowableException.java b/src/java.base/share/classes/java/lang/reflect/Undecla
redThrowableException.java
index 91700f1e8ca..ecba31b497d 100644
--- a/src/java.base/share/classes/java/lang/reflect/UndeclaredThrowableException.java
+++ b/src/java.base/share/classes/java/lang/reflect/UndeclaredThrowableException.java
@@ -48,15 +48,6 @@ import jdk.internal.access.SharedSecrets;
  * {@code RuntimeException}, so it is an unchecked exception
  * that wraps a checked exception.
  *
- * <p>As of release 1.4, this exception has been retrofitted to
- * conform to the general purpose exception-chaining mechanism.  The
- * "undeclared checked exception that was thrown by the invocation
- * handler" that may be provided at construction time and accessed via
- * the {@link #getUndeclaredThrowable()} method is now known as the
- * <i>cause</i>, and may be accessed via the {@link
- * Throwable#getCause()} method, as well as the aforementioned "legacy
- * method."
- *
  * @author      Peter Jones
  * @see         InvocationHandler
  * @since       1.3
@@ -94,7 +85,8 @@ public class UndeclaredThrowableException extends RuntimeException {
      * Returns the {@code Throwable} instance wrapped in this
      * {@code UndeclaredThrowableException}, which may be {@code null}.
      *
-     * <p>This method predates the general-purpose exception chaining facility.
+     * @apiNote
+     * This method predates the general-purpose exception chaining facility.
      * The {@link Throwable#getCause()} method is now the preferred means of
      * obtaining this information.
      *
diff --git a/src/java.base/share/classes/java/security/PrivilegedActionException.java b/src/java.base/share/classes/java/security/PrivilegedActionE
index 7deeaf3efcc..682a52f1ab2 100644
--- a/src/java.base/share/classes/java/security/PrivilegedActionException.java
+++ b/src/java.base/share/classes/java/security/PrivilegedActionException.java
@@ -42,13 +42,6 @@ import jdk.internal.access.SharedSecrets;
  * {@code PrivilegedActionException} is a "wrapper"
  * for an exception thrown by a privileged action.
  *
- * <p>As of release 1.4, this exception has been retrofitted to conform to
- * the general purpose exception-chaining mechanism.  The "exception thrown
- * by the privileged computation" that is provided at construction time and
- * accessed via the {@link #getException()} method is now known as the
- * <i>cause</i>, and may be accessed via the {@link Throwable#getCause()}
- * method, as well as the aforementioned "legacy method."
- *
  * @since 1.2
  * @see PrivilegedExceptionAction
  * @see AccessController#doPrivileged(PrivilegedExceptionAction)
@@ -73,7 +66,8 @@ public class PrivilegedActionException extends Exception {
      * Returns the exception thrown by the privileged computation that
      * resulted in this {@code PrivilegedActionException}.
      *
-     * <p>This method predates the general-purpose exception chaining facility.
+     * @apiNote
+     * This method predates the general-purpose exception chaining facility.
      * The {@link Throwable#getCause()} method is now the preferred means of
      * obtaining this information.
      *