JNI : Java Glossary

Introduction

You can’t directly manipulate or create C++ objects from Java. You need to write native method implementation code in C++ to allow java objects and methods to indirectly create and manipulate the C++ objects. Your C++ code has to do the C++ object creating and manipulating based on clues passed from Java by native methods and parameters.

The Overall Process

1. If you need to use JNI from an Applet, order a certificate well in advance. See Signed Applet.
2. Put all your classes is a package. Package-less classes are just for tiny toy programs.
3. Write a Java class containing a native method something like this Glue.java:
4. Compile Glue.java with javac.exe in the usual way. This step is very important. You must have a clean compile before using javah.exe.
5. Generate the Glue.h header file containing the prototypes of the C/C++ methods you must write with:

   javah.exe -jni -o Glue.h com.mindprod.JNIExper.Glue

6. Write a C or C++ class something like this Glue.c using the code in glue.h as a template.
7. Link that C code and any assembler code it calls into a DLL. The dll may contain methods from many different classes.
8. Pre-install the DLL on the java.library.path i.e. on the browser’s classpath or path. e.g. J:\Program Files\java\jdk1.6.0_10\jre\bin\ext (for the JDK 1.6.0 plug-in), WINNT\java\trustlib (for Internet Explorer), Program Files\Netscape\Communicator\java\classes (for Netscape 8.0).
9. You can’t change DLLs to a new version without rebooting, not even the disk copy, let alone the RAM image. Java can change code on the fly without so much as stopping the program. Surely Microsoft could work out a method to change a DLL that did not require such drastic measures. Some Unix machines run for years without rebooting. To replace a DLL with a new one, you must use the inuse utility to allow you to replace the DLL and then reboot to clear the in-RAM copy.

   inuse test.dll C:\winnt\system32\test.dll /y

   Alternatively, you can reboot, and then replace the DLL, so long at it is not loaded.
10. Alternatively, you can install the DLL to a temporary file in any random directory the browser uses as the current directory. You have to install it afresh on every run. The problem is, because it is a DLL, you can’t delete it until the next reboot. File.delete() and File.deleteOnExit() will fail. There is no such thing as File.deleteOnReboot(), so I suggest using HunkIO. createTempFile which generates filenames that will be more easily recognized as junk and discarded later by some disk cleaner, or by your own program on a subsequent run.
11. Use the Java native method as if it were an ordinary Java method.
12. Normally, Java calls C/C++, but you can do the reverse. Normally you just pass primitives back and forth. On the C++ side, you can create a Java object with the JNI API and populate its fields and return it, most commonly a String. You can also create C++ objects and use them on the C++ side. They mean nothing on the Java side so you can’t bring them over into Java without converting them to Java objects first. Similarly, you can’t create arbitrary C++ objects from the Java side.

Some general JNI tips

• See if you can avoid JNI altogether. Let your Java talk to your native code via TCP/IP.
• JNI and web-loaded Applets are incompatible, even if you sign them or jump through incredible hoops. You must use a Signed Applet to install an second signed one on the client’s local hard disk, and then use that second Applet to do your JNI work. Even then loadLibrary is unreliable.
• A JNI call is very slow, in the order of .5 to 1.0 microseconds, the equivalent of pages of linear Java code to do a simple method call. You would think there would be a tiny generated machine code thunk to bridge between Java and C. Not so — at least in any JVM I know of, Java branches to some general purpose code that interpretively constructs the C parameters. This code is not highly optimised. It seems Sun wants to strongly discourage you from using native methods just for speed. This means you don’t want to hop back and forth between Java and C, but rather to go to C, and stay there a decently long time before returning. This means that you can’t use C to speed up short operations, only long ones, because of the overhead tacked on in getting to C wipes out any savings.
• Keep your JNI interface as minimal as possible. This is tricky, messy, kludgy stuff. Do as little native code as possible. Confine it to as few classes as possible.
• Get your native code working first in an application before you tackle the complexities of signed Applets and capabilities and permissions. With applications you can control the loadlibrary path with:
  java -Djava.library.path=. HelloWorld.
  With Applets, you are at the mercy of the browser.
