Video tutorial for JNI

JNI (Java Native Interface) allows the communication between a JAVA program and a native program (C, C++). The objective of this first blog post is to give you a quick introduction to this technology. Hopefully, after reading this post and watching the video, you should be able to:

• set up your own environment with Eclipse and Visual Studio
• create a program using JNI
• debug while switching between JAVA and native code
• avoid memory leaks
• understand the risk of JVM crash

I used Eclipse and Microsoft Visual Studio for this demonstration. Eclipse is a popular development IDE for JAVA. You can download it for free on http://www.eclipse.org/. Visual Studio Express is the free version of Visual Studio and it is available here: http://www.microsoft.com/express/.

The example is using two classes Bean and JniExample. JniExample loads the native library (JniExampleLibrary.dll) and exposes the native methods implemented in the DLL. The bean is used to demonstrate how to exchange data through JNI.

We used javah.exe to generate the header file declaring the native methods in the DLL as defined in JniExample.java. The command line is:

javah -d C:\codebazaar\JniExample\cpp\JniExample codebazaar.example.JniExample

We also used javap.exe to generate the method signatures. The command line is:

javap -s codebazaar.example.JniExample

As your program may evolve, I recommend you to save these commands as external tools in eclipse.

To debug the library and the JAVA, in Visual Studio go to Debug, select Attach to Process, find javaw.exe and click on the Attach button.

As in any native code, you need to pay a special attention to memory leak. In the case of JNI, the JVM takes care of most of the job. Any instance passed to or returned by the DLL will be freed by the JVM. You need to free a buffer only if it has been allocated outside the JVM.

Finally, we demonstrated how to get the JVM crash... That was the easy part :D If you are considering communicating with a native library from your web application, you need to realize that a problem in the native library might take the whole server down. As this is not great in term of avaibility, you may consider running the native library on a separate web server.

I uploaded all the source code used. But you can view it directly from here:

package codebazaar.example;

public class Bean {
//public members
public String dataString; 
public byte[] dataByteArray;

public Bean() {}

//getters and setters
public String getDataString() {
return dataString;
}

public void setDataString(String dataString) {
this.dataString = dataString;
}

public byte[] getDataByteArray() {
return dataByteArray;
}

public void setDataByteArray(byte[] dataByteArray) {
this.dataByteArray = dataByteArray;
} 

@Override
public String toString(){
String ret = "string = " + dataString;

ret += " / byteArray =";
if ( dataByteArray != null ) {
for ( byte b : dataByteArray) {
ret += " " + b;
}
}

return  ret; 
}
}

package codebazaar.example;

public class JniExample {
static {
System.loadLibrary("JniExampleLibrary");
}

// native methods
/**
* this method calls printSomething
*/
public native void callJavaMethod();

/**
* this method creates an instance of Bean and returns it
*/
public native Bean createAndReturnBean();

/**
* this method takes an instance of Bean as parameter and changes the value of its members
*/
public native void modifyBean(Bean bean);

/**
* this method will the JVM when invoked 
*/
public native void crashTheJvm();

public void printSomething() {
System.out.println("Thanks for watching this video");
}

public void runExample1() {
System.out.println("starting runExample1...");
callJavaMethod();
}

public void runExample2() {
System.out.println("starting runExample2...");

Bean bean = createAndReturnBean();
System.out.println("returned= " + bean.toString());
}

public void runExample3() {
System.out.println("starting runExample3...");

Bean bean = new Bean();
bean.setDataString("hello");

byte[] byteArray = new byte[] { 0x01, 0x02, 0x03 };
bean.setDataByteArray(byteArray);

System.out.println("before: " + bean.toString());
modifyBean(bean);
System.out.println("after: " + bean.toString());
}

public void runExample4() {
System.out.println("starting runExample4...");
crashTheJvm();
}
}

package codebazaar.example;

public class Main {

/**
* @param args
*/
public static void main(String[] args) {
System.out.println("Starting JavaMain...");

JniExample jniExample = new JniExample();
jniExample.runExample1();
jniExample.runExample2();
jniExample.runExample3();
jniExample.runExample4();
}

}

