Calling C from Java with jextract and the FFM API: A Real Library, No JNI

Versions this was tested against. JDK: Temurin 25.0.5+8. FFM API: final since JDK 22 (JEP 454, status “Closed / Delivered”). jextract: openjdk-25-jextract+2-4, an early-access build dated 2025/11/25, the newest on jdk.java.net/jextract when I checked on 30 October 2026, with libclang 13.0.0. SQLite: 3.45.1 (Ubuntu libsqlite3-dev 3.45.1-1ubuntu2.8), so not the newest SQLite. JMH 1.37, gcc 13.3.0 for the JNI shim. Linux x64 only; I did not run anything on macOS or Windows. jextract is not part of the JDK and has no GA release — only early-access builds.

FFM is the JDK part, jextract is the typing saver

jextract is a separate download, not a JDK tool. You will not find it in $JAVA_HOME/bin. The OpenJDK jextract repository says its binaries are published at jdk.java.net/jextract and are built from the master branch, which tracks the latest mainline JDK (github.com/openjdk/jextract). Its own guide also says that, for now, jextract and FFM only support C headers — a C++ library needs a C wrapper header (jextract GUIDE.md). The generated code is not covered by the jextract licence, per the download page.

Generate the bindings: one command, four files

"$JEXTRACT" --output "$OUT" --target-package demo.sqlite --header-class-name sqlite3_h \
  -l sqlite3 "${args[@]}" "$SQLITE_H"

$ jextract --output <tmp> -t demo.sqlite.full -l sqlite3 /usr/include/sqlite3.h     # no filters: the whole header
warnings: 14
sqlite3.h:272:16: warning: Skipping sqlite3 (type Declared(sqlite3) is not supported)
sqlite3.h:4045:16: warning: Skipping sqlite3_stmt (type Declared(sqlite3_stmt) is not supported)
files: 83
lines: 44295
bytes: 1339454
lines in the one big header class: 22335

Opaque structs become plain MemorySegments. SQLite declares sqlite3 and sqlite3_stmt without a body, so jextract cannot generate a struct class for them. The unfiltered run says so (see the Skipping sqlite3 lines in the transcript above) and every sqlite3 * in the generated API shows up as a bare MemorySegment. That is fine — the pointer is only ever passed back to SQLite — but it means the compiler will not stop you passing a statement where a database belongs.

