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 <[email protected]> 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 > > >
