Java 2 SDK for Solaris Developer's Guide

Java Native Interface (JNI)

Making the Transition From NMI to JNI

NMI is not supported in Java 2 SDK for Solaris software. In some installations, NMI is known as JNI 1.0, and JNI as JNI 1.1.

Note -

Any application containing native methods is platform dependent and not Write Once Run Anywhere^TM. This is true regardless of whether NMI or JNI is used. Applets cannot be affected by a change in native method support.

Porting

Porting applications that use NMI to ones that use JNI interfaces is straightforward. For example, an engineer who was unfamiliar with the application ported 6000 lines of C code in approximately two days. In this instance, NMI was only lightly used, but the uses were widely distributed.

`javah`

The javah command generates C header and source files that are needed to implement native methods. C programs use the generated header and source files to reference instance variables of an object from native source code. JNI does not require header information or stub files. You can still use the javah command with the jni option to generate native method function prototypes needed for JNI-style native methods. The result is placed in the .h file.

In JDK 1.1 default mode, the javah command generates NMI output.

Because the NMI interfaces are completely incompatible with the Java 2 SDK for Solaris implementation, Java 2 SDK for Solaris does not support the production of NMI-style output by way of the -old flag. Rather the -old flag is parsed and, if it is found, an -old not supported message occurs and javah exits.

General JNI Issues

Compiler Restrictions

Certain optimizations that might be performed by compilers compiling native methods can cause the VM to fail. The VM relies on the ability to examine the stack frames of functions on a thread's stack. Therefore, the code for native functions must always create stack frames as specified in the system calling conventions for non-leaf functions. Additionally, the frame pointer register must always point to a valid stack frame.

On the Intel (IA) platform, the Sun Workshop^TM C compiler can generate code that violates this requirement at optimization levels -xO4 and -xO5. You should not use an optimization level above -xO3.
On the SPARC platform, all optimization levels are safe. If you are using another compiler, check its documentation to ensure that it produces code that meets this requirement.

Note -

A native method that violates this restriction can cause the VM to abort randomly.

Linking Native Solaris Applications

You should link native Solaris applications with -lthread. Not doing so can cause incorrect behavior.

You must specify the libthread.so library (-lthread option) before the libc.so library (-lc option) when linking up native applications that use JNI. The Sun C compiler option -mt automatically adds the -lthread option, and the -lc option is typically not specified (it defaults to the end of the list). So when using Sun compilers or the Sun linker, you must supply either the -mt or the -lthread options.

Fast JNI Array Access

You can get faster JNI array access with this JDK by using jni_GetPrimitiveArrayCritical() and jni_ReleasePrimitiveArrayCritical() instead of Get*ArrayElements() calls.

Code that uses these *Critical() operations must comply with certain restrictions:
You must release the array elements quickly after you get them.
You cannot call back into Java while holding onto the array elements.
You cannot call other JNI operations.

Because of these restrictions, the array elements can be accessed without pinning and without copying. For more information, see:

http://java.sun.com/products/jdk/1.2/docs/guide/jni/jni-12.html

Locating Shared Libraries

If you are using Solaris 2.5.1 or 2.6 operating environment and you have installed the JDK in any location other than the default location (/usr/java1.2), JNI native applications might have problems locating the JDK shared libraries. You can work around this problem by setting the environment variable LD_LIBRARY_PATH to include the jre/lib/sparc or jre/lib/i386 directory of the JDK installation. This problem does not exist on either Solaris 7 software or Solaris 8 software.

Signal Processing State

Native code using JNI should not modify the signal-processing state. The VM uses signals and any change to the signal handling can result in VM failures.