Sample Image - JNITest.jpg

Introduction

JNI is my favourite programming framework in Java; it gives you freedom to use natively created code. For example, if you want to use any Windows API (i.e. dll) from your Java code, you can use JNI.

The most popular advantage of Java is platform independence. However, sometimes this feature makes it very difficult to integrate Java programs with native platforms.

For example, in our project we are using MSM Q (Microsoft Messaging Que) for a queuing mechanism to maintain messages (to avoid loss of messages) before writing them to the database. Microsoft is providing MSM Q API which is a Windows' API. But our program produces messages is in Java, and Java can't directly access such VC++ API (dll). So we have decided to make an intermediate DLL which will be work as bridge between Java and VC++ (we have used the technology Java Native Interface, or JNI).

Before proceeding further, you should know / be familiar with some terms.

Native Methods: Native method is a method whose declaration would be in a .java file and the definition would be in your native code. (for Window's it is in VC++).
Static block : Static block in Java is the portion of code executed before anything else happens.

So let's start. First, write your Java program with a declaration of native methods. The following code is from the source sample:

public class JNITest 
{
     static 
       {
        System.loadLibrary("JNITest");  // Loading dll in memory 
       }
        
    native void showMessage( String str);  // Declaring native method
    public JNITest()
    {
        System.out.println( "In the constructor of the Java program" );        
    }
        
    public static void main( String s[] )
    {
         JNITest JNT = new JNITest();
         JNT.showMessage("Passing string from Java");  
    } 
}

In above code we have declared showMessage method which is native, and called it w.r.t. object of class JNITest.

Perform the following:

Compile the code to generate .class file.
In the JDK folder you will find an utility called javah.
Go to the command prompt and execute javah -jni JNITest

Execution of the above will produce the file JNITest.h. This .h file contains VC++ equivalent names of native methods declared in our Java code

Creating JNI DLL

We are almost half-way done.

Now create a simple dll project in Visual Studio (or any other win32 IDE) and add above .h file to the project.

Add the path of your JRE\INCLUDE folder to your includes to get include file jni.h.

Now you will find the names of the methods declared in the .java file in somewhat different manner.

In the above case you will get:

JNIEXPORT void JNICALL Java_JNITest_showMessage(JNIEnv *, jobject, jstring);

Here, the third argument is your argument from Java program. You can convert it to the native form as:

const char *strS1 = env->GetStringUTFChars( s1, 0);

Here you can use strS1 in the program as a C++ string. In the demo program I have used it to display it in Messagebox. There are many methods of JNIEnv by which we can convert various types of data from Java to C++.

Releasing the string after use is compulsory, and is not automatic. JNI activities are presumed to be external to JVM, so it will not throw any kind of exception which could be caught in Java code. If you forget to release the string before leaving the function, this could result in the crashing of your JVM.

You can release the string using the function ReleaseStringUTFChars:

env->ReleaseStringUTFChars( s1, strS1);

The whole code would be look like this:

JNIEXPORT void JNICALL Java_JNITest_showMessage(
    JNIEnv * env, jobject job, jstring str )
{    
       const char *strMsgPtr     = env->GetStringUTFChars( str , 0);    
       //Converting string to C++ character pointer
      
       MessageBox( 0, strMsgPtr,"Message box from VC++ ", 0 ); 
       //Using the string 

       env->ReleaseStringUTFChars( str, strMsgPtr);  
       // Releasing the string ( character pointer )
}

Now you are free to do anything with Windows (or VC++) components - you can now access any Windows API.

Build the dll and place it in your Java program's folder (the folder which contains your .class file).

Now run your Java program.

Note: If you get UnSatisfiedLinkError, Check your method signature (prototype). It must be as same as provided in the .h file

Using JNI, you can access various facilities provided by Windows from Java programs.

Using VC++ components from Java program