Summary
-------

The JNI specification needs to be updated to account for the change to PhantomReferences by JDK-8071507.

Problem
-------

The JNI specification for Weak Global References says that the interaction between them and PhantomReferences is undefined.  In particular, in a clarification from 2001, it says

    ... implementations of a Java VM may (or may not) process weak global
    references after PhantomReferences, and it may (or may not) be
    possible to use weak global references to hold on to objects which
    are also referred to by PhantomReference objects. This undefined use
    of weak global references should be avoided.

This ambiguity was in part a consequence of the specification of phantom references at that time; the garbage collector did not clear phantom references whose referents were determined to be phantom reachable, but instead kept them alive. As a result, the relative reference strengths of JNI weak global references and phantom references was visible to applications. At the time it was suggested that JNI weak references should be stronger than phantom references, but the HotSpot VM (and others?) were already using the other order, and there were concerns about incompatibilities that might result from changing that. (It was also suggested that JNI weak references ought to have the same strength as WeakReference, but that had demonstrable incompatibilities.)

However, the specification for PhantomReference was changed by JDK-8071507; phantom references are now cleared by the garbage collector when it determines the referent is phantom reachable.  Because of this change, there is no longer an application visible difference between the strengths of JNI weak references and phantom references.  Both are already specified to be weaker than finalize.  Other than that, their respective referents are found to be unreachable at the same time.

Solution
--------

We propose to update the JNI specification of weak global references to reflect that change, removing the ambiguity and explicitly specifying weak global references in terms of phantom reachability.

That's the behavior we really want to specify, because it's an important safety invariant, as discussed in the email thread referenced by JDK-8188066. The current JNI spec misleads the reader into worrying about a situation that should no longer be possible because of JDK-8071507. We want the specification to ensure that implementations _must_ provide the desired safety invariant, rather than doing something unusual and surprising. The current specification permits such violations (and HotSpot before JDK-8071507 was indeed in violation of the _desired_ behavior).

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

http://cr.openjdk.java.net/~kbarrett/8188066/jni_specdiff_rev2/diff.html <br>
specdiff for the changes.  In addition to updating the section describing Weak Global References, the description of NewGlobalRef is updated, as well as the copyright footer.  Or see the attached jni_specdiff_rev2.tgz.

http://cr.openjdk.java.net/~kbarrett/8188066/weak_global_refs_rev2.html <br>
Copies of the before and after text for the JNI Weak Global References section; easier to read than diffs or specdiff.