In JNI, how do I cache the class, methodID, and fieldIDs per IBM's performance recommendations?

Question

I read on on IBM that

To access Java objects' fields and invoke their methods, native code must make calls to FindClass(), GetFieldID(), GetMethodId(), and GetStaticMethodID(). In the case of GetFieldID(), GetMethodID(), and GetStaticMethodID(), the IDs returned for a given class don't change for the lifetime of the JVM process. But the call to get the field or method can require significant work in the JVM, because fields and methods might have been inherited from superclasses, making the JVM walk up the class hierarchy to find them. Because the IDs are the same for a given class, you should look them up once and then reuse them. Similarly, looking up class objects can be expensive, so they should be cached as well.

How does one cache the methodID, fieldID, and class objects in JNI? Are there built-in methods or a specific procedure that has to be followed?

Answer 1

There is no built-in methodology to follow, however here is a somewhat standard, clean, and repeatable implementation showing how I practice IBM's recommendation.

I am going to assume you are calling your DLL from Java and you are referencing it multiple times throughout your application life-cycle.

The sample Native Java Class is named org.stackoverflow.jni.NativeClazz, which will implement the 2 built-in JNI methods JNI_OnLoad() and JNI_OnUnload().

void JNI_OnLoad(JavaVM *vm, void *reserved): This method will be used to register the Class IDs as global variables and assign the Method IDs and Field IDs to static variables. The method is automatically called when the driver is loaded by the Java VM; it is only called once during the driver life-cycle.

void JNI_OnUnload(JavaVM *vm, void *reserved): This method will be used to free any global variables registered by JNI_OnLoad(). The VM will automatically call JNI_OnUnload() immediately prior to application shutdown.

Rationale: It's my understanding the Class IDs must be registered as global references to maintain the viability of any associated Method ID / Field IDs. If this isn't done and the class is unloaded from the JVM, on class reload, the Method IDs / Field IDs may be different. If the Class ID is registered as a global reference, the associated Method IDs and Field IDs do not need to be registered as global references. Registering a Class ID as a global reference prevents the associated Java class from unloading, therefore stabilizing the Method ID / Field ID values. Global references, including the Class IDs should be removed in JNI_OnUnload().

Method IDs and Field IDs are not managed by the native code; they are managed by the virtual machine and are valid until the associated class is unloaded. Field IDs and Method IDs cannot be explicitly deleted before the virtual machine unloads the defining class; they can be left for the VM to handle after unload.

Sample Code

Comments in the following C++ code sections explain registering variables globally.

Here is the Java class BeanObject representing a data object:

package org.stackoverflow.data;

public class BeanObject {

    String foo = "";
    
    public String getFoo() {
     
        return foo;
    }
}

Here is a skeleton Java class NativeClazz:

package org.stackoverflow.jni;

import org.stackoverflow.data.BeanObject;

public class NativeClazz {

    // Static area for forced initialization
    static {

        // Load Native Library (C++); calls JNI_OnLoad()
        System.loadLibrary("Native_Library_File_Name");
    }       

    /**
     * A static native method you plan to call.
     */
    public static native void staticNativeMethod(BeanObject bean);

    /**
     * A non-static native method you plan to call, to show this also works with 
     * Java class instances.
     */
    public native void instanceNativeMethod(BeanObject bean);
}

Here is the C++ header file "org_stackoverflow_jni_NativeClazz.h" generated using javah on NativeClazz:

/* DO NOT EDIT THIS FILE - it is machine generated */
#include <jni.h>
/* Header for class org_stackoverflow_jni_NativeClazz */

#ifndef _Included_org_stackoverflow_jni_NativeClazz
#define _Included_org_stackoverflow_jni_NativeClazz
#ifdef __cplusplus
extern "C" {
#endif

/*
 * Class:     org_stackoverflow_jni_NativeClazz_staticNativeMethod
 * Method:    staticNativeMethod
 * Signature: ()V
 */
JNIEXPORT void JNICALL Java_org_stackoverflow_jni_NativeClazz_staticNativeMethod
  (JNIEnv *, jclass, jobject);

/*
 * Class:     org_stackoverflow_jni_NativeClazz_instanceNativeMethod
 * Method:    instanceNativeMethod
 * Signature: ()V
 */
JNIEXPORT void JNICALL Java_org_stackoverflow_jni_NativeClazz_instanceNativeMethod
  (JNIEnv *, jobject, jobject);

#ifdef __cplusplus
}
#endif
#endif

