Relevant source files

The following files were used as context for generating this wiki page: - [ext/jni/README.md](https://github.com/sqlite/sqlite/blob/main/ext/jni/README.md) - [ext/jni/src/c/sqlite3-jni.c](https://github.com/sqlite/sqlite/blob/main/ext/jni/src/c/sqlite3-jni.c) - [ext/jni/src/org/sqlite/jni/capi/CApi.java](https://github.com/sqlite/sqlite/blob/main/ext/jni/src/org/sqlite/jni/capi/CApi.java) - [ext/jni/src/org/sqlite/jni/capi/package-info.java](https://github.com/sqlite/sqlite/blob/main/ext/jni/src/org/sqlite/jni/capi/package-info.java) - [ext/jni/src/org/sqlite/jni/capi/Tester1.java](https://github.com/sqlite/sqlite/blob/main/ext/jni/src/org/sqlite/jni/capi/Tester1.java) - [README.md](https://github.com/sqlite/sqlite/blob/main/README.md)

# Java Native Interface (JNI) The SQLite Java Native Interface (JNI) provides a low-level binding of the C-style `sqlite3` API to the Java programming language. Its primary goal is to offer a near 1-to-1 mapping of the C API, allowing Java developers to use the extensive existing C API documentation with minimal translation. This binding is designed to be environment-independent, have no third-party dependencies beyond the JDK, and support Java versions as far back as Java 8. This JNI layer is intentionally not a high-level, object-oriented wrapper. Instead, it provides the fundamental building blocks upon which such higher-level APIs can be built. It exposes the power and semantics of the C API directly, including its resource management and error handling paradigms. As of version 3.43, this feature is considered a "tech preview" and is subject to change. Sources: [ext/jni/README.md:5-28](), [ext/jni/src/org/sqlite/jni/capi/package-info.java:4-23]() ## Architecture Overview The JNI binding consists of two main parts: a Java-side API and a C-side native implementation that bridges Java to the core `sqlite3.c` library. * **Java API (`org.sqlite.jni.capi.CApi.java`)**: This class contains the static methods that mirror the C API functions (e.g., `sqlite3_open`, `sqlite3_prepare_v2`). It also defines wrapper classes for SQLite's opaque pointer types, such as `sqlite3`, `sqlite3_stmt`, and `sqlite3_context`. * **Native C Implementation (`sqlite3-jni.c`)**: This C file contains the JNI functions that are called by the Java API. It handles the translation of data types between Java and C, manages the lifecycle of native resources, and maintains global state and caches to optimize the interaction. The general flow of an operation from Java to the native SQLite library is depicted below. ```mermaid graph TD A[Java Application] --> B[org.sqlite.jni.capi.CApi]; B -- JNI Call --> C["sqlite3-jni.c (JNI Layer)"]; C -- Native Call --> D["sqlite3.c (Core Library)"]; D -- Return --> C; C -- Return --> B; B -- Return --> A; ``` This diagram shows the call stack from a Java application through the JNI layer to the core SQLite library. Sources: [ext/jni/src/org/sqlite/jni/capi/CApi.java](), [ext/jni/src/c/sqlite3-jni.c]() ## Core Concepts ### Pointer Management A central challenge in bridging C and Java is handling pointers. The SQLite C API extensively uses opaque pointers for handles to database connections (`sqlite3*`), prepared statements (`sqlite3_stmt*`), and other resources. In the JNI binding, these native pointers are stored in Java objects as `long` values. The C-side JNI layer uses a set of macros to safely cast these `jlong` values back and forth to native pointers. * `S3JniCast_L2P(JLongAsPtr)`: Casts a `jlong` to a `void*`. * `S3JniCast_P2L(PTR)`: Casts a `void*` to a `jlong`. On the Java side, these pointers are held within subclasses of `NativePointerHolder`. This provides a type-safe way to manage native resources. Sources: [ext/jni/src/c/sqlite3-jni.c:268-275]() The diagram below illustrates the class structure for managing native pointers on the Java side. ```mermaid classDiagram class NativePointerHolder { #long nativePointer +long getNativePointer() #long clearNativePointer() } class sqlite3 { <> } class sqlite3_stmt { <> } class sqlite3_context { <> } class sqlite3_value { <> } class sqlite3_blob { <> } NativePointerHolder <|-- sqlite3 NativePointerHolder <|-- sqlite3_stmt NativePointerHolder <|-- sqlite3_context NativePointerHolder <|-- sqlite3_value NativePointerHolder <|-- sqlite3_blob ``` This diagram shows that various SQLite resource types in Java inherit from a common `NativePointerHolder` to manage the underlying C pointer. Sources: [ext/jni/src/org/sqlite/jni/capi/CApi.java]() ### C-Side State Management The `sqlite3-jni.c` implementation maintains significant internal state to manage the bridge between Java and C efficiently. This state is primarily held in a global `S3JniGlobalType` struct and per-database `S3JniDb` structs. #### Global State (`S3JniGlobalType`) A single global instance of `S3JniGlobalType` (named `SJG`) holds caches and resources that are shared across the application. | Member | Description | | :--- | :--- | | `jvm` | Cached pointer to the `JavaVM`, used to get the `JNIEnv` for the current thread. | | `mutex` | A global mutex for protecting shared state. | | `nph` | A cache for `S3JniNphOp` structs, which store `jclass` and `jfieldID` references for `NativePointerHolder` and `OutputPointer` types to avoid repeated lookups. | | `envCache` | A per-thread cache of `S3JniEnv` structs. | | `perDb` | A free-list for recycling `S3JniDb` structs. | | `udf` | A free-list for recycling `S3JniUdf` structs used for user-defined functions. | | `g` | Global references to frequently used Java classes and methods, like `java.lang.Long` and `java.lang.String`. | | `autoExt` | Manages the list of Java-side auto-extensions. | | `hook` | Manages global hooks like `SQLITE_CONFIG_LOG`. | | `metrics` | (Optional) Internal metrics for performance monitoring. | Sources: [ext/jni/src/c/sqlite3-jni.c:836-937]() #### Per-Database State (`S3JniDb`) For each opened `sqlite3*` handle, a corresponding `S3JniDb` struct is allocated. This struct is associated with the C `sqlite3*` handle via `sqlite3_get_clientdata()` and `sqlite3_set_clientdata()`. | Member | Description | | :--- | :--- | | `pDb` | The native `sqlite3*` database handle. | | `jDb` | A global reference to the corresponding Java `org.sqlite.jni.capi.sqlite3` object. | | `zMainDbName` | Holds the string for `SQLITE_DBCONFIG_MAINDBNAME`. | | `hooks` | A struct containing `S3JniHook` instances for all per-database hooks (e.g., commit, update, rollback). | Sources: [ext/jni/src/c/sqlite3-jni.c:668-698]() ### Callback and Hook Handling One area where the JNI binding deviates from a strict 1-to-1 mapping is in handling C callbacks (function pointers). Since Java does not have a direct equivalent, the JNI layer uses Java interfaces and classes to represent C callbacks. For example, to create a custom SQL function, a developer implements the `SQLFunction` interface (typically via its `ScalarFunction`, `AggregateFunction`, or `WindowFunction` subclasses) and passes an instance to `sqlite3_create_function()`. The C-side JNI layer handles this by: 1. Allocating a C-side wrapper struct (`S3JniUdf` for UDFs, `S3JniHook` for other hooks). 2. Storing a global reference to the Java callback object and the `jmethodID` of its `call()` (or equivalent) method in the wrapper struct. 3. Passing a pointer to the C-side wrapper struct as the `pUserData` argument to the underlying `sqlite3` C function. 4. Providing a static C function (e.g., `udf_xFunc`) as the callback pointer, which then uses the `pUserData` to find the Java object and invoke its method via JNI. This flow is illustrated in the sequence diagram below for `sqlite3_create_function`. ```mermaid sequenceDiagram participant JavaApp as "Java Application" participant CApi as "CApi.java" participant JNI as "sqlite3-jni.c" participant SQLiteCore as "sqlite3.c" JavaApp->>CApi: sqlite3_create_function(db, "myfunc", new MyScalarFunc()) CApi->>JNI: JniFuncName(1create_1function)(...) JNI->>JNI: S3JniUdf_alloc(jFunctor) Note right of JNI: Allocates S3JniUdf struct, gets jmethodID for xFunc, creates global ref to Java object. JNI->>SQLiteCore: sqlite3_create_function_v2(pDb, "myfunc", ..., pS3JniUdf, udf_xFunc, ..., S3JniUdf_finalizer) Note right of SQLiteCore: Stores pS3JniUdf and function pointers. SQLiteCore-->>JNI: returns SQLITE_OK JNI-->>CApi: returns 0 CApi-->>JavaApp: returns 0 ... later, when "SELECT myfunc()" is executed ... SQLiteCore->>JNI: udf_xFunc(pCx, argc, argv) Note right of JNI: pUserData from pCx is the S3JniUdf pointer. JNI->>JNI: Retrieves jObj and jmidxFunc from S3JniUdf JNI->>CApi: env->CallVoidMethod(jObj, jmidxFunc, ...) CApi->>JavaApp: MyScalarFunc.xFunc() is invoked JavaApp-->>CApi: CApi-->>JNI: JNI-->>SQLiteCore: ``` This diagram shows how a Java `SQLFunction` object is registered with and later invoked by the native SQLite core through the JNI layer. Sources: [ext/jni/README.md:210-244](), [ext/jni/src/c/sqlite3-jni.c:4525-4584](), [ext/jni/src/org/sqlite/jni/capi/CApi.java:826-836]() ### Golden Rules and Threading The JNI binding inherits the C API's semantics, which leads to two "golden rules" for developers: 1. **Garbage Collection Cannot Free SQLite Resources**: Native resources like `sqlite3` and `sqlite3_stmt` handles are not managed by the Java garbage collector. They must be explicitly freed by calling `sqlite3_close_v2()` and `sqlite3_finalize()`, respectively. Many resource classes implement `AutoCloseable` to facilitate this with try-with-resources blocks. 2. **Never Throw from Callbacks (Unless Documented)**: Callbacks provided by the user (e.g., for UDFs or hooks) must not throw exceptions unless the API explicitly permits it. Unhandled exceptions from callbacks that cannot propagate errors back to SQLite will be suppressed to maintain C-style semantics. Regarding threading, the API is thread-safe if SQLite is compiled with `SQLITE_THREADSAFE=1` or `2`. However, there is a key limitation in the JNI binding: a specific resource handle (like `sqlite3` or `sqlite3_stmt`) must not be used concurrently from multiple threads. It is legal to use a handle across different threads, but not at the same time. Sources: [ext/jni/README.md:112-154](), [ext/jni/src/org/sqlite/jni/capi/package-info.java:27-51]() ## Key API Components ### Java API (`CApi.java`) The `org.sqlite.jni.capi.CApi` class is the primary entry point for Java applications. | Class / Interface | Description | | :--- | :--- | | `sqlite3` | Wrapper for a native database connection handle (`sqlite3*`). | | `sqlite3_stmt` | Wrapper for a native prepared statement handle (`sqlite3_stmt*`). | | `sqlite3_context` | Wrapper for a UDF context handle (`sqlite3_context*`), passed to UDF implementations. | | `sqlite3_value` | Wrapper for a protected SQL value handle (`sqlite3_value*`), passed to UDF implementations. | | `OutputPointer` | A generic class used to emulate C's output pointers (e.g., `sqlite3** ppDb`). | | `SQLFunction` | Base class for creating user-defined SQL functions. Subclassed into `ScalarFunction`, `AggregateFunction`, and `WindowFunction`. | | `BusyHandlerCallback` | Interface for implementing a custom busy handler. | | `CommitHookCallback` | Interface for implementing a commit hook. | | `TraceV2Callback` | Interface for implementing a tracer with `sqlite3_trace_v2()`. | Sources: [ext/jni/src/org/sqlite/jni/capi/CApi.java]() ### Hello, World Example The following example demonstrates the basic usage of the JNI API to open a database, check for errors, and close it. ```java import org.sqlite.jni.capi.CApi.*; import org.sqlite.jni.capi.sqlite3; // ... final sqlite3 db = sqlite3_open(":memory:"); try { final int rc = sqlite3_errcode(db); if( 0 != rc ){ if( null != db ){ System.out.print("Error opening db: "+sqlite3_errmsg(db)); }else{ System.out.print("Error opening db: rc="+rc); } // ... handle error ... } // ... else use the db ... }finally{ // ALWAYS close databases using sqlite3_close() or sqlite3_close_v2() sqlite3_close_v2(db); } ``` Sources: [ext/jni/README.md:65-87]() ## Summary The SQLite JNI binding provides a powerful, low-level bridge for Java applications to access the full capabilities of the SQLite C API. It prioritizes a direct mapping of C semantics over idiomatic Java abstractions, giving developers fine-grained control. Its architecture relies on careful management of native pointers, a C-side caching layer for performance, and a callback system that translates Java interfaces into C function pointers. While this approach requires developers to be mindful of manual resource management and specific threading rules, it offers unparalleled access to SQLite's features from the Java ecosystem.