Java Native Interface

This article has multiple issues. Please help improve it or discuss these issues on the talk page. (Learn how and when to remove these messages) This article needs more citations. Please help improve this article by adding citations to reliable sources. Unsourced material may be challenged and removed. Find sources: "Java Native Interface" – news · newspapers · books · scholar · JSTOR (February 2017) (Learn how and when to remove this message) This article's lead section may be too short to adequately summarize the key points. Please consider expanding the lead to provide an accessible overview of all important aspects of the article. (February 2017) (Learn how and when to remove this message) (Learn how and when to remove this message)

The Java Native Interface (or Native Method Interface) is a foreign function interface designed for non-Java programming frameworks. The JNI enables Java code to call and be called by native code (i.e. any code using the JNIEnv and interfacing through the C application binary interface), native applications (programs specific to a hardware and operating system platform) and libraries written in other languages such as C, C++ and assembly.^[1][2][3]

Java 22 introduces the Foreign Function and Memory API, which can be seen as the successor to Java Native Interface.^[4][5]

Objectives

JNI allows native methods to allow for applications to make calls outside of the Java platform, e.g. when the standard Java class library does not support platform-specific features or a certain program library. It is also used to modify an existing application (written in another programming language) to be accessible to Java applications. Many standard library classes depend on JNI to provide functionality to the developer and the user, such as file I/O and audio APIs. Only applications and signed applets may invoke JNI.

The JNI framework allows native code to manipulate and consume Java objects. A native method (marked by the keyword native in Java) can create Java objects and inspect and use these objects to perform its tasks. A native method can also inspect and use objects created by Java application code.

An application that relies on JNI loses the platform portability Java offers (a partial workaround is to write a separate implementation of JNI code for each platform and have Java detect the operating system and load the correct one at runtime).

Not only can native code interface with Java, it can also draw on a Java Canvas, which is possible with the Java AWT Native Interface, available since J2SE 1.3.

JNI also allows direct access to assembly, without a C bridge.^[6] Accessing Java applications from assembly is possible in the same way.^[7]

The JNI is the entry point between languages used to begin the JVM startup.^{[8][9][10][11]}

Mapping types

Java types are the default primitive types available on Java, while JVM type signatures are identifiers used by the JVM to identify the type matching on Java, while native types are types defined by the JNI itself to map to native types. For primitives, the following typedefs are provided:^[12]

