JDK-8034923 : JNI: static linking assertions specs are incomplete and are in the wrong section of spec
  • Type: Bug
  • Component: hotspot
  • Sub-Component: runtime
  • Affected Version: 8
  • Priority: P4
  • Status: Closed
  • Resolution: Duplicate
  • Submitted: 2014-02-13
  • Updated: 2015-06-02
  • Resolved: 2015-06-02
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-8079466 - JNI Specification Update and Clean-up (JDK 8)
Relates :  
JDK-8079466 - JNI Specification Update and Clean-up (JDK 8)
Relates :  
JDK-8005716 - Enhance JNI specification to allow support of static JNI libraries in Embedded JREs
Description
JEP 178 covers statically-linked JNI libraries:

    http://openjdk.java.net/jeps/178

In the section of this JEP entitled "JNI Specification Changes" there is a set of eight bullet points that has some specific assertions about how the Java SE APIs must behave in the presence of statically linked JNI libraries. Several of these points are missing from the System.loadLibrary and Runtime.loadLibrary specifications. These points are also not covered in the JNI Specification.

For example, the following points from the JEP don't appear anywhere in the Java SE specifications that I can find:

 * If a statically linked library L exports a function called JNI_OnLoad_L and a function called JNI_OnLoad, the JNI_OnLoad function will be ignored.

 * If a statically linked library L exports a function called JNI_OnUnLoad_L and a function called JNI_OnUnLoad, the JNI_OnUnLoad function will be ignored.

 * If a library L is statically linked then it will be prohibited to link a library of the same name dynamically.

There may also be other points from the JEP missing from the specification.

There may also need to be other assertions added that don't appear in the JEP. For example, I'd propose these, which are related to JDK-8032456:

 * If a library L is dynamically linked and it exports a function called JNI_OnLoad_L, that function will be ignored.

 * If a library L is dynamically linked and it exports a function called JNI_OnUnload_L, that function will be ignored.

I also happened to notice a couple small issues in the relevant JNI Specification section, "Library and Version Management".

 * JNI_Onload_L is missing the return type of jint.
 * JNI_OnUnload_L is missing the return type of void.

Finally, there are a few editorial issues with the j.l.System and j.l.Runtime specs and JNI Specification.

 * The System.loadLibrary and Runtime.loadLibrary specs mention the JNI Specification, but they don't provide a link. It would be helpful if they also specified, and if possible linked to, the "Library and Version Management" section.

 * The top level JNI documentation page (the page linked from the "JNI" link on the "brick wall" of the main JDK doc page), describes JNI as follows: "The Java Native Interface 6.0 Specification describes how the AWT package is designed to use JNI mechanisms to display objects on Solaris, Linux and Windows platforms." This seems like an anachronism.

 * The Library and Version Management section has a typo "... act as if the library was +never loaded."

 * The Library and Version Management section doesn't make clear when it's talking about native libraries in general, or dynamically-linked libraries specifically. The statically-linked material was added but it makes the rest of the material somewhat unclear in scope.

 * There are a couple paragraph indentation errors in this section.

