A Simple Java Native Interface (JNI) example in Java and Scala

by hohonuuli 8/19/2013 04:33:00 PM 3 comments

A version of this post updated for Java 9 is available on Medium.com

First off, let me be perfectly honest, if you have any choice besides using JNI, do that other thing. Dealing with native libraries has been my number one source of pain when supporting Java applications. Now with that warning out of the way, sometimes you just can't avoid using JNI. For those who must go there, I hope this example helps and I salute your bravery and fortitude.

The Java and Scala examples do exactly the same thing. However, the byte code produced is slightly different since Scala doesn't have static methods.

Step 1 - Create a Java or Scala class

Write a Java or Scala class that will interface to the native library:

Java

In Java, methods that will call the native code will use the native keyword in their method signature and have no method body. Create a file named Sample1.java and add the code below:

class Sample1 {

    // --- Native methods
    public native int intMethod(int n);
    public native boolean booleanMethod(boolean bool);
    public native String stringMethod(String text);
    public native int intArrayMethod(int[] intArray);


    // --- Main method to test our native library
    public static void main(String[] args) {
        System.loadLibrary("Sample1");
        Sample1 sample = new Sample1();
        int square = sample.intMethod(5);
        boolean bool = sample.booleanMethod(true);
        String text = sample.stringMethod("java");
        int sum = sample.intArrayMethod(new int[] {1, 1, 2, 3, 5, 8, 13});

        System.out.println("intMethod: " + square);
        System.out.println("booleanMethod: " + bool);
        System.out.println("stringMethod: " + text);
        System.out.println("intArrayMethod: " + sum);
    }
}

The above code can be compiled using:

    javac Sample1.java

Compiling Sample1.java will produce a single class named, Sample1.class

Scala

In Scala, methods that call native code will use the native annotation and, like Java, have no method signature. Create a file named Sample1.scala and add the code below.

class Sample1 {
  // --- Native methods
  @native def intMethod(n: Int): Int
  @native def booleanMethod(b: Boolean): Boolean
  @native def stringMethod(s: String): String
  @native def intArrayMethod(a: Array[Int]): Int
}

// --- Code in App body will get wrapped in a main method on compilation
object Sample1 extends App {

  // --- Main method to test our native library
  System.loadLibrary("Sample1")
  val sample = new Sample1
  val square = sample.intMethod(5)
  val bool = sample.booleanMethod(true)
  val text = sample.stringMethod("java")
  val sum = sample.intArrayMethod(Array(1, 1, 2, 3, 5, 8, 13))

  println(s"intMethod: $square")
  println(s"booleanMethod: $bool")
  println(s"stringMethod: $text")
  println(s"intArrayMethod: $sum")
}

Sample1.scala can be compiled using:

    scalac Sample1.scala

When you compile Sample1.scala you will get three classes: Sample1.class, Sample1$.class, and Sample1$delayedInit$body.class.

Step 2 - Generate a header file with javah

The next step is to have the JVM produce a header file that defines the function prototypes needed for the native implementation.

Java

Creating the native header is really simple for Java. You just need the compiled class, Simple1.class, created in step1. Use the javah program like so:

    javah Sample1

Notice that you do not use the .class extension. javah will produce a file named Sample1.h.

Scala

Creating a native header from Scala code is slightly more involved in that you may need the scala libraries on the javah classpath. In our example, since we are using Scala's App class we definitly need the scala libraries. In this example, we only need scala-library.jar and scala-reflect.jar. I'm working on a Mac and installed Scala via homebrew and my classpath below reflects that. Your path will likely be different depending on your platform.

    SCALA_LIB_HOME=/usr/local/Cellar/scala/2.10.2/libexec/lib/
    SCALA_CP=$SCALA_LIB_HOME/scala-library.jar:$SCALA_LIB_HOME/scala-reflect.jar
    javah -cp $SCALA_CP:. Sample1

Output from javah will be Sample1.h

The Sample1.h file produced here using Scala looks exactly the same as the file produced using the Java class. Just for grins, this is the output of javah:

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

#ifndef _Included_Sample1
#define _Included_Sample1
#ifdef __cplusplus
extern "C" {
#endif
/*
 * Class:     Sample1
 * Method:    intMethod
 * Signature: (I)I
 */
JNIEXPORT jint JNICALL Java_Sample1_intMethod
  (JNIEnv *, jobject, jint);

/*
 * Class:     Sample1
 * Method:    booleanMethod
 * Signature: (Z)Z
 */
JNIEXPORT jboolean JNICALL Java_Sample1_booleanMethod
  (JNIEnv *, jobject, jboolean);

/*
 * Class:     Sample1
 * Method:    stringMethod
 * Signature: (Ljava/lang/String;)Ljava/lang/String;
 */
JNIEXPORT jstring JNICALL Java_Sample1_stringMethod
  (JNIEnv *, jobject, jstring);

/*
 * Class:     Sample1
 * Method:    intArrayMethod
 * Signature: ([I)I
 */
JNIEXPORT jint JNICALL Java_Sample1_intArrayMethod
  (JNIEnv *, jobject, jintArray);

#ifdef __cplusplus
}
#endif
#endif

