The JNI specification makes inconsistent (or badly unhelpful) statements
about the use of global references.


(1) "Weak global references may be used in any situations where global
     or local references are used."

This means that the weak reference can be used as an argument to
GetLongField (for example). The documentation (for GetLongField) does
not describe what happens when a weak reference for a garbage collected
object occurs as an argument. Should it crash? Throw an exception?
There is no illegal return value to return.

Proposal: The only allowable use of a weak reference is in NewGlobalRef
or NewLocalRef, which would produce a usable handle, or NULL, which the
caller can detect. The returned handle should be used for subsequent
calls. The documentation for NewGlobalRef and NewLocalRef would
have to be amended to describe this use.


(2) "Programmers can detect whether a weak global reference points to a
     freed object by using IsSameObject to compare the weak reference
     against NULL."

While this is literally true, garbage collection can occur immediately
after the call to IsSameObject, causing the weak reference to become
unusable. Therefore, the programmer cannot use the call to IsSameObject
to tell whether the weak ref can be used.

Proposal: Remove this comment from the spec in favor of the usage
described above.