Summary
-------

Add API notes about `Method.invoke` and `Constructor.newInstance` wrapping all `Error` in `InvocationTargetException`, recommending users to unwrap and handle those errors or the consequences.

Problem
-------

`Method.invoke` and `Constructor.newInstance` wraps `Error` instances in `InvocationTargetException`, which could be dangerous if `OutOfMemoryError` or `StackOverflowError` are wrapped; even further wrapping the InvocationTargetException into other throwables can lead to more errors from the VM, hiding the original error.

Meanwhile, the specifcations already require `Error` instances to be wrapped in `InvocationTargetException`, but the wording is not clear; it's easy for users to mishandle these APIs' `InvocationTargetException`.

Solution
--------

1. Specify that `InvocationTargetException` wraps any throwable, explicitly.
2. Add a note section about this wrapping of `Error` and the risk associated to mishandling/ignoring `Error`.

Specification
-------------

    diff --git a/src/java.base/share/classes/java/lang/reflect/Constructor.java b/src/java.base/share/classes/java/lang/reflect/Constructor.java
    index 99f14d01536..e3656df0a4c 100644
    --- a/src/java.base/share/classes/java/lang/reflect/Constructor.java
    +++ b/src/java.base/share/classes/java/lang/reflect/Constructor.java
    @@ -450,6 +450,15 @@ void specificToGenericStringHeader(StringBuilder sb) {
          * <p>If the constructor completes normally, returns the newly
          * created and initialized instance.
          *
    +     * @apiNote
    +     * {@link Throwable}s thrown by the constructor, including {@link
    +     * Error}s, are wrapped in {@link InvocationTargetException}s.
    +     * The wrapped throwable should be handled; ignoring the wrapped
    +     * throwable, such as passing the {@link InvocationTargetException}
    +     * as the cause to construct a new throwable, may fail in cases
    +     * like {@link OutOfMemoryError} or {@link StackOverflowError}.
    +     * The JVM may throw new errors that hide the original ones.
    +     *
          * @param initargs array of objects to be passed as arguments to
          * the constructor call; values of primitive types are wrapped in
          * a wrapper object of the appropriate type (e.g. a {@code float}
    @@ -471,7 +480,7 @@ void specificToGenericStringHeader(StringBuilder sb) {
          * @throws    InstantiationException    if the class that declares the
          *              underlying constructor represents an abstract class.
          * @throws    InvocationTargetException if the underlying constructor
    -     *              throws an exception.
    +     *              throws any {@link Throwable}.
          * @throws    ExceptionInInitializerError if the initialization provoked
          *              by this method fails.
          */
    diff --git a/src/java.base/share/classes/java/lang/reflect/Method.java b/src/java.base/share/classes/java/lang/reflect/Method.java
    index b6ccbaa8294..33711f9953d 100644
    --- a/src/java.base/share/classes/java/lang/reflect/Method.java
    +++ b/src/java.base/share/classes/java/lang/reflect/Method.java
    @@ -526,6 +526,16 @@ void specificToGenericStringHeader(StringBuilder sb) {
          * underlying method return type is void, the invocation returns
          * null.
          *
    +     * @apiNote
    +     * {@link Throwable}s thrown by the underlying method, including
    +     * {@link Error}s like {@link AbstractMethodError}, are wrapped
    +     * in {@link InvocationTargetException}s.
    +     * The wrapped throwable should be handled; ignoring the wrapped
    +     * throwable, such as passing the {@link InvocationTargetException}
    +     * as the cause to construct a new throwable, may fail in cases
    +     * like {@link OutOfMemoryError} or {@link StackOverflowError}.
    +     * The JVM may throw new errors that hide the original ones.
    +     *
          * @param obj  the object the underlying method is invoked from
          * @param args the arguments used for the method call
          * @return the result of dispatching the method represented by
    @@ -546,7 +556,7 @@ void specificToGenericStringHeader(StringBuilder sb) {
          *              cannot be converted to the corresponding formal
          *              parameter type by a method invocation conversion.
          * @throws    InvocationTargetException if the underlying method
    -     *              throws an exception.
    +     *              throws any {@link Throwable}.
          * @throws    NullPointerException      if the specified object is null
          *              and the method is an instance method.
          * @throws    ExceptionInInitializerError if the initialization