JNI Enhancements in the Java 2 SDK

# JNI Enhancements
Introduced in Version 1.4
of the JavaTM 2 SDK

JNI Documentation

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.

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved. Please send comments to: jni@java.sun.com |