• If you do your native code in C++, there is slightly more type checking. Watch out, you use env-> in C++ rather than (*env)-> you would use in C. Keep aware in C++ when the first argument is hidden.
• When you compile, set the Options/Project/Directory include path to: J:\Program Files\java\jdk1.6.0_10\include\win32, or equivalent. Note that JNIEXPORT defined in win32\jni_md.h. For Borland, make sure target expert says: DLL, Win32 console, static and Project/Options/Linker/General is no debug, otherwise you will generate enormous DLLs.
• None of the Java safety net is operational when your native code is running. Keep in mind the tiniest error in your JNI code will crash the JVM. In JDK 1.2 there is a debug mode that does extra parameter checking invoked with -Xcheck:jni. Build your code incrementally, testing thoroughly before adding a few more lines.
• Check the return status of every call. There is no exception mechanism to do it for you.
• Make sure you understand global and local references, and include the necessary DeleteLocalRef and DeleteGlobalRefs. When you return an Object, you only need to pass back a local reference. If you want to retain a long-term reference to the Object for yourself, that lives after your method returns, then you need to convert it to a global reference. Local references are automatically deleted when your method returns. You must eventually delete global references explicitly. You may optionally delete local references prematurely. Similarly, you must explicitly use ReleaseStringUTFChars to free the C-style string created from a Java Unicode string that you allocated with GetStringUTFChars. If you fail to release, your code will run for a while, then eventually die of the memory leak. These can be a bear to track down. Code carefully and deal with the release the instant you write the code for the allocate.
• Be careful with GetIntArrayRegion and GetIntArrayElements and modifying the C-array you get. Since GetIntArrayRegion gives you a copy, any changes you make will not affect the Java array. GetIntArrayElements effectively gives you a direct pointer to the Java array so any changes you make to the C array are reflected in the Java array. However, there is a slight catch. GetIntArrayElements may be implemented two ways:
  • Giving you a direct pointer to the Java array. In that case, any changes you make are instantly reflected in the Java array. This technique is used when the garbage collector supports pinning — freezing the Java array at a fixed location, even through a gc cycle.
  • Giving you a copy of the Java array. In that case, any changes you make are not reflected until you call ReleaseIntArrayElements, when your C array is automatically copied back into the Java array. This technique is used when the garbage collector does not support pinning and there would be no way to freeze the Java array at a fixed location where C expects it.
• AllocObject does not invoke the constructors. It is up to you to initialise all the fields. Normally you would use NewObject.
• When debugging DLLs, remember the client must sometimes have to reboot to force Windows or NT to reload the new version of the DLL. DLL hell strikes again. Why must Microsoft fool around with dancing paperclips instead of fixing this? One way around the problem is to keep changing the name of your DLL.
• When you are debugging, display the code and DLL version number on the screen so that you can detect if you are inadvertently using an old version of your Applet stuck in cache, or an old version of a DLL.
• If you have a class file twice on the classpath you will get a misleading error: java.lang.ClassFormatError: Class already loaded. It has nothing to do with the DLL already being loaded. Thankfully, having a DLL still loaded from the last time you ran is not considered an error.
• It is also probably a good idea to give your class containing the native method, your C code, and the DLL distinct names.
• When you do your javah -jni com.mindprod.mypackage.MyClass, make sure you use dots in the name, not slashes.
• When you do your javah -jni com.mindprod.mypackage.MyClass, make sure you have freshly compiled it first. It works from the *.class file, not the *.java file.
• ListDLLs is a useful tool to find out which NT DLLs are currently loaded.
• Don’t use thread local storage (a Microsoft C++ feature) with any DLLs that you let the JVM load. TLS doesn’t work if the library is loaded with loadLibrary.
• I’m told you don’t have to buy an expensive C/C++ compiler to do your JNI work. The Gnu/Cygnus shell and C++ compiler is available free for many platforms.
• Though you can work in either C or C++, you always use extern 'C' so that C-style parameter pushing order is always used.
• Before you write your own JNI native class, check out JConfig. It may already be done.
• If you have a dual CPUs, JNI can be even more tricky. It has not yet been properly tested in that configuration.
• If you are using a 64-bit JVM, you will need to compile 64-bit C++ JNI. If you are using a 32-bit JVM, you will need to compile 32-bit C++ JNI.

C/C++ Primitive Types

JNI Manipulator Functions

Typical JNI C Code

Typical JNI C++ Code

JNI and Assembler

• Use Microsoft Visual C++ inline assembler.
• Use a traditional external 32-bit assembler, and create a little C glue code.

Here is a sample using inline Assembler. Leaving a value in eax without a ret is how you return a value, even though it generates a compiler warning message.