$ grep -o 'public static [A-Za-z.]* sqlite3_open[a-z_0-9$]*(' generated/demo/sqlite/sqlite3_h.java | sort -u
public static FunctionDescriptor sqlite3_open$descriptor(
public static FunctionDescriptor sqlite3_open_v2$descriptor(
public static MemorySegment sqlite3_open$address(
public static MemorySegment sqlite3_open_v2$address(
public static MethodHandle sqlite3_open$handle(
public static MethodHandle sqlite3_open_v2$handle(
public static int sqlite3_open(
public static int sqlite3_open_v2(

$ jextract -t demo.sqlite -l sqlitez --include-function sqlite3_libversion --header-class-name sqlite3_h /usr/include/sqlite3.h
static final SymbolLookup SYMBOL_LOOKUP = SymbolLookup.libraryLookup(System.mapLibraryName("sqlitez"), LIBRARY_ARENA)
$ java --enable-native-access=ALL-UNNAMED -cp <classes> V
Exception in thread "main" java.lang.ExceptionInInitializerError
	at V.main(V.java:6)
Caused by: java.lang.IllegalArgumentException: Cannot open library: libsqlitez.so
	at java.base/java.lang.foreign.SymbolLookup.libraryLookup(SymbolLookup.java:350)
	at java.base/java.lang.foreign.SymbolLookup.libraryLookup(SymbolLookup.java:301)

$ jextract -t demo.sqlite -l :libsqlite3.so.0 --include-function sqlite3_libversion --header-class-name sqlite3_h /usr/include/sqlite3.h
static final SymbolLookup SYMBOL_LOOKUP = SymbolLookup.libraryLookup("libsqlite3.so.0", LIBRARY_ARENA)
$ java --enable-native-access=ALL-UNNAMED -cp <classes> V
sqlite3_libversion() = 3.45.1

The first native call, and the warning you will see

    public static void main(String[] args) {
        MemorySegment v = sqlite3_libversion();              // const char* -> MemorySegment
        System.out.println("sqlite3_libversion()        = " + v.getString(0));
        System.out.println("returned segment byteSize   = " + v.byteSize());
        System.out.println("sqlite3_libversion_number() = " + sqlite3_libversion_number());
        System.out.println("sqlite3_sourceid()          = " + sqlite3_sourceid().getString(0));
    }
}

$ java --enable-native-access=ALL-UNNAMED -cp build/classes demo.Hello
sqlite3_libversion()        = 3.45.1
returned segment byteSize   = 9223372036854775807
sqlite3_libversion_number() = 3045001
sqlite3_sourceid()          = 2024-01-30 16:01:20 e876e51a0ed5c5b3126f52e532044363a014bc594cfefa87ffb5b82257ccalt1

$ java -cp build/classes demo.Hello          # no flag at all, JDK 25 default
WARNING: A restricted method in java.lang.foreign.AddressLayout has been called
WARNING: java.lang.foreign.AddressLayout::withTargetLayout has been called by demo.sqlite.sqlite3_h$shared in an unnamed module (file:/tmp/work/jextract/repo/jextract/build/classes/)
WARNING: Use --enable-native-access=ALL-UNNAMED to avoid a warning for callers in this module
WARNING: Restricted methods will be blocked in a future release unless native access is enabled

sqlite3_libversion()        = 3.45.1
returned segment byteSize   = 9223372036854775807
sqlite3_libversion_number() = 3045001
sqlite3_sourceid()          = 2024-01-30 16:01:20 e876e51a0ed5c5b3126f52e532044363a014bc594cfefa87ffb5b82257ccalt1

$ java --illegal-native-access=deny -cp build/classes demo.Hello
Exception in thread "main" java.lang.ExceptionInInitializerError
	at demo.Hello.main(Hello.java:10)
Caused by: java.lang.IllegalCallerException: Illegal native access from an unnamed module (file:/tmp/work/jextract/repo/jextract/build/classes/)
	at java.base/java.lang.Module.ensureNativeAccess(Module.java:307)
	at java.base/java.lang.System$1.ensureNativeAccess(System.java:2107)
	at java.base/jdk.internal.reflect.Reflection.ensureNativeAccess(Reflection.java:123)

$ java --enable-native-access=ALL-UNNAMED -Djextract.trace.downcalls=true -cp build/classes demo.Hello
sqlite3_libversion()
sqlite3_libversion()        = 3.45.1
returned segment byteSize   = 9223372036854775807
sqlite3_libversion_number()
sqlite3_libversion_number() = 3045001
sqlite3_sourceid()
sqlite3_sourceid()          = 2024-01-30 16:01:20 e876e51a0ed5c5b3126f52e532044363a014bc594cfefa87ffb5b82257ccalt1

Native memory has an owner: arenas

$ java --enable-native-access=ALL-UNNAMED -cp build/classes demo.Arenas
== confined: one owner thread
owner reads -> ok
other thread reads -> WrongThreadException: Attempted access outside owning thread
other thread closes -> WrongThreadException: Attempted access outside owning thread
read after close -> IllegalStateException: Already closed
close twice -> IllegalStateException: Already closed
== shared: any thread, one close
other thread reads -> ok
other thread closes -> ok
read after close -> IllegalStateException: Already closed
== auto: the garbage collector frees it; close() is not allowed
allocate 8 bytes -> ok
close() -> UnsupportedOperationException: Attempted to close a non-closeable session
== global: never freed; close() is not allowed
allocate 8 bytes -> ok
close() -> UnsupportedOperationException: Attempted to close a non-closeable session

== bounds: a segment knows its size
read int at offset 0 -> ok
read int at offset 4 -> IndexOutOfBoundsException: Out of bound access on segment MemorySegment{ kind: native, address: 0x7fba74666600, byteSize: 4 }; new offset = 4; new length = 4
read long at offset 0 -> IndexOutOfBoundsException: Out of bound access on segment MemorySegment{ kind: native, address: 0x7fba74666600, byteSize: 4 }; new offset = 0; new length = 8

The arena owns the buffers, not the library’s objects. When we open a database in a moment, SQLite allocates the connection itself. Closing your arena does not free it, and forgetting sqlite3_close leaks it even though every segment you allocated was freed. That asymmetry — Java frees what Java allocated, native code frees what native code allocated — is the single most useful rule in this whole API.

Strings in, pointers out: opening a database

    public static Db open(String path, int flags) {
        // A confined arena: the two small native buffers below live exactly as long as this block.
        try (Arena arena = Arena.ofConfined()) {
            MemorySegment out = arena.allocate(C_POINTER);          // room for ONE pointer: the sqlite3** out-parameter
            MemorySegment cPath = arena.allocateFrom(path);       // Java String -> NUL-terminated UTF-8 C string
            int rc = sqlite3_open_v2(cPath, out, flags, MemorySegment.NULL);
            MemorySegment db = out.get(C_POINTER, 0);               // read the pointer SQLite wrote
            if (rc != SQLITE_OK()) {
                // SQLite hands back a handle even on failure; it carries the message and must still be closed.
                String message = sqlite3_errmsg(db).getString(0);
                sqlite3_close(db);
                throw new SqliteException(rc, message);
            }
            return new Db(db);
        }
    }

A pointer you read back is only as useful as its layout. Everything above used C_POINTER, the layout jextract generates. The first version of Db used the plain ValueLayout.ADDRESS instead and failed on the first error message with IndexOutOfBoundsException: No null terminator found. A pointer read through plain ADDRESS is a segment of zero bytes: FFM has no idea how long the thing it points to is, so it refuses to read any of it. jextract’s C_POINTER is ADDRESS with a target layout of “unbounded chars”, which is why segments from the generated methods report Long.MAX_VALUE bytes — the number from the first call. src/demo/Trap.java shows both side by side (output/07-pointer-traps.txt):

$ java --enable-native-access=ALL-UNNAMED -cp build/classes demo.Trap
ValueLayout.ADDRESS : byteSize=0
getString(0)        : IndexOutOfBoundsException, "No null terminator found..."
reinterpret(100)    : hello from C land
C_POINTER           : byteSize=9223372036854775807
getString(0)        : hello from C land

$ java --enable-native-access=ALL-UNNAMED -XX:ErrorFile=/tmp/jextract-hs_err.log -cp build/classes demo.NullText     # first lines of the crash banner
address=0 byteSize=9223372036854775807 equals(NULL)=true
about to call getString(0) on it
#
# A fatal error has been detected by the Java Runtime Environment:
#
#  SIGSEGV (0xb) at pc=0x00007f002fe4645d, pid=20843, tid=20844
#
# JRE version: OpenJDK Runtime Environment Temurin-25.0.5+8 (25.0.5+8) (build 25.0.5+8-LTS)
# Java VM: OpenJDK 64-Bit Server VM Temurin-25.0.5+8 (25.0.5+8-LTS, mixed mode, sharing, tiered, compressed oops, compressed class ptrs, g1 gc, linux-amd64)
exit code: 134

Create, insert, query: using the wrapper

        /** SQLITE_TRANSIENT tells SQLite to copy the bytes now, so the temporary C string may be freed straight away. */
        public void bindText(Arena arena, int index, String value) {
            check(sqlite3_bind_text(ptr, index, arena.allocateFrom(value), -1, SQLITE_TRANSIENT()));
        }

        try (Db db = Db.open(":memory:")) {
            db.exec("CREATE TABLE person(id INTEGER PRIMARY KEY, name TEXT NOT NULL, age INTEGER)");
            try (Arena arena = Arena.ofConfined(); Db.Stmt ins = db.prepare(arena, "INSERT INTO person(name, age) VALUES (?1, ?2)")) {
                String[] names = {"Ankur", "Asha", "Ravi"};
                int[] ages = {41, 36, 29};
                for (int i = 0; i < names.length; i++) {
                    ins.bindText(arena, 1, names[i]);
                    ins.bindInt(2, ages[i]);
                    ins.step();
                    ins.reset();
                }
            }
            System.out.println("rows changed by last statement: " + db.changes() + ", last rowid: " + db.lastInsertRowid());
            for (var row : db.query("SELECT id, name, age FROM person ORDER BY id")) {
                System.out.println(row);
            }
            db.exec("INSERT INTO person(name) VALUES ('NoAge')");
            System.out.println(db.query("SELECT name, age FROM person WHERE age IS NULL"));

$ java --enable-native-access=ALL-UNNAMED -cp build/classes demo.Tour
rows changed by last statement: 1, last rowid: 3
[1, Ankur, 41]
[2, Asha, 36]
[3, Ravi, 29]
[[NoAge, null]]

Return codes become exceptions

    /** Runs SQL that returns no rows (DDL, INSERT...). Uses sqlite3_exec without a callback. */
    public void exec(String sql) {
        try (Arena arena = Arena.ofConfined()) {
            MemorySegment errOut = arena.allocate(C_POINTER);   // char** errmsg, SQLite fills it only on failure
            int rc = sqlite3_exec(handle, arena.allocateFrom(sql), MemorySegment.NULL, MemorySegment.NULL, errOut);
            if (rc != SQLITE_OK()) {
                MemorySegment msg = errOut.get(C_POINTER, 0);
                String text = msg.address() == 0 ? errmsg() : msg.getString(0);
                sqlite3_free(msg);                 // this string came from sqlite3_malloc: we must free it
                throw new SqliteException(rc, text);
            }
        }
    }

$ java --enable-native-access=ALL-UNNAMED -cp build/classes demo.Errors
open in a directory that does not exist -> unable to open database file (rc=14)
open a missing file read-only -> unable to open database file (rc=14)
syntax error -> near "SELEC": syntax error (rc=1)
missing table -> no such table: ghost (rc=1)
NOT NULL violation -> NOT NULL constraint failed: t.name (rc=19)
PRIMARY KEY violation -> UNIQUE constraint failed: t.id (rc=19)
SQLITE_CONSTRAINT = 19, sqlite3_errstr(19) = constraint failed

Callbacks, briefly: C calling a Java lambda

            sqlite3_exec$callback.Function onRow = (user, argc, values, names) -> {
                if (explode) {
                    throw new IllegalStateException("thrown inside the callback");
                }
                // values and names are char** : argc pointers each. Read them as an array of pointers.
                MemorySegment vals = values.reinterpret((long) argc * ValueLayout.ADDRESS.byteSize());
                MemorySegment nms = names.reinterpret((long) argc * ValueLayout.ADDRESS.byteSize());
                StringBuilder sb = new StringBuilder("row:");
                for (int i = 0; i < argc; i++) {
                    MemorySegment v = vals.getAtIndex(C_POINTER, i);
                    String value = v.address() == 0 ? "NULL" : v.getString(0);
                    sb.append(' ').append(nms.getAtIndex(C_POINTER, i).getString(0)).append('=').append(value);
                }
                System.out.println(sb);
                return 0;   // non-zero would abort the query with SQLITE_ABORT
            };
            MemorySegment stub = sqlite3_exec$callback.allocate(onRow, arena);   // the C function pointer
            MemorySegment errOut = arena.allocate(C_POINTER);
            int rc = sqlite3_exec(db.handle(), arena.allocateFrom("SELECT id, name FROM t"), stub, MemorySegment.NULL, errOut);

$ java --enable-native-access=ALL-UNNAMED -cp build/classes demo.Callbacks
row: id=1 name=one
row: id=2 name=two
row: id=3 name=NULL
sqlite3_exec returned 0

Never let an exception escape a callback. Run the same program with an argument that makes the lambda throw and the JVM does not unwind through SQLite’s C frames, because it cannot. It prints the stack trace and exits (output/09-callbacks.txt):

$ java --enable-native-access=ALL-UNNAMED -cp build/classes demo.Callbacks explode
java.lang.IllegalStateException: thrown inside the callback
	at demo.Callbacks.lambda$main$0(Callbacks.java:23)
	at demo.sqlite.sqlite3_h.sqlite3_exec(sqlite3_h.java:417)
	at demo.Callbacks.main(Callbacks.java:39)
Unrecoverable uncaught exception encountered. The VM will now exit
exit code: 1

Is it slower than JNI? Measured, with a big asterisk

Read these numbers as a shape, not a result. The machine has 2 CPUs and was shared with other builds the whole time: the load average was 4.00 before the run and 5.97 after (output/10-jmh.txt records both). The error columns, JMH’s 99.9% confidence interval, are consequently wide — between a fifth and a third of the score. An earlier three-fork run on the same machine, at a similar load, gave different scores (for example JNI strlike 150 ns instead of 245 ns), which I did not keep because it was superseded. Where two intervals overlap below, I treat the two paths as indistinguishable.

Benchmark                             Mode  Cnt       Score        Error  Units
SqliteBench.insert1000_ffm            avgt   25  653368.858 ± 161095.825  ns/op
SqliteBench.insert1000_jni            avgt   25  544963.964 ±  97090.203  ns/op
SqliteBench.strlike_ffm_arenaPerCall  avgt   25     192.233 ±     62.055  ns/op
SqliteBench.strlike_ffm_preallocated  avgt   25      82.660 ±     16.253  ns/op
SqliteBench.strlike_jni               avgt   25     244.929 ±     82.330  ns/op
SqliteBench.versionNumber_ffm         avgt   25      16.819 ±      4.063  ns/op
SqliteBench.versionNumber_jni         avgt   25      14.054 ±      4.949  ns/op
SqliteBench.versionNumber_plainJava   avgt   25       0.651 ±      0.162  ns/op
load average after the run: 5.97 6.05 4.10

Should you even do this?

Often the answer is “use the Java driver”. If the library you want has a maintained Java binding — and SQLite does, in the form of JDBC drivers — use it. A binding generated by you is a binding you maintain: you re-run jextract when the header changes, you own the ownership rules (who frees what), and every mistake can crash the whole JVM instead of throwing. FFM earns its place when there is no Java library, when the native library is the point (a codec, a GPU runtime, an OS API, a vendor SDK), or when you want to drop a hand-written JNI layer you already maintain. The performance numbers above do not change this: for SQLite, the cost of the SQL dwarfs the cost of the call.

And jextract is early-access. There is no GA release of jextract; the build I used is labelled early-access and the download page says such builds are not tested to the same level as GA builds. The generated code, once produced, depends only on the JDK and is yours to commit — which is the practical mitigation: pin the jextract build you used in a script, commit the output, and review the diff when you regenerate.

What I did not test

• macOS and Windows: the commands, library names (.dylib, .dll) and framework options of jextract were not run. Only Linux x64.
• JDK 26 and 27: everything ran on JDK 25.0.5 only. JEP 472 says restrictions will tighten in a future release; I measured JDK 25’s warn-by-default and the explicit deny mode, nothing else.
• A SQLite newer than 3.45.1, SQLite built with different options, and thread safety: every demo is single-threaded apart from the arena misuse examples.
• Structs, unions and global variables in generated code: SQLite’s public API is almost all functions on opaque pointers, so the struct accessors jextract generates were not exercised. The unfiltered run does generate such classes for the FTS5 extension structs; I did not use them.
• SQLITE_STATIC used with a freed arena: described from the SQLite header, not run.
• jextract flags other than the ones in gen.sh, including --use-system-load-library and the macOS -F/--framework options.
• A GraalVM native image, jlink or jpackage build with a native library: not tried. For the packaging side of a Java app, see Building Native Installers for Java Applications with jpackage.

Further reading

• The companion module: javademos/jextract — README, gen.sh, Db.java, every captured transcript
• Foreign Function & Memory API: Upcalls, errno, and JEP 472 Explained — hand-written downcalls, qsort upcalls, errno capture
• Java 21 to 25 LTS Features — where FFM sits in the JDK 21-to-25 upgrade
• JEP 454: Foreign Function & Memory API — final in JDK 22
• JEP 472: Prepare to Restrict the Use of JNI — the warn-then-deny timeline for native access
• jdk.java.net/jextract — the early-access builds
• The jextract guide — options, library loading, structs and callbacks
• SQLite C interface reference — the functions wrapped here
• JMH — the benchmark harness