Some questions on JNI Specification(s)

Question

Which is the definitive spec? Is it the book "Programmer's Guide and
Specification" (Guide) by Sheng Liang, or the online doc "Specification" v1.5
(Spec)? The trouble is they don't agree on some matters. It's not simply a
question of which is right, but rather what various JVM vendors have
regarded as correct (regarding the Spec or the Guide as normative) at
various points in time. I'm intending my code to be portable across multiple
platorms and vendors, so it depends to which document they've worked. Do I
have to program within the intersection of the two specs?
The big one is that In the online Spec, it says that only ExceptionOccurred(),
ExceptionDescribe(), and ExceptionClear() can be called when an exception
is pending (end of Chapter 2). But the Guide (11.8.2) lists several other
functions, among them ExceptionCheck(). For instance, according to the
Guide if I call DeleteLocalRef() with a valid argument, nothing bad will
happen, but according to the online Spec I could heading into crashes or
other forms of Undefined Behaviour because there might be a pending
exception. (Having been coding according to the Spec, the Guide now
implies I could afford to have been a lot less cautious, so if the Guide is
normative I can happily rip out lots careful error-handling code.)
One apparently exception-unsafe function is PopLocalFrame(), which
makes it unique amongst the resource cleanup functions. Is this
accurate? Is there a reason for this?
To clarify, what are all the functions that might FatalError() due to
inability to allocate LocalRefs? Is it anything that returns a LocalRef
except NewLocalRef (which just returns NULL and posts an exception)?
What about PopLocalFrame() with a non-NULL argument?
With those functions that take JNI Version parameter, will the resulting
JNIEnv only have those function table entries for that version, or the
most recent one? (i.e. is the supplied version a request for a minimum,
or more exact)? If the former, does this mean that the JNI version
hierarchy is guaranteed never to fork, so there is no ambiguity over the
"latest version"? (My library may create a JVM or attach to a thread in
a variety of circumstances, and it may not be possible to know what the
most appropriate version to request is; I'm hoping the JNI just Does The
Right Thing and saves me some trouble). The same holds for the JavaVM
interface.
For RegisterNatives, the Spec says the functions passed in must
"nominally" have sig
ReturnType (*)(JNIEnv*, jobject objectOrClass,...);
Does this actually mean they should use a va_list and the C calling
convention, rather than JNICALL and explicit params (as in "ordinary"
native methods)?
Thanks for your help
John

Answer 1

> With those functions that take JNI Version parameter, will the resulting JNIEnv only have those function table entries for that version, or the most recent one?
It sounds safest to assume it implements only the version you requested, unless you call GetVersion first to determine the true version.
> Does this actually mean they should use a va_list and the C calling convention, rather than JNICALL and explicit params (as in "ordinary" native methods)?
The book makes this clear. You pass pointers to "ordinary" native methods, having the exact same prototype and implementation as if you used implicit linking rather than RegisterNatives.
-slj-