Don't you just love C/C++?

Step 3 - Create the native implementation

For both our Scala and Java examples, the native implementation is exactly the same. You can write implementations in either C or C++, although the code will be different. The sample below implements all the methods defined in Sample1.h in C++. Copy and paste the code below into a file named Sample1.cpp:

#include "Sample1.h"
#include <ctype.h>
#include <string.h>

// Mutate array to uppercase
void uppercase(char* str) {
    size_t n = strlen(str);
    for (size_t i = 0; i < n; i++) {
        str[i] = toupper(str[i]); 
    }
}

JNIEXPORT jint JNICALL Java_Sample1_intMethod
(JNIEnv* env, jobject obj, jint num) {
    return num * num;
}


JNIEXPORT jboolean JNICALL Java_Sample1_booleanMethod
(JNIEnv* env, jobject obj, jboolean boolean) {
    return !boolean;
}

JNIEXPORT jstring JNICALL Java_Sample1_stringMethod
(JNIEnv* env, jobject obj, jstring string) {
    const char* str = env->GetStringUTFChars(string, 0);
    char cap[128];
    strcpy(cap, str);
    env->ReleaseStringUTFChars(string, str);
    uppercase(cap);
    return env->NewStringUTF(cap);
}

JNIEXPORT jint JNICALL Java_Sample1_intArrayMethod
(JNIEnv* env, jobject obj, jintArray array) {
    int sum = 0;
    jsize len = env->GetArrayLength(array);
    jint* body = env->GetIntArrayElements(array, 0);
    for (int i = 0; i < len; i++) {
        sum += body[i];
    }
    env->ReleaseIntArrayElements(array, body, 0);
    return sum;
}

Now the fun part, getting this to compile on your particular operating system. Since I'm working on a Mac here's the command line blurb I used to compile Sample1.cpp to a shared native library:

    g++ -dynamiclib -G -Wall -O3 \
        -I/usr/include -I$JAVA_HOME/include -I$JAVA_HOME/include/darwin \
        Sample1.cpp -o libSample1.dylib

A few notes about this:

1. Notice the -dynamiclib flag, this creates a shared library and is required. On linux use -shared instead. 
2. You have to include Java's jni headers which are always in at least 2 places. 
1. $JAVA_HOME/include
2. $JAVA_HOME/include/<platform> . On Macs that's $JAVA_HOME/include/darwin, on Linux it's $JAVA_HOME/include/linux. I have no idea what it is on Windows.
3. You may have to set the JAVA_HOME variable on your machine. You can do this on a Mac using: export JAVA_HOME=`/usr/libexec/java_home -v 1.7`
4. Remember the line in our Java/Scala code that goes: System.loadLibrary("Sample1"). Although the name of the native library is referenced using "Sample1" in our code, it's actually looked up using a 'lib' prefix. So the native library is actually named libSample1.dylib on Mac or libSample1.so on Linux. 
5. If you're stuck developing for Java 6 on a Mac, change the native libraries extension to .jnilib or Java 6 won't find it. Java 7 on Mac requires .dylib extension. (I did try to warn you that JNI will test your strength)

Step 4 - Running the Code

Running either sample is straight-forward. However, you need to ensure that native library is on Java's or Scala's library path. The simplest way to do this is to add it to the java.library.path when you start your JVM. 

Java

   # Assumes all files are in the same directory.
    # If they are not, replace $(pwd) with the directory containing libSample1.so or libSample1.dylib
    java -Djava.library.path=$(pwd) -cp . Sample1

Scala

    scala -Djava.library.path=$(pwd) -cp . Sample1

or 

    SCALA_LIB_HOME=/usr/local/Cellar/scala/2.10.2/libexec/lib/
    SCALA_CP=$SCALA_LIB_HOME/scala-library.jar:$SCALA_LIB_HOME/scala-reflect.jar
    java -Djava.library.path=$(pwd) -cp $SCALA_CP:. Sample1

A Note about Deployment

It's not always feasible to set the java.library.path variable (e.g. when using Java Web Start). However, it is not particularly difficult to hack the path used internally by Java to add shared libraries at runtime. This is, however, a topic beyond the scope of this posting.