Java Native Interface (JNI) is a simple tool that allows calling \t\tnative functions from Java code. In addition, a native function which \t\tis called by Java may be able to call back Java functions but we shall \t\tnot discuss this functionality in this tutorial.<\/p>\n
There are plenty of existing guides (some of them are listed \t\tbelow), and I am not competing with them.<\/p>\n
Rather, my purpose is to complement them with my experiences: \t\twhen I tried to use JNI myself and followed these tutorials, I found a \t\tfew difficulties which were not covered in them, and I wanted explain \t\thow I dealt with these difficulties which included packages and \t\tmangling conventions. This step-by-step guide explains exactly how I \t\tdealt with the difficulties I encountered.<\/p>\n
I have been writing code that was supposed to work on Windows \t\twhile running myself a Linux Ubuntu with Eclipse Java development \t\tenvironment.<\/p>\n
Of course, I needed a Windows machine to compile and run Windows \t\tcode, and for this purpose I had access to a Windows XP 32-bit \t\tcomputer on which I ran Eclipse 4.3.2, both for Java and for C\/C++ \t\tnative code; for C\/C++ I used MinGW C\/C++ toolchain.<\/p>\n
Note that the dll I produced on the 32 bit computer, cannot be \t\tcalled from 64-bit code. Practically, this means that if I run 32-bit \t\tJRE, whether on 32-bit computer or an AMD64 one, I can call this dll \t\tfrom it; however, if I run 64-bit JRE (this can be done only on an \t\tAMD64 computer), I cannot call this library.<\/p>\n
A side note: if you need to cover both 32-bit and 64-bit JRE, \t\tyou need to compile two different dlls, write Java code that \t\tdetermines whether your JRE is 32-bit or 64-bit, and load the \t\tappropriate one of the two, e.g.:<\/p>\n
if(Platform.osArch.contains(\"64\")) {
load your 64-bit dll<\/em>
}
else {
load your 32-bit dll<\/em>
}<\/code><\/pre>\nFirst, read the existing tutorials<\/span><\/h2>\n \t\tI suggest starting with reading a \t\t\tnice introduction and a step-by-step guide written in 2004 by Govind \t\t\tSeshadri<\/a>. We shall follow the same steps below, although I shall add \t\tsome details of mine. If you want, you can complement it with the \t\t\tWikipedia article<\/a>. \t<\/p>\n \t\tOther resources: there is a faster and more advanced \t\t\ttutorial<\/a> and a \t\t\tJavaWorld article by Tal Liron<\/a>. \t<\/p>\nHow to run javah to create a C header for JNI functions<\/span><\/h2>\nThis is the first step in implementing JNI.<\/p>\n
Create a java file with a native function declaration (as \t\texplained in the above tutorials), and compile it.<\/p>\n
Open a terminal.<\/p>\n
\t\tIf your java files were created by Eclipse, go to the \t\tbin\/<\/code> \t\tdirectory of the project (i.e., \t\tcd<\/code> \t\tto this directory). \t<\/p>\n \t\tOtherwise, go to the directory where the package tree of the class \t\tfiles starts (the \t\tbin\/<\/code> \t\tdirectory of an Eclipse project is a particular case of it). \t<\/p>\n \t\tE.g., if \t\tMyClass<\/code> \t\tis declared in the package \t\tPkg1.Pkg2.Pkg3<\/code> \t\tand \t\tMyClass.class<\/code> \t\tlies in \t\tMyDir\/Pkg1\/Pkg2\/Pkg3<\/code> \t\tthen \t\tcd<\/code> \t\tin your terminal to \t\tMyDir<\/code> \t\t. \t<\/p>\n \t\tAfter that run javah:
\t\tjavah Pkg1.Pkg2.Pkg3.MyClass<\/code> \t<\/p>\n \t\tThis creates your header file:
\t\t Pkg1_Pkg2_Pkg3_MyClass.h<\/code> \t<\/p>\n \t\tIt is placed in the same directory, \t\tMyDir<\/code> \t\t. \t<\/p>\nThis file contains the C\/C++ declarations of the native \t\tfunctions to be called from Java. It starts with the lines<\/p>\n
\/* DO NOT EDIT THIS FILE - it is machine generated *\/
#include <jni.h><\/code><\/pre>\n \t\tThe header file referenced here, \t\tjni.h<\/code> \t\t, is provided by java; I have found it in the directory \t<\/p>\n<Java installation directory>\/jdk1.7.0_51\/include<\/code><\/pre>\nOn my Windows computer, this is<\/p>\n
C:\\Program Files\\Java\\jdk1.7.0_51\\include<\/code><\/pre>\nThis directory needs to be added to the include path, together \t\twith its subdirectory win32<\/p>\n
<Java installation directory>\/jdk1.7.0_51\/include\/win32<\/code><\/pre>\n \t\tthat contains another header file, \t\tjni_md.h<\/code> \t\twhich is \t\t#include<\/code> \t\t‘d by \t\tjni.h<\/code> \t\t. \t<\/p>\n \t\t (Note that jdk1.7.0_51<\/code> in the directory \t\t\tpath reflects the fact that I was running jdk 1.7.0 Release 51; if \t\t\tyou update your jdk to a later version, while doing that you change \t\t\tthe directory name jdk1.7.0_51<\/code> accordingly and want to \t\t\tbuild your dll again, you would have to update your include path.) \t\t<\/small> \t<\/p>\n \t\tStill, Eclipse with MinGW C\/C++ compliler could not find this include \t\teven though it could display \t\tjni.h<\/code> \t\tin its include list. The only thing that helped, was to replace the \t\tline
\t\t #include <jni.h><\/code> \t\t
by
\t\t #include \"jni.h\"<\/code> \t\t
(Regretfully, I had to disregard the warning not to edit \t\tthis file.) \t<\/p>\nAfter that the file successfully compiled.<\/p>\n
Calling this code from java<\/span><\/h2>\nThe next step is to create a .c file that implements the \t\tdeclarations in this header (assuming you want to implement it in C as \t\tI did).<\/p>\n
Compile it to create a Windows dll; if its name is hello.dll \t\tthen do the following.<\/p>\n
Place hello.dll on the Java build path of this project; in \t\tEclipse, open Project Properties (by right-clicking on the project in \t\tthe project explorer) \u2192 Java build path \u2192 Source \u2192 native library \t\tlocation \u2192 Edit, and make sure that the folder containing hello.dll is \t\tincluded.<\/p>\n
Insert the following code in the class that calls the native \t\tfunction:<\/p>\n
static {
System.loadLibrary(\"hello\"); \/\/ Load native library at runtime
\/\/ hello.dll (Windows) or libhello.so (Unixes)
}<\/code><\/pre>\n \t\tNote that this code must appear before you actually call your native \t\tfunction; usually this code is put in the same java class in which you \t\thave declared your native function in java. For an example, see the Wikipedia \t\t\tarticle referenced above<\/a>. \t<\/p>\n \t\tIf you want your program to deal with the case the library cannot be \t\tloaded, embed the \t\tSystem.loadLibrary<\/code> \t\tcall in a \t\ttry\/catch<\/code> \t\tblock. (The alternative approach that I followed, was to package the \t\tdll together with the Java class files and deal with all problems \t\trelated to this packaging \u2013 including with the possibility that the \t\tnative library cannot be loaded \u2013 manually during debugging.) \t<\/p>\nJNI unsatisfied link error<\/span><\/h2>\n \t\tStill, as I tried to run my program, I got a exception of the type \t\tjava.lang.UnsatisfiedLinkError<\/code> \t\t. \t<\/p>\nIt was thrown on the line on which I called my native function; \t\tJava could not find it.<\/p>\n
\t\tI found some good \t\t\tadvice on the net<\/a>; I followed it and installed dumpbin on my Windows \t\tcomputer, see here<\/a> for \t\tdetails. (The alternative approach is to use \t\t\tpexports utility of MinGW<\/a>.) \t<\/p>\n \t\tI ran
\t\t dumpbin \/exports MyDLLname.dll<\/code> \t\t
(according to the description of dumbin) and found that \t\t@8<\/code> \t\twas added to the name of my exported function, which prevented it from \t\tbeing found. \t<\/p>\n \t\tAs I studied it further, I found out the following.
The C\/C++ \t\theader file that was created by javah (see above), defined my function \t\twith \t\tJNICALL<\/code> \t\t(see an example in the Wikipedia \t\t\tarticle<\/a>). As I looked for the definition of \t\tJNICALL<\/code> \t\t, I found it in the header file \t\tjni_md.h<\/code> \t\twhich is \t\tinclude<\/code> \t\t‘d in the header file \t\tjni.h<\/code> \t\t(both mentioned above). The header \t\tjni_md.h<\/code> \t\tdefines \t\tJNICALL<\/code> \t\tas \t\t__stdcall<\/code> \t\t. This is a calling \t\t\tconvention<\/a> and according to \t\t\tMicrosoft documentation<\/a> \t\t __stdcall<\/code> \t\tprefixes an underscore _ to the name and suffixes it with @ followed \t\tby the decimal number of bytes in the argument list. \t<\/p>\n \t\tSo the conclusion is that \t\t@8<\/code> \t\tis correct (8 being the number of bytes in the two arguments) but the \t\tleading underscore was missing. \t<\/p>\n