Here is the C++ .cpp file implementing the header file:

#include "org_stackoverflow_jni_NativeClazz.h"

using namespace std;

/**************************************************************
 * Static Global Variables to cache Java Class and Method IDs
 **************************************************************/
static jclass JC_BeanObject;              // declare for each class
static jmethodID JMID_BeanObject_getFoo;  // declare for each class method

/**************************************************************
 * Declare JNI_VERSION for use in JNI_Onload/JNI_OnUnLoad
 * Change value if a Java upgrade requires it (prior: JNI_VERSION_1_6)
 **************************************************************/
static jint JNI_VERSION = JNI_VERSION_1_8;

/**************************************************************
 * Initialize the static Class and Method Id variables
 **************************************************************/
jint JNI_OnLoad(JavaVM* vm, void* reserved) {

    // Obtain the JNIEnv from the VM and confirm JNI_VERSION
    JNIEnv* env;
    if (vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION) != JNI_OK) {

        return JNI_ERR;
    }

    // Temporary local reference holder
    jclass tempLocalClassRef;

    // STEP 1/3 : Load the class id
    tempLocalClassRef = env->FindClass("org/stackoverflow/data/BeanObject");

    // STEP 2/3 : Assign the ClassId as a Global Reference
    JC_BeanObject = (jclass) env->NewGlobalRef(tempLocalClassRef);

    // STEP 3/3 : Delete the no longer needed local reference
    env->DeleteLocalRef(tempLocalClassRef);
    
    // Load the method id
    JMID_BeanObject_getFoo = env->GetMethodID(JC_BeanObject, "getFoo", "(Ljava/lang/String;)V");

    // ... repeat prior line for any other methods of BeanObject

    // ... repeat STEPS 1-3 for any other classes; re-use tempLocalClassRef.

    // Return the JNI Version as required by method
    return JNI_VERSION;
}

/**************************************************************
 * Destroy the global static Class Id variables
 **************************************************************/
void JNI_OnUnload(JavaVM *vm, void *reserved) {

    // Obtain the JNIEnv from the VM
    // NOTE: some re-do the JNI Version check here, but I find that redundant
    JNIEnv* env;
    vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION);

    // Destroy the global references
    env->DeleteGlobalRef(JC_BeanObject);
    
    // ... repeat for any other global references
}

/**************************************************************
 * A Static Native Method
 **************************************************************/
JNIEXPORT void JNICALL Java_org_stackoverflow_jni_NativeClazz_staticNativeMethod
               (JNIEnv * env, jclass clazz, jobject jBeanObject) {
    
    // Retrieve jstring from the Java Object
    jstring jFoo = (jstring)env->CallObjectMethod(jBeanObject, JMID_BeanObject_getFoo);

    // Make accessible to C++
    const char * cFoo = env->GetStringUTFChars(jFoo, NULL);             

    // Do something with cFoo...

    // Release Resources
    env->ReleaseStringUTFChars(jFoo, cFoo);
    env->DeleteLocalRef(jFoo);
}

/**************************************************************
 * Instance / Non-Static Native Method
 **************************************************************/
JNIEXPORT void JNICALL Java_org_stackoverflow_jni_NativeClazz_instanceNativeMethod
               (JNIEnv * env, jobject selfReference, jobject jBeanObject) {

    // Retrieve jstring from the Java Object
    jstring jFoo = (jstring)env->CallObjectMethod(jBeanObject, JMID_BeanObject_getFoo);               

    // Make accessible to C++
    const char * cFoo = env->GetStringUTFChars(jFoo, NULL);             

    // Do something with cFoo...

    // Release Resources
    env->ReleaseStringUTFChars(jFoo, cFoo);
    env->DeleteLocalRef(jFoo);
}

Answer 2

Here is how I practice IBM's recommendation. Considering demo java class like that:

public class SimpleClazz {

    public int value = 10;

    public native int getValue();

    static {
        // Load Native Library
        System.loadLibrary("The native library name");
    }
}

The corresponding jni header file like that:

/* DO NOT EDIT THIS FILE - it is machine generated */
#include <jni.h>
/* Header for class SimpleClazz */

