Changes planned to Throwable, 6991528 & 6998871

[Paul Benedict]

Joe,

The class documentation currently has a nice chronological history of
Throwable's features:

* "Prior to release 1.4, there were many throwables that had their own
non-standard exception chaining mechanisms..."
* "Further, as of release 1.4, many general purpose...."
* "Also introduced in release 1.4 is the getStackTrace() method..."

It's odd, however, that the suppressed exceptions feature is held off
until the printStackTrace() method:
"As of release 7, the platform supports the notion of suppressed exceptions..."

For consistency, I recommend moving some of that documentation to the
class level to continue the big picture.

Paul

On Fri, Nov 12, 2010 at 3:00 AM, Joe Darcy <joe.darcy at oracle.com> wrote:
> Hello.
>
> Mandy and David Holmes have already reviewed this change; however, I'm
> sending it out to the list in case anyone else is interested in having a
> look before the fix is pushed in the next day or two.
>
> For background, as identified on the coin-dev list, for example [1], it is
> problematic that all Throwable objects are mutable post-creation by calling
> addSuppressedExceptions since it is helpful that the VM be able to reuse
> immutable Throwable objects to provide better handling of conditions like
> OutOfMemoryError.  To support this, the API of Throwable is modified to
> support making the corresponding field of Throwable immutable.
>  Additionally, the method names related to suppressed exceptions will be
> shortened [2].
>
> There is an analogous, and pre-existing issue with the stackTrace field.
>  Due to technical complications encountered during this fix, making
> stackTrace immutable will be addressed in the follow-on bug 6998871.
>
> The webrev of the current round of changes is at:
>
>   http://cr.openjdk.java.net/~darcy/6991528.11/
>
> This involves several specification changes: to the serial specification of
> Throwable:
>
> // Sentinel value protocol added.
>     /**
>      * The list of suppressed exceptions, as returned by {@link
>      * #getSuppressed()}.  The list is initialized to a zero-element
>      * unmodifiable sentinel list.  When a serialized Throwable is
>      * read in, if the {@code suppressedExceptions} field points to a
>      * zero-element list, the field is reset to the sentinel value.
>      *
>      * @serial
>      * @since 1.7
>      */
>     private List<Throwable> suppressedExceptions
>
> // New explicit specification of readObject
>     /**
>      * Read a {@code Throwable} from a stream, enforcing
>      * well-formedness constraints on fields.  Null entries and
>      * self-pointers are not allowed in the list of {@code
>      * suppressedExceptions}.  Null entries are not allowed for stack
>      * trace elements.
>      *
>      * Note that there are no constraints on the value the {@code
>      * cause} field can hold; both {@code null} and this are valid
>      * values for the field.
>      */
>     private void readObject(ObjectInputStream s)
>
> In other parts of the specification, rename "addSuppressedException" to
> "addSuppressed", make the method final, and add the following paragraph and
> update @throws clause:
>
>      * If the first exception to be suppressed is {@code null}, that
>      * indicates suppressed exception information will <em>not</em> be
>      * recorded for this exception.  Subsequent calls to this method
>      * will not record any suppressed exceptions.  Otherwise,
>      * attempting to suppress {@code null} after an exception has
>      * already been successfully suppressed results in a {@code
>      * NullPointerException}.
>      *
>
> ...
>      * @throws NullPointerException if {@code exception} is null and
>      *         an exception has already been suppressed by this exception
>
>
> Rename "getSuppressedExceptions" to "getSuppressed," make the method final,
> and add the following clarification:
>
> * If no exceptions were suppressed, an empty array is returned.
>
> Cheers,
>
> -Joe
>
> [1] http://mail.openjdk.java.net/pipermail/coin-dev/2010-August/002826.html
> [2]
> http://mail.openjdk.java.net/pipermail/coin-dev/2010-September/002909.html
>
>
>