jni

the picture

with FFM, java learned to speak C. with JNI, you hire a translator who lives in C: a small layer of C functions with very particular names, written by you, compiled by you, for every operating system and CPU you ship to. the translator can talk back to the JVM through a phone book of about 230 functions (JNIEnv): "give me this string's characters", "make a new array", "call this java method", "throw this exception".

the whole round trip

here's a real JNI library built from scratch on a mac: a native int add(int, int) and a native String greet(String).

public class Greeter {    static {        System.loadLibrary("greeter");    }    static native int add(int a, int b);    static native String greet(String name);     public static void main(String[] args) {        System.out.println(add(40, 2));        System.out.println(greet("ada"));    }}

a few things to notice in there:

• the names are the contract. Java_Greeter_add is found by name when the method is first called (or registered explicitly with RegisterNatives). rename the class or move it to a package and the C function name must change too, which is why you regenerate the header.
• primitives cross for free, objects don't. jint is just an int. a jstring is an opaque handle; C has to ask the JVM for a copy of the characters and give it back.
• the library is per platform. libgreeter.dylib on macOS, libgreeter.so on linux, greeter.dll on windows, each built separately, often for two CPU architectures each. libraries like sqlite-jdbc or netty's native transports ship a dozen binaries inside the jar and pick one at runtime.

crossing the boundary

what actually happens when java calls add(40, 2):

that's the overhead: not the C code (an add is one instruction), but the bookkeeping around it. measured with JMH, calling the same add from the same library:

why it's being fenced in

JNI code runs in the same process as the JVM with no checks at all. a native library can read or write any memory, corrupt the heap, or crash the whole JVM (you get an hs_err_pid<n>.log and the process is gone). and until java 24, any library on the class path could do that silently: a dependency of a dependency could load native code without anyone in the application deciding it should.

JEP 472 (java 24) makes native access an explicit decision, the same way strong encapsulation made deep reflection one (reflection):

and since java 24 there's a tool to find out who needs it before you flip the switch, jnativescan:

$ jnativescan --class-path greeter.jar
greeter.jar (ALL-UNNAMED):
  Greeter:
    Greeter::add(int,int)int is a native method declaration
    Greeter::greet(String)String is a native method declaration
    Greeter::<clinit>()void references restricted methods:
      java.lang.System::loadLibrary(String)void

run it over your application's class path and you get the list of jars that do native things, which is the list of modules to name in --enable-native-access.