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

[harold seigel]

Hi David,

It looks like a lot of work!  I have just a few small comments:

1. In functions.html, delete the 'a' before 'this'

  944 reference. May be a <code>NULL</code> value, in which case a this function will
  945 return <code>NULL</code>.</p>


2. In function.html, perhaps some commas around 'for example' ?

1035 (e.g. <code>JNI_ERR</code> or <code>JNI_EINVAL</code>). The HotSpot JVM
1036 implementation for example uses the <code>-XX:+MaxJNILocalCapacity</code> flag
1037 (default: 65536).</p>


3. In function.html, should the words "string length" be added to line 
4339, like they are in line 4335?

4334 <p><code>start</code>: the index of the first unicode character in the string to
4335 copy. Must be greater than or equal to zero, and less than string length
4336 ("<code>GetStringLength()</code>").</p>
4337
4338 <p><code>len</code>: the number of unicode characters to copy. Must be greater
4339 than or equal to zero, and "<code>start + len</code>" must be less than
4340 "<code>GetStringLength()</code>".</p>


4. In function.html, what does "this number" refer to in line 4361?

4359 <p>The <code>len</code> argument specifies the number of
4360 <i>unicode characters</i>. The resulting number modified UTF-8 encoding
4361 characters may be greater than this number. <code>GetStringUTFLength()</code>
4362 may be used to determine the maximum size of the required character buffer.</p>

5. In function.htlm, line 4366, change "safetly' to "to safely"

4366 "<code>memset()</code>") before using this function, in order safetly perform
4367 <code>strlen()</code>.</p>


6. In jni-6.html can the following:

   15 <p>JNI has been enhanced in Java SE 6 with a few minor changes. The addition of
   16 the <code>GetObjectRefType</code> function. Deprecated structures
   17 <code>JDK1_1InitArgs</code> and <code>JDK1_1AttachArgs</code> have been removed.
   18 And an increment in the JNI version number.</p>

to

   15 <p>JNI has been enhanced in Java SE 6 with a few minor changes. The
   16 <code>GetObjectRefType</code> function has been added. Deprecated structures
   17 <code>JDK1_1InitArgs</code> and <code>JDK1_1AttachArgs</code> have been removed.
   18 The JNI version number has also been incremented.</p>

Thanks, Harold

On 5/18/2015 5:07 AM, David Simms wrote:
> 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