• Using assembler or in-line assembler can massively shrink your DLL files. So often in C, one tiny function brings in all kinds of library code.
• If you work in assembler, you can get a rough prototype in ASM to work with by writing a dummy version in C, and getting the compiler to generate ASM source. In Borland you do this with Project ⇒ right click on *.c file ⇒ Special ⇒ C->ASM.
• Test your actual ASM code with a test C driver. Once you get that working, try putting it in a DLL. After that is working, attempt calling it from Java.
• Beware! assemblers may only handle 8.3 source names, and may truncate public symbols or convert them to upper case. It gets pretty strange. Java, C, C++ and MASM each have their own idea of what the symbol names are. Unless you specify to the C++ compiler that symbols are extern 'C', it will decorate them with method signatures. Sometimes symbols get a leading _. You can guess these symbols from MAPs, error messages, and looking at hex dumps of object files. I found it easiest to call a C wrapper method with the official Java name which in turn calls an ordinary assembler routine with a short name, all uppercase.
• In theory, with a smart linker, you should be able to alias the short name to the long one and avoid the C wrapper method. With the wrapper method, you don’t need the JNIEXPORT on your MASM prototype, since the JNI interface never sees it. E.g. jint JNICALL NATIVE1(JNIEnv *env, jclass thisClass, jint n);
• Make sure you are explicit about JNICALL on your MASM prototype which means the called routine is responsible for popping the parms with a ret n.
• Borland inline assembler does not work in the C compiler in 32-bit mode unless you buy the separate TASM product.
• You can’t access the familiar 16-bit DOS int 21h functions, from a 32-bit flat app.
• The method signature strings that GetMethodID wants can be had from running javap -s -p on your compiled Java class files.

JNI Example Code

Using JNI in Applets

Using native methods in a Netscape Applet is a bear because even after you manage to defang the security manager with:

PrivilegeManager.enablePrivilege( "UniversalLinkAccess" );

I got word from Hannu Helminen that it is possible after all. He came across this JavaWorld Article. What is says basically that Netscape and native code do work together after all. He tried it out, and to his amazement the example indeed works! But hey, he did the same things that I did, where is the catch?

The idea is that first you download the native DLL and a class file to user’s local hard drive. The class file has to be in the Netscape class path, thus it uses the system class loader. Also the DLL has to be downloaded and System. loaded before the class is referenced for the first time. It appears that Netscape does some kind of checking for the DLLs already when the class is loaded. I have not yet had time to check this out myself.

To make it worse, there are fourteen security bypassing schemes you have to deal with.

System.load vs System.loadLibrary

// display where loadLibrary is looking for native code
System.out.println ( System.getProperty( "java.library.path" ) );

// Discovering the path where native code goes for an application.
// Most browsers do NOT support this, except Opera.
String lib = System.getProperty( "java.library.path" );

• The Windows system directories.
• The current working directory.
• The entries is the PATH (not CLASSPATH) set environment variable.
• and sometimes, at least in Java Web Start, the root directory of your jar. DLLs must be added to jars without the package name path.

Windows loadLibrary

Solaris and Linux loadLibrary

gcc -fPIC -D_REENTRANT  -I $JAVA_HOME/include  -I $JAVA_HOME/include/linux  -c Glue.c

gcc -shared Glue.o  -o libglue.so

Mac

File Naming Conventions

Exceptions

Threads

• The JNIEnv pointer is valid only for the thread associated with it. Don’t pass it around.
• Local references are only valid in the thread that created them.
• You can convert a local reference to global reference to share it.
• You have the same sorts of synchronised problems in JNI you do in regular Java, it is just you deal with them with MonitorEnter and MonitorExit. For those who like to line dangerously, it is also possible to use the native thread mechanisms.

Reflection

// Java reflection
Class theClass = Class.forName( "java.lang.Long" );
Constructor constructorList[] = theClass.getConstructors();

// equivalent C JNI reflection
Class theClass = Class.forName( "java.lang.Long" );

jclass theClass = (*env)->FindClass( env, "java/lang/Long" );

jclass classClass = (*env)->GetObjectClass( env, theClass );

jmethodID mid = (*env)->GetMethodID( env, classClass, "getConstructors",
                                     "()[Ljava/lang/reflect/Constructor;" );

jarray constructorList = (jarray)(*env)->CallObjectMethod( env, theClass, mid );

The Old Netscape Problem

The Old Netscape Solution

I have fooled around with this over a period of six months, chasing wild goose after wild goose, and have finally came to the conclusion, in agreement with Sun’s FAQ, that JNI and Applets simply don’t mix. There is simply no way to get sufficient security clearance to let you directly access the DLL from a web-loaded Applet, even if you write a custom ClassLoader. One problem with doing so many tests is I could have slipped somewhere along the line, thinking I tested two cases, when I actually tested only one. The problem is the way Windows/Netscape hold onto the old code. I have not even got the method I describe below to work. It may fail too. Netscape security may apply even if you load from local hard disk.

