Editing Java Native Interface (section)

== Design ==
In the JNI framework, native functions are implemented in separate .c or .cpp files. (C++ provides a slightly simpler interface with JNI.) When the JVM invokes the function, it passes a <code>JNIEnv</code> pointer, a <code>jobject</code> pointer, and any Java arguments declared by the Java method. For example, the following converts a Java string to a native string:

<syntaxhighlight lang="cpp">
extern "C"
JNIEXPORT void JNICALL Java_ClassName_MethodName
  (JNIEnv *env, jobject obj, jstring javaString)
{
    const char *nativeString = env->GetStringUTFChars(javaString, 0);

    //Do something with the nativeString

    env->ReleaseStringUTFChars(javaString, nativeString);
}
</syntaxhighlight>

The ''<code>env</code>'' pointer is a structure that contains the interface to the JVM. It includes all of the functions necessary to interact with the JVM and to work with Java objects. Example JNI functions are converting native arrays to/from Java arrays, converting native strings to/from Java strings, instantiating objects, throwing exceptions, etc. Basically, anything that Java code can do can be done using <code>JNIEnv</code>, albeit with considerably less ease.

The argument ''<code>obj</code>'' is a reference to the Java object inside which this native method has been declared.

Native [[data type]]s can be mapped to/from Java data types. For compound types such as objects, [[Array data structure|arrays]] and [[string (computer science)|string]]s the native code must explicitly convert the data by calling methods in the <code>JNIEnv</code>.

A JNI environment pointer ({{mono|JNIEnv*}}) is passed as an argument for each native function mapped to a Java method, allowing for interaction with the JNI environment within the native method. This JNI interface pointer can be stored, but remains valid only in the current thread. Other threads must first call {{mono|AttachCurrentThread()}} to attach themselves to the VM and obtain a JNI interface pointer. Once attached, a native thread works like a regular Java thread running within a native method. The native thread remains attached to the VM until it calls {{mono|DetachCurrentThread()}} to detach itself.<ref>The Invocation API. Sun Microsystems. https://docs.oracle.com/en/java/javase/11/docs/specs/jni/invocation.html</ref>

The JNI framework does not provide any automatic garbage collection for non-JVM memory resources allocated by code executing on the native side. Consequently, native side code (such as assembly language) assumes the responsibility for explicitly releasing any such memory resources that the native code acquires.

On Linux and Solaris platforms, if the native code registers itself as a signal handler, it could intercept signals intended for the JVM. A [[Chain-of-responsibility pattern|chain of responsibility]] can be used to allow native code to better inter-operate with the JVM. On Windows platforms, [[Microsoft-specific exception handling mechanisms#Structured Exception Handling|Structured Exception Handling (SEH)]] may be employed to wrap native code in SEH try/catch blocks so as to capture machine (CPU/FPU) generated software interrupts (such as NULL pointer access violations and divide-by-zero operations), and to handle these situations before the interrupt is propagated back up into the JVM (i.e. Java side code), in all likelihood resulting in an unhandled exception.{{original research inline|date=February 2017}}

The encoding used for the NewStringUTF, GetStringUTFLength, GetStringUTFChars, ReleaseStringUTFChars and GetStringUTFRegion functions is "modified UTF-8",<ref name="jniModifiedUtf">{{cite web|url=http://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/types.html#wp16542|title=JNI Types and Data Structures}}</ref> which is not valid UTF-8 for all inputs, but a different encoding really. The null character (U+0000) and codepoints not on the [[Plane (Unicode)#Basic Multilingual Plane|Basic Multilingual Plane]] (greater than or equal to U+10000, i.e. those represented as ''surrogate pairs'' in UTF-16) are encoded differently in modified UTF-8. Many programs actually use these functions incorrectly and treat the UTF-8 strings returned or passed into the functions as standard UTF-8 strings instead of modified UTF-8 strings. Programs should use the NewString, GetStringLength, GetStringChars, ReleaseStringChars, GetStringRegion, GetStringCritical and ReleaseStringCritical functions, which use UTF-16LE encoding on little-endian architectures and UTF-16BE on big-endian architectures, and then use a UTF-16 to UTF-8 conversion routine.{{original research inline|date=February 2017}}