Updated ARM Spec

[David Holmes]

Joe Darcy said the following on 08/24/10 05:45:
> To recap, Throwable objects have several pieces of mutable state:
> 
> * the cause; this is a write-at-most-once value that can be set set via 
> a constructor, like Throwable(Throwable cause) or Throwable(String 
> message, Throwable cause), or set after construction via the 
> Throwable.initCause method.  (Setting the cause to null prevents future 
> assignment.)
> 
> * the stack trace; set by fillInStackTrace() or 
> setStackTrace(StackTraceElement[] stackTrace) -- there doesn't seem to 
> be any API prohibition against setting the stack trace multiple times

But note that the VM implements fillInStackTrace and can ignore the 
request, while setStackTrace is pure Java.

> * suppressed exceptions : new functionality added to support 
> try-with-resources statements/ARM blocks.  Modified via calling 
> addSuppressedException
> 
> Focusing just on suppressed exceptions, to support the JVM reusing 
> exception objects, the Throwable API should have some idiom to indicate 
> suppressed exception information should *not* be recorded. Logically 
> this amount to having the list of exceptions be a zero-length list which 
> just discards adds.
> 
> I'm hesitant to overload a null cause with discarding suppressed 
> exceptions too.  Instead, I propose the following:
> 
> * a null value of the suppressedException field indicates 
> addSuppressedException is a no-op.
> 
> * the suppressedException field is initialized to point to a sentinel 
> list in Throwable, something non-null that can be used for == checks.  
> With this protocol, the "raw" Throwable objects created by the JVM get 
> the addSuppressedException is a no-op behavior for free.
> 
> * if the first call to addSuppressedException has this as an argument, 
> the suppressedException field is null-ed; otherwise, a list is appended 
> to as usual.
> 
> Comments?

It seems to me, inline with what has been written, that Throwable should 
adopt the overall approach that for each of the cause, stacktrace and 
suppressedExceptions fields:

- null indicates that these fields can not be modified (and is the 
default we get from the instances pre-allocated in the VM)
- the default initialization, via the constructor, is always a non-NULL 
sentinel value

This requires several changes to the existing method specifications.

David