ARM API Support

[Paul Benedict]

I would like to submit the following addition. I feel the current
JavaDoc can benefit from a clearer explanation that differentiates the
two. I also would like to credit Patrick Wright for a great offline
explanation which helped me craft this.

To add at the bottom of the Javadoc:
* <p>Take care to differentiate between the root cause exception and suppressed
* exceptions. The root cause is the fundamental reason of the main exception.
* Suppressed exceptions have no direct relation, but are captured and ignored
* during during post-processing (such as in a {@code finally} block}
of the main
* exception.</p>
*
* <p>As demonstrated in the above example, the "main" Exception was thrown by
* the application, but there were additional problems cleaning up some
* automatic resources. These additional exceptions were captured and
* suppressed because, although they occurred, they did not contribute to,
* cause, or prevent the main exception.</p>

On Thu, Jun 24, 2010 at 10:48 AM, Paul Benedict <pbenedict at apache.org> wrote:
> I understand the technical difference, but do you see my point that
> "suppressed" vs. "cause" is a very thin difference? I can use English
> to actually express both ARM and root causes and be correct -- if not
> imprecise technically. Conversely, if I catch X and throw Y without
> setting X as a root cause, I actually suppressed X.
>
> I don't have a better word choice for you at this time, but it's
> something for everyone to think about.
>
> On Thu, Jun 24, 2010 at 10:39 AM, Neal Gafter <neal at gafter.com> wrote:
>> Suppression occurs due to the constructs of the language (the ARM try), in
>> which an exception propogating out of the implied finally block simply
>> discards (suppresses) any exceptions from the try block without any
>> programmer expression of this intent.  Moreover, more than one exceptions
>> can be suppressed.  This is completely different from exception causes,
>> which are explicit user expression of intent that one exception was the
>> cause of the other.
>>