JNI has been enhanced in v 1.4 with support for the
java.nio package as well as a new entry point in the
JNI Invocation Interface. Also, the JNI version number has been
incremented and the description of JNI_OnLoad updated
accordingly.
The new Invocation Interface routine allows native code to attach a daemon thread to the Java virtual machine (JVM); this is useful when the JVM should not wait for this thread to exit upon shutdown.
The NIO-related entry points allow native code to access
java.nio direct buffers. The contents of a
direct buffer can, potentially, reside in native memory outside of
the ordinary garbage-collected heap. For information about direct
buffers, please see New I/O APIs and
the specification of the java.nio.ByteBuffer
class.
Every implementation of the Java virtual machine must support these functions, but not every implementation is required to support JNI access to direct buffers. If a JVM does not support such access then the NewDirectByteBuffer and GetDirectBufferAddress functions must always return NULL, and the GetDirectBufferCapacity function must always return -1. If a JVM does support such access then these three functions must be implemented to return the appropriate values.
The JNI version number has been incremented. The include file
jni.h defines the new constant:
#define JNI_VERSION_1_4 0x00010004
The GetVersion procedure now returns this value,
and the specification of the JNI_OnLoad procedure has
been revised:
jint JNI_OnLoad(JavaVM *vm, void *reserved);
The VM calls JNI_OnLoad when the native library is loaded (for example,
through System.loadLibrary). JNI_OnLoad must return the JNI version
needed by the native library.
In order to use the JNI functions introduced in Java SE release 1.2 in
addition to those that were available in JDK 1.1, a native library must
export a JNI_OnLoad function that returns JNI_VERSION_1_2.
In order to use the JNI functions introduced in Java SE release 1.4 in
addition to those that were available in release 1.2, a native library
must export a JNI_OnLoad function that returns JNI_VERSION_1_4.
If the native library does not export a JNI_OnLoad function, the VM
assumes that the library only requires JNI version JNI_VERSION_1_1. If
the VM does not recognize the version number returned by JNI_OnLoad, the
native library cannot be loaded.
jint AttachCurrentThreadAsDaemon(JavaVM* vm, void** penv, void* args);
Same semantics as AttachCurrentThread, but the newly-created java.lang.Thread instance is a daemon.
If the thread has already been attached via either AttachCurrentThread or AttachCurrentThreadAsDaemon, this routine simply sets the value pointed to by penv to the JNIEnv of the current thread. In this case neither AttachCurrentThread nor this routine have any effect on the daemon status of the thread.
Index 7 in the JavaVM interface function table.
vm: the virtual machine instance to which the current thread will be attached.
penv: a pointer to the location in which the JNIEnv interface pointer for the current thread will be placed.
args: a pointer to a JavaVMAttachArgs structure.
Returns zero on success; otherwise, returns a negative number.
None.
jobject NewDirectByteBuffer(JNIEnv* env, void* address, jlong capacity);
Allocates and returns a direct java.nio.ByteBuffer referring to the block of memory starting at the memory address address and extending capacity bytes.
Native code that calls this function and returns the resulting byte-buffer object to Java-level code should ensure that the buffer refers to a valid region of memory that is accessible for reading and, if appropriate, writing. An attempt to access an invalid memory location from Java code will either return an arbitrary value, have no visible effect, or cause an unspecified exception to be thrown.
Index 229 in the JNIEnv interface function
table.
env: the JNIEnv interface pointer
address: the starting address of the memory region (must not be NULL)
capacity: the size in bytes of the memory region (must be positive)
Returns a local reference to the newly-instantiated java.nio.ByteBuffer object. Returns NULL if an exception occurs, or if JNI access to direct buffers is not supported by this virtual machine.
OutOfMemoryError: if allocation of the ByteBuffer object fails
void* GetDirectBufferAddress(JNIEnv* env, jobject buf);
Fetches and returns the starting address of the memory region referenced by the given direct java.nio.Buffer.
This function allows native code to access the same memory region that is accessible to Java code via the buffer object.
Index 230 in the JNIEnv interface function
table.
env: the JNIEnv interface pointer
buf: a direct java.nio.Buffer object (must not be NULL)
Returns the starting address of the memory region referenced by the buffer. Returns NULL if the memory region is undefined, if the given object is not a direct java.nio.Buffer, or if JNI access to direct buffers is not supported by this virtual machine.
jlong GetDirectBufferCapacity(JNIEnv* env, jobject buf);
Fetches and returns the capacity in bytes of the memory region referenced by the given direct java.nio.Buffer.
Index 231 in the JNIEnv interface function
table.
env: the JNIEnv interface pointer
buf: a direct java.nio.Buffer object (must not be NULL)
Returns the capacity in bytes of the memory region associated with the buffer. Returns -1 if the given object is not a direct java.nio.Buffer, or if JNI access to direct buffers is not supported by this virtual machine.
