Updated ARM Spec

[Joe Darcy]

David Holmes wrote:
> 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.
>

The needed library changes to Throwable are being worked on under bug 
6991528 "Support immutable Throwable objects" and the changes will be 
sent out for review to core-libs-dev once they're ready.

-Joe