(If necessary, the portions of this bug pertaining to the JNI Specification may need to be moved to a separate bug under the docs component.)
Comments
Merged into 8079466
02-06-2015
Move details from design to invocation, check, will do. Good catch with the "unload" typos, there are a number of them. BTW the code implementation reads: #define JNI_ONUNLOAD_SYMBOLS {"JNI_OnUnload"} // this is the prefix for "JNI_OnUnload_L" form (see: ClassLoader.c). So the opposite of your previous statement.
25-03-2015
Sorry for the confusing history of this bug. I'd suggest that all of the primary assertions about both dynamic linking and static linking be moved into the "Library and Version Management" section of Chapter 5, "The Invocation API". What's in that section now is very unclear about distinguishing between static and dynamic linking cases. Adding more material here would be redundant with some material in the "Design Overview" chapter, but that's because the material in "Design Overview" is misplaced. That material should be moved (not copied) to "Library and Version Management Chapter" in order to avoid redundancy. Perhaps a forward reference from "Design Overview" to "Library and Version Management" should be added. Aside: additional typos that should be fixed are JNI_OnUnLoad_L instead of JNI_OnUnload_L -- note capitalization. I can provide detailed markups or edits outside the bug report if that would be helpful.
24-03-2015
After going back and forth between the bug description and JNI spec, most of the changes were indeed listed in the design section and the invocation API. But the following changes remain, I will post a RFR containing these: 1) Top level doc http://docs.oracle.com/javase/8/docs/technotes/guides/jni/index.html - remove "describes how the AWT package is designed to use JNI mechanisms to display objects on Solaris, Linux and Windows platforms." 2) Enhancements http://docs.oracle.com/javase/8/docs/technotes/guides/jni/enhancements.html - Add JEP 178 change summary to jni-8.html and link - Reinstate the changes doc links "jni-12.html" and "jni-14.html" 3) http://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/invocation.html - Clarify "JNI_OnLoad_L and JNI_OnUnload_L being ignored in dynamic libraries." - fix typo "act as if the library was +never loaded." Unless someone feels strongly here, or during review, this is the limit of the changes I will be making (my thinking: the design section does a reasonable job of explaining static libraries, the invocation API doesn't need to reiterate).
24-03-2015
Moved to hotspot/runtime since this is probably the right place for JNI spec bugs. Downgraded to P4 as this is a non-critical spec clarification.
19-03-2014
We did add additional content to the Javadocs for the APIs impacted by static JNI libraries and Agents but did not list all of the rules. They refer to the JNI Specification for these detailed assertions. Static Agent changes are document in the JVMTI Doc. http://download.java.net/jdk8/docs/platform/jvmti/jvmti.html The Static Library changes have been added to the JNI Spec. http://download.java.net/jdk8/docs/technotes/guides/jni/spec/jniTOC.html Bob.
14-02-2014
I was confused about JCK not testing any assertions in the JNI Specification. There is certainly coverage for the JNI functions in Chapter 4. There is also coverage for "JNI Enhancements in JDK 1.2" and "JNI Enhancements in the Java 2 SDK", both of which seem to have been dropped out of the current docs bundle. (They do appear in older docs bundles, though.) There also does not appear to be a "JNI Enhancements in Java SE 8" document. [1] [1] http://download.java.net/jdk8/docs/technotes/guides/jni/enhancements.html There is a little bit of coverage of Chapter 2 "Design Overview" where many of the points from the JEP ended up. (I don't know if the JCK has plans to add coverage for these new points in Chapter 2.) There also does not appear to be any coverage for the Chapter 5 Invocation APIs, though there is coverage of JNI_OnLoad and JNI_OnUnload (but some of this is carried over from the earlier "JNI Enhancements" documents) and these have been enhanced with the JNI_OnLoad_L support, though there is no reference to either Chapter 2 or Chapter 5. (See the JCK tests for JNI_OnLoad and JNI_OnUnload.)
14-02-2014
Yes, this is a spec clarification. I don't think it needs to be fixed in 8. I didn't realize that much of the text from the JEP ended up in the Design Overview chapter. Frankly, that's the wrong place. The spec is still missing my suggested statements about JNI_OnLoad_L and JNI_OnUnload_L being ignored in dynamic libraries. Those assertions would have prevented the behavior exhibited in JDK-8032456 (assuming tests had been written for them (and assuming that somebody looked at the test results)). I'm not even sure that having this material in the "JNI Specification" document is the right place anyway, since the JCK does not test assertions made in this document as far as I know. We should consider moving some of this material into the Java SE API specification (i.e., the javadoc).
14-02-2014
Under http://download.java.net/jdk8/docs/technotes/guides/jni/spec/design.html#compiling_loading_and_linking_native_methods, it does mention. ------------- If a statically linked library L exports a function called JNI_OnLoad_L and a function called JNI_OnLoad, the JNI_OnLoad function will be ignored. If a library L is statically linked, then upon the first invocation of System.loadLibrary("L") or equivalent API, a JNI_OnLoad_L function will be invoked with the same arguments and expected return value as specified for the JNI_OnLoad function. A library L that is statically linked will prohibit a library of the same name from being loaded dynamically. When the class loader containing a statically linked native library L is garbage collected, the VM will invoke the JNI_OnUnload_L function of the library if such a function is exported. If a statically linked library L exports a function called JNI_OnUnLoad_L and a function called JNI_OnUnLoad, the JNI_OnUnLoad function will be ignored. --------------- I consider this a spec clarification and probably should be a P4.
14-02-2014