What you have to do is use a small signed installer Applet to install a second unsigned Worker Applet on the client’s local hard disk. When that second Worker Applet runs, it is totally free of security restrictions, and so can access JNI DLLs. It behaves much like an application, except it runs under a browser.

You also have to install some html in that same local directory that will load the Worker Applet from the local hard disk. It would have CODE and ARCHIVE parameters, but no CODEBASE. It defaults to the local hard disk directory where the html file lives.

You have to install the DLL in F:\Program Files\Netscape\Communicator\program\java\bin, which is guaranteed to be on Netscape’s Windows path, where Windows looks for DLLs.

You have to install the unsigned Worker jar file in F:\Program Files\Netscape\Communicator\program\java\classes. Netscape totally trusts classes it loads from the local file system, even if they are not signed and have no capabilities calls.

The Old Netscape Recipe

In order to execute JNI methods from a Netscape Applet, create three jar files.

1. installer.jar. When this signed jar is first executed, it installs the various files on the client’s local hard disk, (intelligently choosing C: or D:). On subsequent executions, it notices the needed files are already installed and up-to-date and avoids that step. As soon as it has ensured it has installed the files, it uses getAppletContext().showDocument(url) to transfer control to the HTML it has downloaded on C: or D: The installer jar contains only the tools such as FileTransfer classes for help in downloading and installing the files. It does not contain any of the data to be installed. Keeping that out of installer.jar saves transferring that bulk when it is already installed.
2. Worker.jar is for your class files that contain native methods, and the other classes you need to run the actual Applet. This jar should not be signed. If you sign it, it will slow class loading the code down. The Worker.jar will be embedded inside the toInstall jar, described shortly. The installer Applet will copy the Worker.jar to F:\Program Files\Netscape\Communicator\program\java\classes or perhaps D:. Thereafter, you could run it standalone via a bookmark, or you could run it via the original install.jar. The advantage of using the original install.jar is automatic updates, and automatic finding where the Worker.jar Applet is installed. The disadvantage is extra startup time and an extra annoying grant to run the program each time.
3. toInstall.jar. This unsigned jar is just a container for the various files you need to download namely:
   • An HTML file to invoke the actual Applet. Your installer Applet will install it in: F:\Program Files\Netscape\Communicator\program\java\classes, or perhaps D:.
   • Your DLL file containing the native C++/C/Assembler code. Your installer Applet will install it in F:\Program Files\Netscape\Communicator\program\java\bin, or perhaps D:.
   • Your worker Applet jar containing all the class files you will need to run the unsigned Applet. Your installer Applet will install it in F:\Program Files\Netscape\Communicator\program\java\classes or perhaps D:.

   If you use getResourceAsStream, you must use the goofy extension *.ram for resources inside your jar files because Netscape interferes with the extensions DLL, EXE, CLASS etc. If you access them via ZipFile that kludge is not necessary.

Strategy

Alternatives

• Spawn a C++ progam with the exec mechanism.
• Use a JNI library, or JNI generator written by someone else.
• Exchange data via data files, perhaps big or little-endian binary, or XML.
• Exchange data via an SQL database.
• Exchange data via a TCP/IP socket.

Books

	recommend book⇒The Java Native Interface, Programmer’s Guide and Specification
		paperback
	ISBN13:	978-0-201-32577-5
	ISBN10:	0-201-32577-2
	publisher:	Prentice Hall
	published:	1999-06-20
	by:	Sheng Liang
Sun Microsystems. Does not cover Applet signing, or "obvious" JNI like accessing int parms, but he does explain many fine points well. A slim, indispensible, expensive book. The specification itself is bundled as part of the JDK docs. Part of the book is available free online.
abe books.co.uk abe books.ca amazon.co.uk amazon.ca abe books.de chapters.indigo.ca amazon.de abe books.com abe books.fr amazon.com amazon.fr barnes and noble.com abe books.it powells.com iberlibro.com abe books anz

	recommend book⇒Essential JNI, Java Native Interface
		paperback
	ISBN13:	978-0-13-679895-8
	ISBN10:	0-13-679895-0
	publisher:	Prentice Hall
	published:	1998-03
	by:	Rob Gordon and Alan
This book is aimed more at the beginner than Liang’s book. It can’t very well teach you C and Java and JNI in one book, but it does not make quite so many assumptions about what you already know.
abe books.co.uk abe books.ca amazon.co.uk amazon.ca abe books.de chapters.indigo.ca amazon.de abe books.com abe books.fr amazon.com amazon.fr barnes and noble.com abe books.it powells.com iberlibro.com abe books anz

Learning More