Changes planned to Throwable, 6991528 & 6998871

[Joe Darcy]

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