How to access a C function from Java?

Java Call C function

Java is a higher level language and works in platform independent way. Java can run on Linux, Windows, Mac, Android and many platforms. Java does not provide any standard or class APIs to interact with platform software. However there are many situations where user may require to interface with system software. System softwares are written mainly with C language. So some common questions may arise like how to run c program through java? or how to load c library in java? or call dll in java? Java Native Interface or JNI is the interface to bridge between C and Java. This article is primarily a java native interface tutorial for a new java programmer.

JNI Java C banner

JavaC and JRE

Java programs are written inside source files as plain text format. These files are compiled with the help of Java Compiler or known as javac executable. Java compiler do not compile the source to native platform binary but it prepares an intermediate executable code. Java compiler generates platform independent executable code known as Java Byte code or JBC. Java Byte code files are are stored in ".class" files. These are not native executables like C, C++ etc generates. So they cannot be executed directly. Java runtime environment or JRE is an executable which runs java byte code in any platform.

Java Native Interface/JNI

Java run time environment(JRE) executes Java byte Code(JBC) from class binaries in platform independent way. Sometimes java applications may need to access some of the system resources which are strictly platform dependent. Java language is limited to upper layer and cannot access this directly from its context. However there is a provision in Java to interface with native binaries. This interface is well known as Java Native Interface or JNI in short. JNI in the gateway between JAVA and native binaries, written in C/C++/VB or any other compiled languages.

Java Native Interface requires below three files.

  1. Java source file - Main application java file which calls C functions
  2. C header file - C function prototypes are declared here
  3. C source file - C source implementation of the native functions

Java JNI Code

We have JNIDemo class code with main() routine to demo this JNI application. We have three member functions.

  1. void HelloWorld();
  2. int CallC ();
  3. void SetMembers();

public class MyJNI {
  static {
    try{
      /* MyJNI.dll (Windows) or libMyJNI.so (Linux) */
      System.loadLibrary("MyJNI");
    } catch(java.lang.UnsatisfiedLinkError err){
      /* Error output when native binary not present */
      System.out.println("Unable to load MyJNI library");
      System.exit(0);
    }
  }
  private boolean z;
  private byte    b;
  private char    c;
  private short   s;
  private int     i;
  private long    j;
  private float   f;
  private double  d;
  private String  str;

  /* JNI simple interface take no arguments and no returns */
  private native void HelloWorld();
  /* JNI Call by Value */
  private native int CallC (boolean z,
                            byte    b,
                            char    c,
                            short   s,
                            int     i,
                            long    j,
                            float   f,
                            double  d,
                            String  str);
  /* JNI Call by Value */
  private native void SetMembers();
 
  public static void main(String[] args) {
    MyJNI myjni = new MyJNI();
    myjni.HelloWorld();
    System.out.println("Calling by Value");
    myjni.CallC (true,
                 (byte)'J',
                 'K',
                 (short)10,
                 100,
                 (long)1000,
                 (float)1.2,
                 1.5,
                 "Hello From Java!");
      myjni.z = true;
      myjni.b = (byte)'C';
      myjni.c = 'D';
      myjni.s = 20;
      myjni.i = 200;
      myjni.j = 2000;
      myjni.f = (float)2.2;
      myjni.d = 2.5;
      myjni.str = "Hello from Java!";
      System.out.println("Calling by Reference");
      myjni.SetMembers();
      System.out.println("End of Calling by Reference");
      System.out.println("Java Members (changed)");
      System.out.println("z (boolean) = " + myjni.z);
      System.out.println("b (byte) = " + (char)myjni.b);
      System.out.println("c (char) = " + (char)myjni.c);
      System.out.println("s (short) = " + (short)myjni.s);
      System.out.println("i (int) = " + myjni.i);
      System.out.println("l (long) = " + myjni.j);
      System.out.println("f (float) = " + myjni.f);
      System.out.println("d (double) = " + myjni.d);
      System.out.println("str (string) = " + myjni.str);
   }
}

These three functions are declared with native keyword. Native keyword instructs compiler to link the functions even if the definition of HelloWorld(), CallC() and SetMembers() do not exist. This is similar to linking a function from library DLL/SO file. Java compiler puts these interfaces in import table or checks import table of DLL/so during runtime linking. At this point we have java application code but there is no implementation in native side of the library.

JNI library error

We try to execute this code we will get error as Java runtime will fail to load import library JNIDemo.dll or libJNIDemo.so. 

>javac JNIDemo.java
>java JNIDemo
Unable to load JNIDemo library

JNI Interface generation

Now we will start implementing the native side of the library. We need a tool called JAVAH (C Header and Stub File Generator) JAVAH comes with Java Development Kit and can be executed in the same way as we execute comiler javac or java. Javah takes byte code file name (without .class extension) as argument. It process the binary and generates a C/C++ header file in the same name. Name of the header file in the same name. 

>javah JNIDemo

JNI header file

Note carefully javah has generated three function prototype in C/C++.

  • Java_JNIDemo_HelloWorld() is the equivalent JNI prototype of HelloWorld() in java.
  • Java_JNIDemo_CallC() is the equivalent JNI prototype of CallC() in java. It is calling all arguments by value.
  • Java_JNIDemo_SetMembers() is the equivalent JNI prototype of SetMembers() in java.
