JDK-8038588 : JNI Spec for EnsureLocalCapacity has no throws clause but docs say OOME may be thrown
  • Type: Bug
  • Component: hotspot
  • Sub-Component: runtime
  • Priority: P3
  • Status: Resolved
  • Resolution: Duplicate
  • Submitted: 2014-03-27
  • Updated: 2014-04-03
  • Resolved: 2014-04-03
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 9
9Resolved
Related Reports
Duplicate :  
JDK-4907359 - JNI spec should describe functions more strictly
Relates :  
JDK-4907359 - JNI spec should describe functions more strictly
Description
http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#ensure_local_capacity

says
Ensures that at least a given number of local references can be created in the current thread. Returns 0 on success; otherwise returns a negative number and throws an OutOfMemoryError.

However unlike most functions that throw an exception it is missing a "THROWS:" clause in the docs.
Consequently I almost missed it *and* am unsure if it should in fact have one.
Comments
There are a number of functions in the JNI spec that contain similar text, regarding throwing an exception, but there is no THROWS clause. For reference, in this case hotspot's implementation is trivial and will never throw an exception: jint ret; if (capacity >= 0 && capacity <= MAX_REASONABLE_LOCAL_CAPACITY) { ret = JNI_OK; } else { ret = JNI_ERR; } but I don't see how this implementation actually ensures anything. Looking at the JNI book, it states that on error "an exception" is thrown (no mention what exception type) but then for Exceptions it lists OOME if the system runs out of memory.
28-03-2014