#ifndef _Included_SimpleClazz
#define _Included_SimpleClazz
#ifdef __cplusplus
extern "C" {
#endif
/*
 * Class:     SimpleClazz
 * Method:    getValue
 * Signature: ()I
 */
JNIEXPORT jint JNICALL Java_SimpleClazz_getValue
  (JNIEnv *, jobject);

#ifdef __cplusplus
}
#endif
#endif

According to IBM's recommendation, we need to cache the used class SimpleClazz and the field id of the object member value.

After learning this good article, I cache the SimpleClazz in the function JNI_OnLoad, which is called when the native library is loaded (for example, through System.loadLibrary). In the JNI_Onload, we do find class and store this jclass as a global field.

Furthermore, in the native implementation of getValue, we use static local variable to cache the field id of value. This design is to make sure this filed id can be in the better scope, rather than in the global scope. The drawback of this design is that we need to compare with NULL each time we call this function. I learnt this design from section 4.4.1 of the book The Java Native Interface: Programmer's Guide and Specification.

Finally, we also need to write the function JNI_OnUnload, which is called when the class loader containing the native library is garbage collected. In this function, we release the global reference of jclass.

My cpp implementation is shown as below:

#include <jni.h>
#include <SimpleClazz.h>

static jclass simpleCls;

// According to http://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/invocation.html#JNI_OnLoad
// The VM calls JNI_OnLoad when the native library is loaded (for example, through System.loadLibrary).
jint JNI_OnLoad(JavaVM* vm, void* reserved) {
    JNIEnv* env;
    if ((*vm)->GetEnv(vm, (void **) &env, JNI_VERSION_1_6) != JNI_OK) {
        return JNI_ERR;
    } else {
        jclass localSimpleCls = (*env)->FindClass("SimpleClazz");

        if (localSimpleCls == NULL) {
            return JNI_ERR;
        }
        simpleCls = (jclass) (*env)->NewGlobalRef(env, localSimpleCls);
    } 
    return JNI_VERSION_1_6;
}



JNIEXPORT jint JNICALL Java_SimpleClazz_getValue(JNIEnv * env, jobject thiz){
    static jfieldID valueID = NULL;
    if (valueID == NULL) {
        valueID = (*env)->GetFieldID(env, simpleCls, "value", "I");
        if (valueID == NULL){
            return JNI_ERR;         // Exception thrown
        }
    }
    jint value = (*env)->GetIntField(env, thiz, valueID);
    return value;
}

// According to http://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/invocation.html#JNI_OnUnload
// The VM calls JNI_OnUnload when the class loader containing the native library is garbage collected.
void JNI_OnUnload(JavaVM *vm, void *reserved) {
    JNIEnv* env;
    if ((*vm)->GetEnv(vm, (void **) &env, JNI_VERSION_1_6) != JNI_OK) {
        // Something is wrong but nothing we can do about this :(
        return;
    } else {
        if (0 != NULL){
            (*env)->DeleteGlobalRef(env, simpleCls);
        }
    }
}

Answer 3

You can have some utility structures like this:

typedef struct MYVARIANT_FID_CACHE {
    int cached;
    jclass clazz;
    jfieldID pAddress;
} MYVARIANT_FID_CACHE;

MYVARIANT_FID_CACHE VARIANTFc;

void cacheMYVARIANTFields(JNIEnv *env, jobject lpObject)
{
    if (VARIANTFc.cached) return;
    VARIANTFc.clazz = env->GetObjectClass(lpObject);
    VARIANTFc.pAddress = env->GetFieldID(VARIANTFc.clazz, "pAddress", "I");
    VARIANTFc.cached = 1;
}

VARIANT *getMYVARIANTFields(JNIEnv *env, jobject lpObject, VARIANT *lpStruct)
{
    if (!VARIANTFc.cached) cacheVARIANT2Fields(env, lpObject);

    lpStruct = (VARIANT*)(env->GetIntField(lpObject, VARIANTFc.pAddress));

    return lpStruct;
}

This is taken from my question: https://stackoverflow.com/questions/10617714/how-to-extend-swt-com-support

For some good examples look at the os_structs.c it is bundled with eclipse SWT implementation.

Note: The above code is just an example and could be adapted for different OS. Also it just shows "how to access java fields"; for methods you could follow the same approach.