Summary

Update the ExceptionCheck description to use the same wording as ExceptionOccurred and have them both reference each other. Use consistent terminology throughout.

Problem

It is very easy to mis-use the ExceptionOccurred method as a boolean check (it actually returns a local reference to the exception object) when the ExceptionCheck method was added for that purpose.

Solution

Update the ExceptionCheck description to use the same wording as Exception Occurred and have them both reference each other. Add mention of ExceptionCheck in the "Java Exceptions" section of the Design chapter. Use consistent terminology throughout all the exception related text.

Specification

Proposed change:

diff --git a/closed/src/java.se/share/specs/jni/design.md b/closed/src/java.se/share/specs/jni/design.md
index 5e1db522ba..7270de47f5 100644
--- a/closed/src/java.se/share/specs/jni/design.md
+++ b/closed/src/java.se/share/specs/jni/design.md
@@ -537,14 +537,14 @@ return values. Therefore, the programmer can:

 -   quickly check the return value of the last JNI call to determine if an
     error has occurred, and
--   call a function, ExceptionOccurred(), to obtain the exception object that
+-   call the function, ExceptionOccurred(), to obtain the exception object that
     contains a more detailed description of the error condition.

 There are two cases where the programmer needs to check for exceptions without
 being able to first check an error code:

 -   The JNI functions that invoke a Java method return the result of the Java
-    method. The programmer must call `ExceptionOccurred()` to check for
+    method. The programmer must call `ExceptionCheck()` or `ExceptionOccurred()` to check for
     possible exceptions that occurred during the execution of the Java method.
 -   Some of the JNI array access functions do not return an error code, but may
     throw an `ArrayIndexOutOfBoundsException` or `ArrayStoreException`.
@@ -569,13 +569,13 @@ code in the current thread, until:

 -   the native code calls one of the JNI functions that could raise synchronous
     exceptions, or
-   the native code uses `ExceptionOccurred()` to explicitly check for
+   the native code uses `ExceptionCheck()` or `ExceptionOccurred()` to explicitly check for
     synchronous and asynchronous exceptions.

 Note that only those JNI functions that could potentially raise synchronous
 exceptions check for asynchronous exceptions.

-Native methods should insert `ExceptionOccurred()` checks in necessary places,
+Native methods should insert `ExceptionCheck()` or `ExceptionOccurred()` checks in necessary places,
 such as in any long running code without other exception checks (this may
 include tight loops). This ensures that the current thread responds to
 asynchronous exceptions in a reasonable amount of time. However, because of
@@ -593,7 +593,7 @@ There are two ways to handle an exception in native code:
     then execute its own exception-handling code.

 After an exception has been raised, the native code must first clear the
-exception before making other JNI calls. When there is a pending exception, the
+exception before making other JNI calls. When there is an exception being thrown, the
 JNI functions that are safe to call are:

--- a/closed/src/java.se/share/specs/jni/functions.md
+++ b/closed/src/java.se/share/specs/jni/functions.md
@@ -863,6 +863,9 @@ Determines if an exception is being thrown. The exception stays being thrown
 until either the native code calls `ExceptionClear()`, or the Java code handles
 the exception.

+If the exception object currently being thrown is not needed then the
+[`ExceptionCheck()`](#exceptioncheck) method is a simpler alternative to use.
+
 #### LINKAGE:

 Index 15 in the JNIEnv interface function table.
@@ -883,7 +886,7 @@ or `NULL` if no exception is currently being thrown.
 `void ExceptionDescribe(JNIEnv *env);`

 Prints an exception and a backtrace of the stack to a system error-reporting
-channel, such as `stderr`. The pending exception is cleared as a side-effect of
+channel, such as `stderr`. The exception being thrown is cleared as a side-effect of
 calling this function. This is a convenience routine provided for debugging.

 #### LINKAGE:
@@ -935,13 +938,15 @@ Index 18 in the JNIEnv interface function table.

 ### ExceptionCheck

-We introduce a convenience function to check for pending exceptions without
-creating a local reference to the exception object.
-
 `jboolean ExceptionCheck(JNIEnv *env);`

-Returns `JNI_TRUE` when there is a pending exception; otherwise, returns
-`JNI_FALSE`.
+Determines if an exception is being thrown. The exception stays being thrown
+until either the native code calls `ExceptionClear()`, or the Java code handles
+the exception.
+
+This is a convenience function to check if an exception is being thrown, without
+creating a local reference to the exception object
+(see [`ExceptionOccurred()`](#exceptionoccurred)).

 #### LINKAGE:

@@ -951,6 +956,11 @@ Index 228 in the JNIEnv interface function table.

 `env`: the JNI interface pointer, must not be `NULL`.

+#### RETURNS:
+
+Returns `JNI_TRUE` when there is an exception being thrown; otherwise, returns
+`JNI_FALSE`.
+
 -------------------------------------------------------------------------------

 ## Global and Local References
@@ -1097,8 +1107,8 @@ JDK/JRE 1.2
 `jint PushLocalFrame(JNIEnv *env, jint capacity);`

 Creates a new local reference frame, in which at least a given number of local
-references can be created. Returns 0 on success, a negative number and a
-pending `OutOfMemoryError` on failure.
+references can be created. Returns 0 on success, a negative number and throws
+`OutOfMemoryError` on failure.

 Note that local references already created in previous local frames are still
 valid in the current local frame.