In addition, the JVM type signature Lfully-qualified-class; refers the class uniquely specified by that name, for example the signature Ljava.lang.String; (Ljava/lang/String; in class files) refers to the class java.lang.String. Prefixing [ to the signature denotes an array of that type; for example, [I refers to int[], and [[I refers to int[][], up to a maximum of 255 dimensions.

These types are interchangeable. One can use jint where you normally use an int, and vice versa, without any typecasting required. However, mapping between Java strings and arrays to native strings and arrays is different; for instance, jstring and char* are not interchangeable types, nor are jintArray and int[].

JNI additionally contains the following declarations for Java reference types in <jni.h>:^[13]

#ifdef __cplusplus
class _jobject {};
class _jclass : public _jobject {};
// ...
typedef _jobject *jobject;
typedef _jclass *jclass;
// ...
#else
struct _jobject;
// ...
typedef struct _jobject *jobject;
typedef jobject jclass;
// ...
#endif

Here, all Java reference types are defined as opaque empty types which act as handles to Java objects. These types should not be dereferenced.^[14]

Additionally, the following opaque types are used as handles:

Note however that jfieldID and jmethodID are just opaque handles, and do not correspond to java.lang.reflect.Field/java.lang.reflect.Method.

Design

The communication between native code and Java code is intermediated by the JNI, acting as an ABI.

// jni.h file

struct JNINativeInterface_;
struct JNIEnv_;

#ifdef __cplusplus
typedef JNIEnv_ JNIEnv;
#else
typedef const struct JNINativeInterface_ *JNIEnv;
#endif

JNIEnv is used to access the structure of functions (array of function pointers), and each function being identifiable by a unique pointer.^[15] According to the programming language, C or C++, the implementation can be a little different.^[16] For example, in C:

// jni.h file

struct JNINativeInterface_ {

    jint (JNICALL *GetVersion) // JNICALL declaration of a pointer to identify the specific function;
       (JNIEnv *env); // Parameter env is a pointer to the JNIEnv pointer, the pointer-to-pointer;

    jclass (JNICALL *DefineClass)
      (JNIEnv *env, const char *name);

    jclass (JNICALL *FindClass)
      (JNIEnv *env, const char *name);

    // Others functions pointers...
}

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);
}

}

#include <stdio.h>
#include <jni.h>

JNIEXPORT void JNICALL Java_HelloJNI_sayHello(JNIEnv* env, jobject obj) {
    printf("Hello from C!\n");
}

public class HelloJNI {
    static {
        // "hello" refers to libhello.so on Linux
        System.loadLibrary("hello"); // System.load() is other way to load a library.
    }

    public native void sayHello();

    public static void main(String[] args) {
        new HelloJNI().sayHello();
    }
}

Performance

JNI incurs considerable overhead and performance loss under certain circumstances:^[19]

• Function calls to JNI methods are expensive, especially when repeatedly calling a method.
• Native methods are not inlined by the JVM, nor can the method be JIT compiled, as the method is already compiled.
• A Java array may be copied for access in native code, and later copied back. The cost is linear in the size of the array.
• If the method is passed an object, or needs to make a callback, then the native method will likely be making its own calls to the JVM. Accessing Java fields, methods and types from native code invokes Java reflection. Signatures are specified in strings and queried from the JVM. This is both slow and error-prone.
• Java strings are objects and have length and are encoded. Accessing or creating a string may require an ${\displaystyle O(n)}$ copy.

Foreign Function and Memory API

Java 22 introduced the Foreign Function and Memory API, located in java.lang.foreign which can be seen as a sort of successor to the Java Native Interface.^[20] It has a simpler interface and generally requires less boilerplate than JNI, due to no longer requiring the inclusion of <jni.h> in the foreign library to invoke, and Foreign Function and Memory API abstracts away the usage of the native keyword completely. It supports region-based memory management. The class java.lang.foreign.MemorySegment models a contiguous segment of memory which can lie inside or outside the JVM heap, and a java.lang.foreign.MemorySegment is allocated using a java.lang.foreign.Arena which controls the lifetime of the region of memory backing its allocated segment of memory.

The java.lang.foreign.Arena offers the following arena kinds:^[21]

package org.wikipedia.examples;

import java.lang.foreign.Arena;
import java.lang.foreign.MemorySegment;
import java.lang.foreign.ValueLayout;

public class ForeignMemoryExample {
    public static void main(String[] args) {
        try (Arena arena = Arena.ofConfined()) {
            MemorySegment segment = arena.allocate(5 * Double.BYTES);
            
            for (int i = 0; i < 5; ++i) {
                segment.setAtIndex(ValueLayout.JAVA_DOUBLE, i, i * 1.1);
            }

            for (int i = 0; i < 5; ++i) {
                double value = segment.getAtIndex(ValueLayout.JAVA_DOUBLE, i);
                System.out.printf("Value at index %d: %d%n", i, value);
            }
        }
    }
}

In a sense, Java Foreign Function and Memory API allows for direct memory allocation outside the JVM heap (i.e. the operating system heap), through Arena.allocate() and MemorySegment.allocateNative() which allocate raw memory directly, while Arena.close() and MemorySegment.close() are used to deallocate/release the memory segment.

As a foreign function interface, the classes java.lang.foreign.Linker is offered for accessing between foreign functions from Java (to and from), java.lang.foreign.SymbolLookup for retrieving the address of a symbol in a library, and java.lang.foreign.FunctionDescriptor for modelling a foreign function signature.

package org.wikipedia.examples;

import java.lang.foreign.Arena;
import java.lang.foreign.FunctionDescriptor;
import java.lang.foreign.Linker;
import java.lang.foreign.MemorySegment;
import java.lang.foreign.SymbolLookup;
import java.lang.foreign.ValueLayout;
import java.lang.invoke.MethodHandle;

public class ForeignFunctionExample {
    public static void main(String[] args) throws Throwable {
        Linker linker = Linker.nativeLinker();
        
        SymbolLookup stdlib = linker.defaultLookup();
        
        MethodHandle printf = linker.downcallHandle(
            stdlib.findOrThrow("printf"),
            FunctionDescriptor.of(ValueLayout.JAVA_INT, ValueLayout.ADDRESS)
        );

        MethodHandle strlen = linker.downcallHandle(
            stdlib.findOrThrow("strlen"),
            FunctionDescriptor.of(ValueLayout.JAVA_LONG, ValueLayout.ADDRESS)
        );

        try (Arena arena = Arena.ofConfined()) {
            MemorySegment formatString = arena.allocateUtf8String("Hello, %s!\n");
            MemorySegment argString = arena.allocateUtf8String("World");
            printf.invokeExact(formatString, argString); // prints "Hello, World!"
            long len = (long)strlen.invokeExact(formatString); // len = 5
        }
    }
}

Layouts are modelled by java.lang.foreign.ValueLayout, which consists of:

Primitives receive ValueLayout.JAVA_* layouts when mapped to their native types, while pointer types use ValueLayout.ADDRESS (for instance char*, int** or struct Point*).

Additionally, the constant MemorySegment.NULL (of type java.lang.foreign.MemorySegment) is a zero-length native segment representing a null address (nullptr), equivalent to MemorySegment.ofAddress(0).

Java offers additional methods to express more complicated native types. For instance, the following native types^[22]

struct Point {
    int x;
    long y;
};

union Choice {
    float a;
    int b;
};

receive the following layouts:

import java.lang.foreign.MemoryLayout;
import java.lang.foreign.StructLayout;
import java.lang.foreign.UnionLayout;

StructLayout pointLayout = MemoryLayout.structLayout(
    ValueLayout.JAVA_INT.withName("x"),
    MemoryLayout.paddingLayout(4),
    ValueLayout.JAVA_LONG.withName("y")
};

UnionLayout choiceLayout = MemoryLayout.unionLayout(
    ValueLayout.JAVA_FLOAT.withName("a"),
    ValueLayout.JAVA_INT.withName("b")
);

Alternatives

The Java Runtime Interface was created by Netscape as a precursor.^[23]

Microsoft's proprietary implementation of a Java Virtual Machine (Visual J++) had a similar mechanism for calling native code from Java, called the Raw Native Interface (RNI). In addition, it offered a simple way to call existing native code that was not itself aware of Java, such as (but not limited to) the Windows API, (J/Direct). However, following the Sun–Microsoft litigation about this implementation, Visual J++ ceased to be maintained. RNI was simpler to use than JNI, because no management of the Java environment pointer was needed; instead, all Java objects were accessed directly. To facilitate this, a tool was used to generate header files from Java classes. Similarly, J/Direct was easier to use than using the necessary intermediate native library and JNI.

Java Native Access (JNA) is a community-developed library that provides Java programmers easy access to native shared libraries without using JNI. However, this requires the redistribution of the dependent jar library. The tradeoff is between JNI being more complex and JNA being slower, and not built-in like JNI.^[24]

Historically, GCC (until GCC 7) offered the GNU Compiler for Java. This compiler offered the Compiled Native Interface (CNI), which allowed direct interoperability between C++ and Java. It provided an API that was heavily based on JNI itself.^[25] It claimed several advantages over JNI, as it represented Java classes directly as C++ classes.^[26]

Since Java 22, the Foreign Function and Memory API supersedes the JNI, due to its reduced boilerplate and simplified interface.^[20]

See also

• C++/CLI
• GIWS (software)
• GlueGen
• Java Access Bridge
• Java Debug Wire Protocol
• Java Native Access
• Java Virtual Machine Tools Interface
• GNU Compiler for Java
• libffi
• Platform Invocation Services
• Symbol table
• SWIG

References

Bibliography

External links

• Oracle's JNI 25.0 API Specification
• Java Native Interface: Programmer's Guide and Specification
• JNI in XCode from Apple
• Exception handling in JNI
• The Foreign Function and Memory API Tutorial