JNI made easy

Using JNI can sometimes be tricky. Getting all the settings right can be a nightmare when done for the first time.
In this tutorial I will use Eclipse with CDT (using MinGW/gcc) to create a simple hello world example. Therefore we will create a Java program, that calls native code from a shared library.

Source code for this tutorial is available on googlecode as a single zip archive or you can checkout the SVN projects directly.


Step 1: Creating a Java Project

First create a new Java Project called "JNI Test". Create a class com.example.jni.JNITest with following content:

package com.example.jni;

public class JNITest {

    static {
        // load library
        System.loadLibrary("JNI Library");
    }

    public static void main(final String[] args) {
        new JNITest().hello("world");
    }

    // native method signature
    public native void hello(String name);
}

Line 7 will trigger loading of the shared library.
Line 15 declares an external method which is implemented in the native library.

Create a new folder called resources under your project root. This will be the location for our JNI library.


Step 2: Create C++ Project

Now we need to create the library code. Therefore create a new C++ Project called "JNI Library". Create a source folder src within that project. The function header for the shared function needs to follow a very specific coding. This is generated by javah, a helper program of your JDK. We will do this by using an external tool helper.
Use Run -> External Tools -> External Tools Configurations... and create a new Program launcher.

This launcher will create a header file within the src folder of our C++ Project. On linux you will have to change the Location to /usr/bin/javah. On the refresh tab you can enable refreshing of this folder. Otherwise refresh manually after file creation.

Open the project properties of JNI Library and go to C/C++ General/Paths and Symbols. On the Includes tab add include and include/win32 folders of your JDK to the include paths for GNU C++.

On linux you need to includethe folders include and include/linux.

 
Now we can add our implementation in C++.
Create a new source file within src folder named com_example_jni_JNITest.cpp. Add following content to the file

#include  <iostream>

#include "com_example_jni_JNITest.h"

using namespace std;

JNIEXPORT void JNICALL Java_com_example_jni_JNITest_hello
    (JNIEnv *env, jobject jthis, jstring data) {

    jboolean iscopy;
    const char *charData = env->GetStringUTFChars(data, &iscopy);
    cout << "Hello " << charData << endl;
    env->ReleaseStringUTFChars(data, charData);
}

JNI needs a shared library to access, so we need to customize build settings a bit. Open the project properties and go to C/C++ Build/Settings. On the Tool Settings tab we need to add some linker flags. Add

-Wl,--add-stdcall-alias

at MinGW C++ Linker/Miscellaneous.

Check that Shared(-shared) is enabled at MinGW C++ Linker/Shared Library Settings.

On the Build Steps tab add following Post-Build step:

xcopy "${BuildArtifactFilePrefix}${BuildArtifactFileName}" "${workspace_loc:/JNI Test/resources/}" /Y

This will automatically copy our build product to the Java Project we created at step 1.
Finally go to Build Arifact tab and select Shared Library as Artifact Type.

Save all settings and build your library. It should be copied over to your Java Project. Refresh your workspace (F5) to see the newly created file.

Step 3: Put it all together

We are almost done. As a final step we need to add the resource folder to the library path of our run target.  Launch your Java program to create a launch target for it. You will get an Exception, don't worry, we'll fix that immediately. Go to Run -> Run Configurations... and find your Java run target (typically named JNITest). On the Arguments tab add

-Djava.library.path="${workspace_loc}/com.example.jni/resources;${env_var:PATH}"

to VM arguments.

Now launch your Java program and you should get a "Hello world" on your console view.