/* DO NOT EDIT THIS FILE - it is machine generated */
#include 
/* Header for class codebazaar_example_JniExample */

#ifndef _Included_codebazaar_example_JniExample
#define _Included_codebazaar_example_JniExample
#ifdef __cplusplus
extern "C" {
#endif
/*
* Class:     codebazaar_example_JniExample
* Method:    callJavaMethod
* Signature: ()V
*/
JNIEXPORT void JNICALL Java_codebazaar_example_JniExample_callJavaMethod
(JNIEnv *, jobject);

/*
* Class:     codebazaar_example_JniExample
* Method:    createAndReturnBean
* Signature: ()Lcodebazaar/example/Bean;
*/
JNIEXPORT jobject JNICALL Java_codebazaar_example_JniExample_createAndReturnBean
(JNIEnv *, jobject);

/*
* Class:     codebazaar_example_JniExample
* Method:    modifyBean
* Signature: (Lcodebazaar/example/Bean;)V
*/
JNIEXPORT void JNICALL Java_codebazaar_example_JniExample_modifyBean
(JNIEnv *, jobject, jobject);

/*
* Class:     codebazaar_example_JniExample
* Method:    crashTheJvm
* Signature: ()V
*/
JNIEXPORT void JNICALL Java_codebazaar_example_JniExample_crashTheJvm
(JNIEnv *, jobject);

#ifdef __cplusplus
}
#endif
#endif

#include "codebazaar_example_JniExample.h"
#include 

JNIEXPORT void JNICALL Java_codebazaar_example_JniExample_callJavaMethod (JNIEnv * env, jobject obj) {
jclass jniExampleCls = env->GetObjectClass(obj);

jmethodID mid = env->GetMethodID(jniExampleCls, "printSomething", "()V");

env->CallVoidMethod(obj, mid);
}

JNIEXPORT jobject JNICALL Java_codebazaar_example_JniExample_createAndReturnBean  (JNIEnv *env, jobject obj) {
jclass beanClass = env->FindClass("codebazaar/example/Bean");
jmethodID constructorMethodId = env->GetMethodID(beanClass, "", "()V"); 
jobject bean = env->NewObject(beanClass, constructorMethodId);

jstring newString = env->NewStringUTF("this bean has been created in Java_codebazaar_example_JniExample_createAndReturnBean");

jmethodID setStringMid = env->GetMethodID(beanClass, "setDataString", "(Ljava/lang/String;)V");

env->CallVoidMethod(bean, setStringMid, newString );

return bean;
}

JNIEXPORT void JNICALL Java_codebazaar_example_JniExample_modifyBean  (JNIEnv *env, jobject obj, jobject bean) {
jclass beanCls = env->GetObjectClass(bean);

jmethodID setStringMid = env->GetMethodID(beanCls, "setDataString", "(Ljava/lang/String;)V");

// set the bean member "dataString"
jstring newString = env->NewStringUTF("world");
env->CallVoidMethod(bean, setStringMid, newString );

// set the bean member "dataByteArray"
jbyteArray newByteArray = env->NewByteArray(5);
jbyte buffer[5] = {5,4,3,2,1};
env->SetByteArrayRegion( newByteArray, 0, 5, buffer);

jmethodID setByteArrayMid = env->GetMethodID(beanCls, "setDataByteArray", "([B)V");

env->CallVoidMethod(bean, setByteArrayMid, newByteArray );
}


JNIEXPORT void JNICALL Java_codebazaar_example_JniExample_crashTheJvm (JNIEnv *env, jobject obj) {
//stack overflow - http://en.wikipedia.org/wiki/Stack_overflow
double x[1000000];
}

UPDATE 04/02/11:
If you encounter the following error:

java.lang.UnsatisfiedLinkError: ${path here}/library.dll: This application has failed to start because the application configuration is incorrect. Reinstalling the application may fix this problem

I would recommend you to use Dependency Walker to verify your DLL can find all its dependencies. If you are missing msvcr90.dll, you may be missing the Microsoft Redistributable Merge Modules.