/* DO NOT EDIT THIS FILE - it is machine generated */
#include <jni.h>
/* Header for class MyJNI */

#ifndef _Included_MyJNI
#define _Included_MyJNI
#ifdef __cplusplus
extern "C" {
#endif
/* * Class: MyJNI * Method: HelloWorld * Signature: ()V */
JNIEXPORT void JNICALL Java_MyJNI_HelloWorld
  (JNIEnv *, jobject);

/* * Class: MyJNI * Method: CallC * Signature: (ZBCSIJFDLjava/lang/String;)I */
JNIEXPORT jint JNICALL Java_MyJNI_CallC
  (JNIEnv *, jobject, jboolean, jbyte, jchar, jshort, jint, jlong, jfloat, jdouble, jstring);

/* * Class: MyJNI * Method: SetJMembers * Signature: ()V */
JNIEXPORT void JNICALL Java_MyJNI_SetMembers
  (JNIEnv *, jobject);

#ifdef __cplusplus
}
#endif
#endif

JNIEXPORT macro tells C/C++ compiler to export these functions from DLL/SO library so that java run time can import these calls. Additionally there are two extra arguments for each functions. First argument is of type JNIEnv which gives a pointer to Java Runtime Environment. JNIEnv provides many interfaces which native binary can utilize. Next argument is of type jobject which represents the object itself or the "this" pointer. We can access members of the object through this arguments. Next arguments are same as declared in java. jboolean, jbyte, jchar, jshort, jlong, jfloat, jdouble are type definition of unsigned char, signed char, signed short, short, int, long, float and double in C/C++. Now java treats strings as UNICODE thus jstring is not directly char * but conversions are possible in both the ways.

Call by reference in java is not possible but this is equivalent of Call by reference in java. It access and modify member variables of JNIDemo class object and thus can be treated as the equivalent of call by reference.

Implement JNI Native C/C++

Now we will implement these interfaces in a dynamic link library in Windows or in a shared library in Linux. We need to create a C/C++ source file and may need to copy this header file to the same solder. Here we created JNIDemo.c in the same folder where JNIDemo.h is located. We should include this file and implement the definitions. jchar, jshort, jlong, jfloat, jdouble are type definition of char, short, long, float and double in C/C++ thus we can used these directly. But this is not true for the strings. Java treats strings char char as UNICODE. There are two bytes for each characters. First character contains ASCII value and next one contains language id. jstring can be converted to UTF char* and vice versa. GetStringUTFChars() can be used to extract char* from Java strings. NewStringUTF() is used to allocate a new UNICODE string from UTF char*. ReleaseStringUTFChars() is used to release existing buffer. Here in Java_JNIDemo_CallC(), we are simply printing the values passed from Java in C/C++ context and directly returning to Java context. Java_JNIDemo_SetMembers() is not taking arguments. Every C++/Java function has inherent member called this pointer. This function uses this object to access all member variables. JNI can access and modify all the members. These are the steps to access/modify Java members.

  • GetObjectClass() returns the class reference
  • GetFieldID() returns field ID of the member from class reference
  • GetXXXXField()/GetObjectField returns an instance of the member variable from object
  • SetXXXXField()/SetObjectField can be used to set the member value

This is only a demo however in practical situation where system applications need to access system resources can open device files and can call mmap/ioctls/sysctl etc to interface deeper inside into system side.

/* MyJNI.cpp : Defines the entry point for the DLL application. */
#include <stdio.h>
#include "MyJNI.h"
BOOL APIENTRY DllMain ( HANDLE hModule, 
                        DWORD  ul_reason_for_call, 
                        LPVOID lpReserved
                      )
{
    return TRUE;
}

JNIEXPORT void JNICALL Java_MyJNI_HelloWorld (JNIEnv *,
                                              jobject)
{
  printf ("Hello World!\n");

}

JNIEXPORT jint JNICALL Java_MyJNI_CallC (JNIEnv * env,
                                         jobject  jobj,
                                         jboolean z,
                                         jbyte    b,
                                         jchar    c,
                                         jshort   s,
                                         jint     i,
                                         jlong    j,
                                         jfloat   f,
                                         jdouble  d,
                                         jstring  str)
{

  printf ("Arguments from Java \n");
  printf ("z (boolean) = %s\n", b ? "true" : "false");
  printf ("b (byte) = %c\n", b);
  printf ("c (char) = %c\n", c);
  printf ("s (short) = %d\n", (int)s);
  printf ("i (int) = %d\n", i);
  printf ("l (long) = %ld\n",j);
  printf ("f (float) = %f\n", f);
  printf ("d (double) = %f\n", d);
  printf ("str (string) = %s\n", env->GetStringUTFChars( str, NULL));
  return 0;
}

