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.

• AttachCurrentThreadAsDaemon

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.

Three new functions allow JNI code to create, examine, and manipulate direct buffers:

• NewDirectByteBuffer
• GetDirectBufferAddress
• GetDirectBufferCapacity

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.

Incremented Version Number

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 J2SE 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 J2SE 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.

Additions to the JNI Invocation Interface

AttachCurrentThreadAsDaemon

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.

LINKAGE

Index 7 in the JavaVM interface function table.

PARAMETERS

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

Returns zero on success; otherwise, returns a negative number.

EXCEPTIONS

None.

Additions to the JNI Interface

NewDirectByteBuffer

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.

LINKAGE

Index 229 in the JNIEnv interface function table.

PARAMETERS

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

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.

EXCEPTIONS

OutOfMemoryError: if allocation of the ByteBuffer object fails

---

GetDirectBufferAddress

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.

LINKAGE

Index 230 in the JNIEnv interface function table.

PARAMETERS

env: the JNIEnv interface pointer

buf: a direct java.nio.Buffer object (must not be NULL)

RETURNS

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.

---

GetDirectBufferCapacity

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.

LINKAGE

Index 231 in the JNIEnv interface function table.

PARAMETERS

env: the JNIEnv interface pointer

buf: a direct java.nio.Buffer object (must not be NULL)

RETURNS

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.