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.
*