JNIEXPORT void JNICALL Java_MyJNI_SetMembers (JNIEnv * env,
                                              jobject jobj)
{

  jfieldID fidnum;
  printf ("Java members (from C)\n");

   /* Get a reference to this object's class */
   jclass thisclass = env->GetObjectClass(jobj);
 
  /* ============== Boolean ================= */
  /* Boolean Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "z", "Z");
  if (NULL == fidnum) {
    return;
  }
  /* Get the boolean given the Field ID */
  jboolean z = env->GetBooleanField(jobj, fidnum);
  printf ("z (boolean) = %s\n", z ? "true" : "false");
 
  /* Change the variable */
  z = false;
  env->SetBooleanField(jobj, fidnum, z);

  /* ============== Byte ================= */
  /* Byte Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "b", "B");
  if (NULL == fidnum) {
    return;
  }
  /* Get the byte given the Field ID */
  jbyte b = env->GetByteField(jobj, fidnum);
  printf ("b (byte) = %c\n", b);
 
  /* Change the variable */
  b += 1;
  env->SetByteField(jobj, fidnum, b);
  
  /* ============== Char ================= */
  /* Char Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "c", "C");
  if (NULL == fidnum) {
    return;
  }
  /* Get the char given the Field ID */
  jchar c = env->GetCharField(jobj, fidnum);
  printf ("c (char) = %c\n", c);
 
  /* Change the variable */
  c += 1;
  env->SetCharField(jobj, fidnum, c);

  /* ============== Short ================= */
  /* Short Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "s", "S");
  if (NULL == fidnum) {
    return;
  }
  /* Get the short given the Field ID */
  jshort s = env->GetShortField(jobj, fidnum);
  printf ("s (short) = %d\n", s);
 
  /* Change the variable */
  s = 10;
  env->SetShortField(jobj, fidnum, s);

  /* ============== Int ================= */
  /* Int Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "i", "I");
  if (NULL == fidnum) {
    return;
  }
  /* Get the int given the Field ID */
  jint i = env->GetIntField(jobj, fidnum);
  printf ("i (int) = %d\n", i);
 
  /* Change the variable */
  i = 100;
  env->SetIntField(jobj, fidnum, i);

  /* ============== Long ================= */
  /* Long Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "j", "J");
  if (NULL == fidnum) {
    return;
  }
  /* Get the long given the Field ID */
  jlong j = env->GetLongField(jobj, fidnum);
  printf ("l (long) = %ld\n", j);
 
  /* Change the variable */
  j = 1000;
  env->SetLongField(jobj, fidnum, j);

  /* ============== Float ================= */
  /* Float Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "f", "F");
  if (NULL == fidnum) {
    return;
  }
  /* Get the float given the Field ID */
  jfloat f = env->GetFloatField(jobj, fidnum);
  printf ("f (float) = %f\n", f);
 
  /* Change the variable */
  f = (float)1.2;
  env->SetFloatField(jobj, fidnum, f);

  /* ============== Double ================= */
  /* Double Get the Field ID of the instance */
  fidnum = env->GetFieldID(thisclass, "d", "D");
  if (NULL == fidnum) {
    return;
  }
  /* Get the Double given the Field ID */
  jdouble d = env->GetDoubleField(jobj, fidnum);
  printf ("d (double) = %f\n", d);
 
  /* Change the variable */
  d = 1.5;
  env->SetDoubleField(jobj, fidnum, d);

  /* ============== String ================= */
  /* String Get the Field ID of the instance */
   fidnum = env->GetFieldID(thisclass, "str", "Ljava/lang/String;");
  if (NULL == fidnum) {
    return;
  }
  /* Get the String given the Field ID */
  jstring str = (jstring)env->GetObjectField(jobj, fidnum);
  printf ("str (string) = %s\n", env->GetStringUTFChars(str, NULL));

  /* Change the variable */
  env->ReleaseStringUTFChars(str, "str");
  str = env->NewStringUTF ((const char *) "Hello form C!");
  env->SetObjectField(jobj, fidnum, str);

}

JNI Block Diagram

JNI Block Diagram

JNI Execution

Now we need to place this native library in the same folder where our Java Class binary located and can run. If we have more than one class We can also place this in the Java Runtime binary folder jre\bin if we want to access this from more than one java class located in different folder. 

:>java JNIDemo
Hello World!
Calling by Value
Arguments from Java
z (boolean)  = true
b (byte)     = J
c (char)     = K
s (short)    = 10
i (int)      = 100
l (long)     = 1000
f (float)    = 1.200000
d (double)   = 1.500000
str (string) = Hello From Java!
Calling by Reference
Java members (from C)
z (boolean)  = true
b (byte)     = C
c (char)     = D
s (short)    = 20
i (int)      = 200
l (long)     = 2000
f (float)    = 2.200000
d (double)   = 2.500000
str (string) = Hello from Java!
End of Calling by Reference
Java Members (changed)
z (boolean)  = false
b (byte)     = D
c (char)     = E
s (short)    = 10
i (int)      = 100
l (long)     = 1000
f (float)    = 1.2
d (double)   = 1.5
str (string) = Hello form C!

About our authors: Team EQA

You have viewed 1 page out of 252. Your C learning is 0.00% complete. Login to check your learning progress.

‹ # ›

Questions index C Questions C++ Questions Win32 MFC COM/DCOM DLL Questions