Summary
-------

Update the JNI Specification to align JNI weak global reference with Java phantom references, driven by the change to automatically clear phantom references (CCC-8071507).


Problem
-------

The JNI Specification in Java SE 8 contains a "clarification" from 2001 concerning the ambiguous relationship of JNI weak global references and Java phantom references (`java.lang.ref.PhantomReference`). It states:

```
Interactions between weak global references and PhantomReferences
are undefined. In particular, 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.
```

(https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/functions.html#weak_global_references)

The ambiguity was in part a consequence of the specification of phantom references circa 2001: 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 of the "clarification", it was suggested that JNI weak global references should be stronger than phantom references, but the HotSpot VM was already using the other order (JNI weak global references are weaker than phantom references), and there were concerns about incompatibilities that might result from changing that. (It was also suggested that JNI weak global references should have the same strength as Java weak references (`java.lang.ref.WeakReference`) but that had demonstrable incompatibilities.)

Since 2001, the specification of phantom references has changed: they 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 global references and phantom references. Both are already specified to be weaker than finalize (that is, weaker than Java weak references). Other than that, their respective referents are found to be unreachable at the same time.

As a result, the "clarification" in the JNI Specification is no longer useful. Its ambiguity misleads the reader into worrying about a situation that should no longer be possible with automatic clearing of phantom references.


Solution
--------

We propose to update the JNI Specification in Java SE 8 by (1) removing the "clarification" from 2001, and (2) specifying JNI weak global references in terms of phantom reachability. This is an important safety invariant and it is proper for the JNI Specification to ensure that implementations _must_ provide it, rather than doing something unusual and surprising. 


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

http://cr.openjdk.java.net/~dholmes/8287056-specdiff/mr4-jni/overview-summary.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 specdiff.

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