src/share/classes/java/lang/Throwable.java

@@ -334,11 +334,14 @@
      * conditions under which suppression is disabled and document
      * conditions under which the stack trace is not writable.
      * 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,
      * and indicates that the cause is nonexistent or unknown.)
      * @param enableSuppression whether or not suppression is enabled or disabled

@@ -421,10 +424,22 @@
      * throwable.  If this throwable was created
      * 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
      *         permitted, and indicates that the cause is nonexistent or
      *         unknown.)
      * @return  a reference to this {@code Throwable} instance.

@@ -786,11 +801,12 @@
      * or more stack frames from the stack trace.  In the extreme case,
      * a virtual machine that has no stack trace information concerning
      * 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.
      * @since  1.4
      */

@@ -969,12 +985,12 @@
     }
 
     /**
      * 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
      * a constructor}.  When suppression is disabled, this method does
      * nothing other than to validate its argument.

@@ -1041,11 +1057,13 @@
      * suppressed, typically by the {@code try}-with-resources
      * statement, in order to deliver this exception.
      *
      * 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.
      * @since 1.7
      */