How xerial/sqlite-jdbc works
Project type and purpose
• This is a Java library—a JDBC driver that embeds the SQLite native engine.
• Purpose: expose SQLite database functionality through standard Java JDBC interfaces, auto-extracting an OS-specific native library at runtime, and supporting GraalVM native-image builds.
File-structure overview
• Top level
• pom.xml / Makefile / Dockerfiles / GitHub workflows → build, CI, cross-compile.
• src/main/java/org/sqlite → core JDBC driver classes (Driver, Connection, Statement, ResultSet, Configuration, listeners).
• src/main/java/org/sqlite/core → JNI wrapper (NativeDB.java / NativeDB.c) and core DB metadata + statement implementations.
• src/main/java/org/sqlite/util, /date, /jdbc3, /jdbc4, /javax → utility, backward-compatibility, javax-pool support.
• src/main/resources/org/sqlite/native/... → prebuilt native libraries (.so/.dll/.dylib) for each OS/arch.
• src/main/ext/extension-functions.c → custom SQLite UDF extension code.
• src/test & src/test/resources → unit/integration tests, sample DBs.
• demo/ → sample usage.
• docker/ → cross-compilation Docker images and scripts.
• README.adoc and USAGE.md describe usage, architecture, GraalVM support.
A. Java client code (your application)
B. JDBC API layer (java.sql.* interfaces)
C. org.sqlite.JDBC driver
• DriverManager registration → Driver class
• SQLiteJDBCLoader / ResourceFinder → finds correct native lib in JAR
• Extraction to OS temp folder
• System.load → loads JNI library
D. JNI bridge (NativeDB.java + NativeDB.c)
• JNI methods map Java calls (open, execSQL, prepare) to C API
E. SQLite native engine (C library)
• .so/.dll/.dylib code executed via JNI
• Filesystem interaction: reads/writes .db file
F. Optional GraalVM native-image integration
• native-build-tools plugin configuration
• Resource config under META-INF/native-image
G. Build & CI
• Maven (pom.xml) + shade plugin
• Docker cross-compile scripts (docker/)
• GitHub Actions workflows (.github/workflows)
Relationships & interactions
• Bi-directional data flows for queries/results.
• Extension functions loaded from src/main/ext.
Architectural patterns & principles
• Wrapper / Adapter pattern: JDBC interfaces adapted to native C via JNI.
• Auto-configuration: packaged native libs + ResourceFinder.
• Modularity: separate packages for core, util, date, JDBC3 vs JDBC4, javax.
• Cross-platform packaging: native libraries per OS/arch bundled in one JAR.
Detail capture
• Native-extraction process (ResourceFinder → temp folder → System.load).
• Where extension UDF code plugs in.
• Test harness (src/test) only if diagramming end-to-end CI build.