Name: jl125535			Date: 12/19/2001


FULL PRODUCT VERSION :
java version "1.3.1_01"
Java(TM) Runtime Environment, Standard Edition (build
1.3.1_01)
Java Hotspot(TM) Client VM (build 1.3.1_01, mixed mode)


Not applicable.



A DESCRIPTION OF THE PROBLEM :
I recently unwittingly stumbled across an undocumented
feature of the JNI method "GetStringChars()" which has
wasted quite a bit of my time. I discovered that sometimes
the strings I was getting returned from GetStringChars() on
the native side were not the length I expected.

After a quick search on bug parade, I found bug #4076576,
which mentions the fact that "Java strings are not
NULL-terminated. Thus the string returned by GetStringChars
does not have 0 at the end."

I am not reporting this as a bug in itself. There are
probably good reasons why the JNI was designed to not return
null-terminated strings. What I *am* reporting as a bug, is
that the fact that the strings are *not* necessarily
null-terminated is not documented anywhere in the JNI
documentation (including the latest JDK 1.4 documentation on
your website). In fact, the only place I have ever seen this
documented is in bug report #4076576. This is highly
unsatisfactory, for a number of reasons:

1. C programmers, in the absence of any documentation to the
contrary, will generally assume that the strings they are
passed are NULL-terminated.
2. In the case where the programmer is unsure and decides to
investigate for themselves, they may find that (by
coincidence) the strings that they get happen to be
NULL-terminated, and incorrectly assume that this will
always be the case (which is what I did). This may introduce
bugs at a later stage.
3. The JNI tutorial ("Accessing Java Strings in Native
Methods") mentions that the strings returned by
GetStringUTFChars() is NULL-terminated. This would lead many
developers to conclude that GetStringChars() would also be
NULL-terminated (again, this is what I did).

The complaints about lack of documentation were actually
already made in the comments of bug report #4076576. However
nothing seems to have been done about it in the 4 years
since the original report was made and that bug has long
since been closed. Thus I thought the particular complaint
about lack of documentation was worth submitting as a bug in
itself - especially as it is still causing developers (such
as myself) to be caught out.


STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. Read the documentation.
2. See that it is incomplete.

This bug can be reproduced always.

---------- BEGIN SOURCE ----------
See bug #4076576
---------- END SOURCE ----------

CUSTOMER WORKAROUND :
Once the behaviour of GetStringChars() is properly
understood, work-around is easy - if a null-terminated
string is required, then make a copy and null-terminate it
yourself.
(Review ID: 137530) 
======================================================================