RFR JDK-8079466: JNI Specification Update and Clean-up

[David Simms]

Greetings,

Posting this JNI Specification docs clean up for public review/comment...

JDK Bug: https://bugs.openjdk.java.net/browse/JDK-8079466

Web review: http://cr.openjdk.java.net/~dsimms/8079466/rev0/

Original Document for HTML comparison: 
http://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/jniTOC.html

*** Summary of changes ***

Wholly confined to documentation changes, no code modifications made. 
Since there were a number of conflicts with previous doc change review, 
all have incorporated all current patches for one push:

------------------------------------------------------------------------------------------
JDK-8051947 JNI spec for ExceptionDescribe contradicts hotspot behavior
- Added text explaining pending exception is cleared as a side effect

JDK-4907359 JNI spec should describe functions more strictly
- Made the split between function definitions more obvious (hr)
- Added a general note on OOM to the beginning of chapter 4: "Functions 
whose definition may both return NULL and throw an exception on error, 
may choose only to return NULL to indicate an error, but not throw any 
exception. For example, a JNI implementation may consider an "out of 
memory" condition temporary, and may not wish to throw an 
OutOfMemoryError since this would appear fatal (JDK API java.lang.Error 
documentation: "indicates serious problems that a reasonable application 
should not try to catch")."
- Every function needs "Parameters", "Returns" and "Throws" documented 
(chapters 4 & 5).
-- Have documented parameters as must not be "null" when appropriate 
(although there are cases where the HotSpot reference implementation 
does not crash):

JDK-7172129 Integration of the JNI spec updates for JDK 1.2 was incomplete
- Previously reviewed

JDK-8034923 JNI: static linking assertions specs are incomplete and are 
in the wrong section of spec
- Previously reviewed

JDK-6462398 jni spec should specify which characters are unicode-escaped 
when mangling
- Previously reviewed

JDK-6590839 JNI Spec should point out Java objects created in JNI using 
AllocObject are not finalized
- Previously reviewed

JDK-8039184 JNI Spec missing documentation on calling default methods
- Previously reviewed

JDK-6616502 JNI specification should discuss multiple invocations of 
DetachCurrentThread
-Previously reviewed

JDK-6681965 The documentation for GetStringChars and GetStringUTFChars 
is unclear
-Previously reviewed
------------------------------------------------------------------------------------------

Cheers
/David Simms