JDK-7021645 : Project Coin: Minor improvements to java.lang.Throwable
  • Type: Bug
  • Component: core-libs
  • Sub-Component: java.lang
  • Affected Version: 7
  • Priority: P3
  • Status: Closed
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2011-02-23
  • Updated: 2017-05-16
  • Resolved: 2011-06-08
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 7
7 b143Fixed
Related Reports
Relates :  
JDK-7011920 - Project Coin: Sync with JSR 334 EDR
Description
Several improvments have been suggested to the API chnanges being done in as part of Project Coin/JSR 334:

Run-on sentence in Throwable:

             * In contrast, when one exception suppresses
             * another, two exceptions are thrown in sibling code blocks, such
             * as in a {@code try} block and in its {@code finally} block, and
             * control flow can only continue with one exception so the second
             * is recorded as a suppressed exception of the first.

Add usage note on reusing an exception object as one legitimate reason to make it immutable.

Clarity usage constraints in SafeVarargs.
Comments
SUGGESTED FIX # HG changeset patch # User darcy # Date 1304988643 25200 # Node ID f4d804b21217b01dd6e87099a7c770ae071f84f0 # Parent 9f56fbc8b6beb7845294fab8452984e7e700500f 7021645: Project Coin: Minor improvements to java.lang.Throwable Reviewed-by: mduigou --- a/src/share/classes/java/lang/Throwable.java Tue May 10 07:00:36 2011 +0800 +++ b/src/share/classes/java/lang/Throwable.java Mon May 09 17:50:43 2011 -0700 @@ -336,7 +336,10 @@ public class Throwable implements Serial * Disabling of suppression should only occur in exceptional * circumstances where special requirements exist, such as a * virtual machine reusing exception objects under low-memory - * situations. + * situations. Circumstances where a given exception object is + * repeatedly caught and rethrown, such as to implement control + * flow between two sub-systems, is another situation where + * immutable throwable objects would be appropriate. * * @param message the detail message. * @param cause the cause. (A {@code null} value is permitted, @@ -422,6 +425,18 @@ public class Throwable implements Serial * with {@link #Throwable(Throwable)} or * {@link #Throwable(String,Throwable)}, this method cannot be called * even once. + * + * <p>An example of using this method on a legacy throwable type + * without other support for setting the cause is: + * + * <pre> + * try { + * lowLevelOp(); + * } catch (LowLevelException le) { + * throw (HighLevelException) + * new HighLevelException().initCause(le); // Legacy constructor + * } + * </pre> * * @param cause the cause (which is saved for later retrieval by the * {@link #getCause()} method). (A {@code null} value is @@ -788,7 +803,8 @@ public class Throwable implements Serial * this throwable is permitted to return a zero-length array from this * method. Generally speaking, the array returned by this method will * contain one element for every frame that would be printed by - * {@code printStackTrace}. + * {@code printStackTrace}. Writes to the returned array do not + * affect future calls to this method. * * @return an array of stack trace elements representing the stack trace * pertaining to this throwable. @@ -971,8 +987,8 @@ public class Throwable implements Serial /** * Appends the specified exception to the exceptions that were * suppressed in order to deliver this exception. This method is - * typically called (automatically and implicitly) by the {@code - * try}-with-resources statement. + * thread-safe and typically called (automatically and implicitly) + * by the {@code try}-with-resources statement. * * <p>The suppression behavior is enabled <em>unless</em> disabled * {@linkplain #Throwable(String, Throwable, boolean, boolean) via @@ -1043,7 +1059,9 @@ public class Throwable implements Serial * * If no exceptions were suppressed or {@linkplain * #Throwable(String, Throwable, boolean, boolean) suppression is - * disabled}, an empty array is returned. + * disabled}, an empty array is returned. This method is + * thread-safe. Writes to the returned array do not affect future + * calls to this method. * * @return an array containing all of the exceptions that were * suppressed to deliver this exception.
10-05-2011
PUBLIC COMMENTS See http://hg.openjdk.java.net/jdk7/tl/jdk/rev/f4d804b21217
10-05-2011
EVALUATION A fine idea.
23-02-2011