Java Fundamentals Tutorial: Java Native Interface (JNI)

Motivation for JNI

javah - JDK tool that builds C-style header files from a given Java class that includes native methods

jni.h - C/C++ header file included with the JDK that maps Java types to their native counterparts

We are now ready to compile our program and run it

Two kind of types in Java:

However, primitive and reference types are treated differently in JNI

Let us consider the following Java class:

package com.marakana.jniexamples;

public class HelloName {
  public static native void sayHelloName(String name);

  static { System.loadLibrary("helloname"); }

  public static void main (String[] args) {
    HelloName hello = new HelloName();
    String name = "John";
    hello.sayHelloName(name);
  }
}

The .h file would look like this:

...
#include <jni.h>
...
JNIEXPORT void JNICALL Java_com_marakana_jniexamples_HelloName_sayHelloName
  (JNIEnv *, jclass, jstring);
...

A .c file like this one would not produce the expected result:

#include <stdio.h>
#include "com_marakana_jniexamples_HelloName.h"


JNIEXPORT void JNICALL Java_com_marakana_jniexamples_HelloName_sayHelloName(JNIEnv *env, jclass class, jstring name){
    printf("Hello %s", name);
}

All native method implementation accepts two standard parameters:

There are a lot of methods related to strings:

	Note
	Details about these methods can be found at http://download.oracle.com/javase/6/docs/technotes/guides/jni/spec/functions.html

If you remember the previous example, we had a native method where we wanted to display "Hello name":

#include <stdio.h>
#include "com_marakana_jniexamples_HelloName.h"

JNIEXPORT void JNICALL Java_com_marakana_jniexamples_HelloName_sayHelloName(JNIEnv *env, jclass class, jstring name) {
    printf("Hello %s", name); //
}

Here is what you would do, using UTF-8 string for instance:

#include <stdio.h>
#include "com_marakana_jniexamples_HelloName.h"

JNIEXPORT void JNICALL Java_com_marakana_jniexamples_HelloName_sayHelloName(JNIEnv *env, jclass class, jstring name){
    const jbyte *str;
    str = (*env)->GetStringUTFChars(env, name, NULL); //
    printf("Hello %s\n", str);
    (*env)->ReleaseStringUTFChars(env, name, str); //
}

Here is another example where we would construct and return a java.lang.String instance:

#include <stdio.h>
#include "com_marakana_jniexamples_GetName.h"

JNIEXPORT jstring JNICALL Java_com_marakana_jniexamples_ReturnName_GetName(JNIEnv *env, jclass class) {
    char buffer[20];
    scanf("%s", buffer);
    return (*env)->NewStringUTF(env, buffer);
}

Again we will use the JNIEnv *env parameter to access the type conversion methods

First, this would be your Java program:

package com.marakana.jniexamples;

public class ArrayReader {
    private static native int sumArray(int[] arr); //
    public static void main(String[] args) {
        //Array declaration
        int arr[] = new int[10];
        //Fill the array
        for (int i = 0; i < 10; i++) {
            arr[i] = i;
        }
        ArrayReader reader = new ArrayReader();
        //Call native method
        int result = reader.sumArray(arr); //
        System.out.println("The sum of every element in the array is " + Integer.toString(result));
    }
    static {
        System.loadLibrary("arrayreader");
    }
}

After running javah, create your .c file that would look like this:

#include <stdio.h>
#include "com_marakana_jniexamples_ArrayReader.h"

JNIEXPORT jint JNICALL Java_com_marakana_jniexamples_ArrayReader_sumArray(JNIEnv *env, jclass class, jintArray array) {
    jint *native_array;
    jint i, result = 0;
    native_array = (*env)->GetIntArrayElements(env, array, NULL); /*  */
    if (native_array == NULL) {
        return 0;
    }
    for (i=0; i<10; i++) {
        result += native_array[i];
    }
    (*env)->ReleaseIntArrayElements(env, array, native_array, 0);
    return result;
}

Throwing an exception from the native world involves the following steps:

We could imagine a utility function like this one:

void ThrowExceptionByClassName(JNIEnv *env, const char *name, const char *message) {
  jclass class = (*env)->FindClass(env, name); //
  if (class != NULL) {
      (*env)->ThrowNew(env, class, message); //
  }
  (*env)->DeleteLocalRef(env, class); //
}

Here would be how to use this utility method:

ThrowExceptionByClassName(env,"java/lang/IllegalArgumentException","This exception is thrown from C code");

From this Java class, we will see how to call its methods or access its properties in the native code:

package com.marakana.jniexamples;

public class InstanceAccess {
    public String name; //

    public void setName(String name) { //
        this.name = name;
    }

    //Native method
    public native void propertyAccess(); //
    public native void methodAccess(); //

    public static void main(String args[]) {
        InstanceAccess instanceAccessor = new InstanceAccess();
        //Set the initial value of the name property
        instanceAccessor.setName("Jack");
        System.out.println("Java: value of name = \""+ instanceAccessor.name +"\"");
        //Call the propetyAccess() method
        System.out.println("Java: calling propertyAccess() method...");
        instanceAccessor.propertyAccess(); //
        //Value of name after calling the propertyAccess() method
        System.out.println("Java: value of name after calling propertyAccess() = \""+ instanceAccessor.name +"\"");
        //Call the methodAccess() method
        System.out.println("Java: calling methodAccess() method...");
        instanceAccessor.methodAccess(); //
        System.out.println("Java: value of name after calling methodAccess() = \""+ instanceAccessor.name +"\"");
    }

    //Load library
    static {
        System.loadLibrary("instanceaccess");
    }
}

This would be our C code for native execution:

#include <stdio.h>
#include "com_marakana_jniexamples_InstanceAccess.h"


JNIEXPORT void JNICALL Java_com_marakana_jniexamples_InstanceAccess_propertyAccess(JNIEnv *env, jobject object){
    jfieldID fieldId;
    jstring jstr;
    const char *cString;

    /* Getting a reference to object class */
    jclass class = (*env)->GetObjectClass(env, object); /*  */

    /* Getting the field id in the class */
    fieldId = (*env)->GetFieldID(env, class, "name", "Ljava/lang/String;"); /*  */
    if (fieldId == NULL) {
        return; /* Error while getting field id */
    }

    /* Getting a jstring */
    jstr = (*env)->GetObjectField(env, object, fieldId); /*  */

    /* From that jstring we are getting a C string: char* */
    cString = (*env)->GetStringUTFChars(env, jstr, NULL); /*  */
    if (cString == NULL) {
        return; /* Out of memory */
    }
    printf("C: value of name before property modification = \"%s\"\n", cString);
    (*env)->ReleaseStringUTFChars(env, jstr, cString);

    /* Creating a new string containing the new name */
    jstr = (*env)->NewStringUTF(env, "Brian"); /*  */
    if (jstr == NULL) {
        return; /* Out of memory */
    }
    /* Overwrite the value of the name property */
    (*env)->SetObjectField(env, object, fieldId, jstr); /*  */
}


JNIEXPORT void JNICALL Java_com_marakana_jniexamples_InstanceAccess_methodAccess(JNIEnv *env, jobject object){
    jclass class = (*env)->GetObjectClass(env, object); /*  */
    jmethodID methodId = (*env)->GetMethodID(env, class, "setName", "(Ljava/lang/String;)V"); /*  */
    jstring jstr;
    if (methodId == NULL) {
        return; /* method not found */
    }
    /* Creating a new string containing the new name */
    jstr = (*env)->NewStringUTF(env, "Nick"); /*  */
    (*env)->CallVoidMethod(env, object, methodId, jstr); /*  */
}