Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8163861

JNI NewString() and GetStringLength() documentation incorrect

    Details

    • Understanding:
      Cause Known
    • CPU:
      other
    • OS:
      other

      Description

      A DESCRIPTION OF THE PROBLEM :
      Starting with RFC 2781 (published February 2000), Unicode grew to include characters larger than 16 bits. While most of the Java documentation was updated to reflect this, these two overlooked JNI functions remain unchanged. A minimal modification of the current documentation is needed for it to be accurate again.

      Currently, NewString() has an ambiguous description and GetStringLength() has an incorrect description. The documentation refers to the length of these strings as "the count of Unicode characters," which is definitionally equivalent to "the count of Unicode code points." However, the length expected by NewString() and returned by GetStringLength() is the number of 16-bit words used to represent the string.

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      To be correct:
      * Specify that the value returned by GetStringLength() is the number of 16-bit words used to represent the string
      * Specify that the "len" parameter of NewString is the number of 16-bit words used to represent the string

      Ideally:
      * Specify that NewString() requires a UTF-16 string as input
      * Specify that the length returned by GetStringLength() corresponds to a UTF-16 string
      ACTUAL -
      NewString(), which takes a length parameter, describes the parameter as:
      "len: length of the Unicode string."

      GetStringLength(), which returns string length, is described as:
      "Returns the length (the count of Unicode characters) of a Java string."

      URL OF FAULTY DOCUMENTATION :
      http://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/functions.html#NewString

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                Unassigned
                Reporter:
                webbuggrp Webbug Group
              • Votes:
                0 Vote for this issue
                Watchers:
                7 Start watching this issue

                Dates

                • Created:
                  Updated: