/*
** 2023-10-09
**
** The author disclaims copyright to this source code. In place of
** a legal notice, here is a blessing:
**
** May you do good and not evil.
** May you find forgiveness for yourself and forgive others.
** May you share freely, never taking more than you give.
**
*************************************************************************
** This file is part of the wrapper1 interface for sqlite3.
*/
package org.sqlite.jni.wrapper1;
import java.nio.charset.StandardCharsets;
import org.sqlite.jni.capi.CApi;
import org.sqlite.jni.capi.sqlite3;
import org.sqlite.jni.capi.sqlite3_stmt;
import org.sqlite.jni.capi.sqlite3_backup;
import org.sqlite.jni.capi.sqlite3_blob;
import org.sqlite.jni.capi.OutputPointer;
import java.nio.ByteBuffer;
/**
This class represents a database connection, analog to the C-side
sqlite3 class but with added argument validation, exceptions, and
similar "smoothing of sharp edges" to make the API safe to use from
Java. It also acts as a namespace for other types for which
individual instances are tied to a specific database connection.
*/
public final class Sqlite implements AutoCloseable {
private sqlite3 db;
private static final boolean JNI_SUPPORTS_NIO =
CApi.sqlite3_jni_supports_nio();
// Result codes
public static final int OK = CApi.SQLITE_OK;
public static final int ERROR = CApi.SQLITE_ERROR;
public static final int INTERNAL = CApi.SQLITE_INTERNAL;
public static final int PERM = CApi.SQLITE_PERM;
public static final int ABORT = CApi.SQLITE_ABORT;
public static final int BUSY = CApi.SQLITE_BUSY;
public static final int LOCKED = CApi.SQLITE_LOCKED;
public static final int NOMEM = CApi.SQLITE_NOMEM;
public static final int READONLY = CApi.SQLITE_READONLY;
public static final int INTERRUPT = CApi.SQLITE_INTERRUPT;
public static final int IOERR = CApi.SQLITE_IOERR;
public static final int CORRUPT = CApi.SQLITE_CORRUPT;
public static final int NOTFOUND = CApi.SQLITE_NOTFOUND;
public static final int FULL = CApi.SQLITE_FULL;
public static final int CANTOPEN = CApi.SQLITE_CANTOPEN;
public static final int PROTOCOL = CApi.SQLITE_PROTOCOL;
public static final int EMPTY = CApi.SQLITE_EMPTY;
public static final int SCHEMA = CApi.SQLITE_SCHEMA;
public static final int TOOBIG = CApi.SQLITE_TOOBIG;
public static final int CONSTRAINT = CApi. SQLITE_CONSTRAINT;
public static final int MISMATCH = CApi.SQLITE_MISMATCH;
public static final int MISUSE = CApi.SQLITE_MISUSE;
public static final int NOLFS = CApi.SQLITE_NOLFS;
public static final int AUTH = CApi.SQLITE_AUTH;
public static final int FORMAT = CApi.SQLITE_FORMAT;
public static final int RANGE = CApi.SQLITE_RANGE;
public static final int NOTADB = CApi.SQLITE_NOTADB;
public static final int NOTICE = CApi.SQLITE_NOTICE;
public static final int WARNING = CApi.SQLITE_WARNING;
public static final int ROW = CApi.SQLITE_ROW;
public static final int DONE = CApi.SQLITE_DONE;
public static final int ERROR_MISSING_COLLSEQ = CApi.SQLITE_ERROR_MISSING_COLLSEQ;
public static final int ERROR_RETRY = CApi.SQLITE_ERROR_RETRY;
public static final int ERROR_SNAPSHOT = CApi.SQLITE_ERROR_SNAPSHOT;
public static final int IOERR_READ = CApi.SQLITE_IOERR_READ;
public static final int IOERR_SHORT_READ = CApi.SQLITE_IOERR_SHORT_READ;
public static final int IOERR_WRITE = CApi.SQLITE_IOERR_WRITE;
public static final int IOERR_FSYNC = CApi.SQLITE_IOERR_FSYNC;
public static final int IOERR_DIR_FSYNC = CApi.SQLITE_IOERR_DIR_FSYNC;
public static final int IOERR_TRUNCATE = CApi.SQLITE_IOERR_TRUNCATE;
public static final int IOERR_FSTAT = CApi.SQLITE_IOERR_FSTAT;
public static final int IOERR_UNLOCK = CApi.SQLITE_IOERR_UNLOCK;
public static final int IOERR_RDLOCK = CApi.SQLITE_IOERR_RDLOCK;
public static final int IOERR_DELETE = CApi.SQLITE_IOERR_DELETE;
public static final int IOERR_BLOCKED = CApi.SQLITE_IOERR_BLOCKED;
public static final int IOERR_NOMEM = CApi.SQLITE_IOERR_NOMEM;
public static final int IOERR_ACCESS = CApi.SQLITE_IOERR_ACCESS;
public static final int IOERR_CHECKRESERVEDLOCK = CApi.SQLITE_IOERR_CHECKRESERVEDLOCK;
public static final int IOERR_LOCK = CApi.SQLITE_IOERR_LOCK;
public static final int IOERR_CLOSE = CApi.SQLITE_IOERR_CLOSE;
public static final int IOERR_DIR_CLOSE = CApi.SQLITE_IOERR_DIR_CLOSE;
public static final int IOERR_SHMOPEN = CApi.SQLITE_IOERR_SHMOPEN;
public static final int IOERR_SHMSIZE = CApi.SQLITE_IOERR_SHMSIZE;
public static final int IOERR_SHMLOCK = CApi.SQLITE_IOERR_SHMLOCK;
public static final int IOERR_SHMMAP = CApi.SQLITE_IOERR_SHMMAP;
public static final int IOERR_SEEK = CApi.SQLITE_IOERR_SEEK;
public static final int IOERR_DELETE_NOENT = CApi.SQLITE_IOERR_DELETE_NOENT;
public static final int IOERR_MMAP = CApi.SQLITE_IOERR_MMAP;
public static final int IOERR_GETTEMPPATH = CApi.SQLITE_IOERR_GETTEMPPATH;
public static final int IOERR_CONVPATH = CApi.SQLITE_IOERR_CONVPATH;
public static final int IOERR_VNODE = CApi.SQLITE_IOERR_VNODE;
public static final int IOERR_AUTH = CApi.SQLITE_IOERR_AUTH;
public static final int IOERR_BEGIN_ATOMIC = CApi.SQLITE_IOERR_BEGIN_ATOMIC;
public static final int IOERR_COMMIT_ATOMIC = CApi.SQLITE_IOERR_COMMIT_ATOMIC;
public static final int IOERR_ROLLBACK_ATOMIC = CApi.SQLITE_IOERR_ROLLBACK_ATOMIC;
public static final int IOERR_DATA = CApi.SQLITE_IOERR_DATA;
public static final int IOERR_CORRUPTFS = CApi.SQLITE_IOERR_CORRUPTFS;
public static final int LOCKED_SHAREDCACHE = CApi.SQLITE_LOCKED_SHAREDCACHE;
public static final int LOCKED_VTAB = CApi.SQLITE_LOCKED_VTAB;
public static final int BUSY_RECOVERY = CApi.SQLITE_BUSY_RECOVERY;
public static final int BUSY_SNAPSHOT = CApi.SQLITE_BUSY_SNAPSHOT;
public static final int BUSY_TIMEOUT = CApi.SQLITE_BUSY_TIMEOUT;
public static final int CANTOPEN_NOTEMPDIR = CApi.SQLITE_CANTOPEN_NOTEMPDIR;
public static final int CANTOPEN_ISDIR = CApi.SQLITE_CANTOPEN_ISDIR;
public static final int CANTOPEN_FULLPATH = CApi.SQLITE_CANTOPEN_FULLPATH;
public static final int CANTOPEN_CONVPATH = CApi.SQLITE_CANTOPEN_CONVPATH;
public static final int CANTOPEN_SYMLINK = CApi.SQLITE_CANTOPEN_SYMLINK;
public static final int CORRUPT_VTAB = CApi.SQLITE_CORRUPT_VTAB;
public static final int CORRUPT_SEQUENCE = CApi.SQLITE_CORRUPT_SEQUENCE;
public static final int CORRUPT_INDEX = CApi.SQLITE_CORRUPT_INDEX;
public static final int READONLY_RECOVERY = CApi.SQLITE_READONLY_RECOVERY;
public static final int READONLY_CANTLOCK = CApi.SQLITE_READONLY_CANTLOCK;
public static final int READONLY_ROLLBACK = CApi.SQLITE_READONLY_ROLLBACK;
public static final int READONLY_DBMOVED = CApi.SQLITE_READONLY_DBMOVED;
public static final int READONLY_CANTINIT = CApi.SQLITE_READONLY_CANTINIT;
public static final int READONLY_DIRECTORY = CApi.SQLITE_READONLY_DIRECTORY;
public static final int ABORT_ROLLBACK = CApi.SQLITE_ABORT_ROLLBACK;
public static final int CONSTRAINT_CHECK = CApi.SQLITE_CONSTRAINT_CHECK;
public static final int CONSTRAINT_COMMITHOOK = CApi.SQLITE_CONSTRAINT_COMMITHOOK;
public static final int CONSTRAINT_FOREIGNKEY = CApi.SQLITE_CONSTRAINT_FOREIGNKEY;
public static final int CONSTRAINT_FUNCTION = CApi.SQLITE_CONSTRAINT_FUNCTION;
public static final int CONSTRAINT_NOTNULL = CApi.SQLITE_CONSTRAINT_NOTNULL;
public static final int CONSTRAINT_PRIMARYKEY = CApi.SQLITE_CONSTRAINT_PRIMARYKEY;
public static final int CONSTRAINT_TRIGGER = CApi.SQLITE_CONSTRAINT_TRIGGER;
public static final int CONSTRAINT_UNIQUE = CApi.SQLITE_CONSTRAINT_UNIQUE;
public static final int CONSTRAINT_VTAB = CApi.SQLITE_CONSTRAINT_VTAB;
public static final int CONSTRAINT_ROWID = CApi.SQLITE_CONSTRAINT_ROWID;
public static final int CONSTRAINT_PINNED = CApi.SQLITE_CONSTRAINT_PINNED;
public static final int CONSTRAINT_DATATYPE = CApi.SQLITE_CONSTRAINT_DATATYPE;
public static final int NOTICE_RECOVER_WAL = CApi.SQLITE_NOTICE_RECOVER_WAL;
public static final int NOTICE_RECOVER_ROLLBACK = CApi.SQLITE_NOTICE_RECOVER_ROLLBACK;
public static final int WARNING_AUTOINDEX = CApi.SQLITE_WARNING_AUTOINDEX;
public static final int AUTH_USER = CApi.SQLITE_AUTH_USER;
public static final int OK_LOAD_PERMANENTLY = CApi.SQLITE_OK_LOAD_PERMANENTLY;
// sqlite3_open() flags
public static final int OPEN_READWRITE = CApi.SQLITE_OPEN_READWRITE;
public static final int OPEN_CREATE = CApi.SQLITE_OPEN_CREATE;
public static final int OPEN_EXRESCODE = CApi.SQLITE_OPEN_EXRESCODE;
// transaction state
public static final int TXN_NONE = CApi.SQLITE_TXN_NONE;
public static final int TXN_READ = CApi.SQLITE_TXN_READ;
public static final int TXN_WRITE = CApi.SQLITE_TXN_WRITE;
// sqlite3_status() ops
public static final int STATUS_MEMORY_USED = CApi.SQLITE_STATUS_MEMORY_USED;
public static final int STATUS_PAGECACHE_USED = CApi.SQLITE_STATUS_PAGECACHE_USED;
public static final int STATUS_PAGECACHE_OVERFLOW = CApi.SQLITE_STATUS_PAGECACHE_OVERFLOW;
public static final int STATUS_MALLOC_SIZE = CApi.SQLITE_STATUS_MALLOC_SIZE;
public static final int STATUS_PARSER_STACK = CApi.SQLITE_STATUS_PARSER_STACK;
public static final int STATUS_PAGECACHE_SIZE = CApi.SQLITE_STATUS_PAGECACHE_SIZE;
public static final int STATUS_MALLOC_COUNT = CApi.SQLITE_STATUS_MALLOC_COUNT;
// sqlite3_db_status() ops
public static final int DBSTATUS_LOOKASIDE_USED = CApi.SQLITE_DBSTATUS_LOOKASIDE_USED;
public static final int DBSTATUS_CACHE_USED = CApi.SQLITE_DBSTATUS_CACHE_USED;
public static final int DBSTATUS_SCHEMA_USED = CApi.SQLITE_DBSTATUS_SCHEMA_USED;
public static final int DBSTATUS_STMT_USED = CApi.SQLITE_DBSTATUS_STMT_USED;
public static final int DBSTATUS_LOOKASIDE_HIT = CApi.SQLITE_DBSTATUS_LOOKASIDE_HIT;
public static final int DBSTATUS_LOOKASIDE_MISS_SIZE = CApi.SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE;
public static final int DBSTATUS_LOOKASIDE_MISS_FULL = CApi.SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL;
public static final int DBSTATUS_CACHE_HIT = CApi.SQLITE_DBSTATUS_CACHE_HIT;
public static final int DBSTATUS_CACHE_MISS = CApi.SQLITE_DBSTATUS_CACHE_MISS;
public static final int DBSTATUS_CACHE_WRITE = CApi.SQLITE_DBSTATUS_CACHE_WRITE;
public static final int DBSTATUS_DEFERRED_FKS = CApi.SQLITE_DBSTATUS_DEFERRED_FKS;
public static final int DBSTATUS_CACHE_USED_SHARED = CApi.SQLITE_DBSTATUS_CACHE_USED_SHARED;
public static final int DBSTATUS_CACHE_SPILL = CApi.SQLITE_DBSTATUS_CACHE_SPILL;
// Limits
public static final int LIMIT_LENGTH = CApi.SQLITE_LIMIT_LENGTH;
public static final int LIMIT_SQL_LENGTH = CApi.SQLITE_LIMIT_SQL_LENGTH;
public static final int LIMIT_COLUMN = CApi.SQLITE_LIMIT_COLUMN;
public static final int LIMIT_EXPR_DEPTH = CApi.SQLITE_LIMIT_EXPR_DEPTH;
public static final int LIMIT_COMPOUND_SELECT = CApi.SQLITE_LIMIT_COMPOUND_SELECT;
public static final int LIMIT_VDBE_OP = CApi.SQLITE_LIMIT_VDBE_OP;
public static final int LIMIT_FUNCTION_ARG = CApi.SQLITE_LIMIT_FUNCTION_ARG;
public static final int LIMIT_ATTACHED = CApi.SQLITE_LIMIT_ATTACHED;
public static final int LIMIT_LIKE_PATTERN_LENGTH = CApi.SQLITE_LIMIT_LIKE_PATTERN_LENGTH;
public static final int LIMIT_VARIABLE_NUMBER = CApi.SQLITE_LIMIT_VARIABLE_NUMBER;
public static final int LIMIT_TRIGGER_DEPTH = CApi.SQLITE_LIMIT_TRIGGER_DEPTH;
public static final int LIMIT_WORKER_THREADS = CApi.SQLITE_LIMIT_WORKER_THREADS;
// sqlite3_prepare_v3() flags
public static final int PREPARE_PERSISTENT = CApi.SQLITE_PREPARE_PERSISTENT;
public static final int PREPARE_NO_VTAB = CApi.SQLITE_PREPARE_NO_VTAB;
// sqlite3_trace_v2() flags
public static final int TRACE_STMT = CApi.SQLITE_TRACE_STMT;
public static final int TRACE_PROFILE = CApi.SQLITE_TRACE_PROFILE;
public static final int TRACE_ROW = CApi.SQLITE_TRACE_ROW;
public static final int TRACE_CLOSE = CApi.SQLITE_TRACE_CLOSE;
public static final int TRACE_ALL = TRACE_STMT | TRACE_PROFILE | TRACE_ROW | TRACE_CLOSE;
// sqlite3_db_config() ops
public static final int DBCONFIG_ENABLE_FKEY = CApi.SQLITE_DBCONFIG_ENABLE_FKEY;
public static final int DBCONFIG_ENABLE_TRIGGER = CApi.SQLITE_DBCONFIG_ENABLE_TRIGGER;
public static final int DBCONFIG_ENABLE_FTS3_TOKENIZER = CApi.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER;
public static final int DBCONFIG_ENABLE_LOAD_EXTENSION = CApi.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION;
public static final int DBCONFIG_NO_CKPT_ON_CLOSE = CApi.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE;
public static final int DBCONFIG_ENABLE_QPSG = CApi.SQLITE_DBCONFIG_ENABLE_QPSG;
public static final int DBCONFIG_TRIGGER_EQP = CApi.SQLITE_DBCONFIG_TRIGGER_EQP;
public static final int DBCONFIG_RESET_DATABASE = CApi.SQLITE_DBCONFIG_RESET_DATABASE;
public static final int DBCONFIG_DEFENSIVE = CApi.SQLITE_DBCONFIG_DEFENSIVE;
public static final int DBCONFIG_WRITABLE_SCHEMA = CApi.SQLITE_DBCONFIG_WRITABLE_SCHEMA;
public static final int DBCONFIG_LEGACY_ALTER_TABLE = CApi.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE;
public static final int DBCONFIG_DQS_DML = CApi.SQLITE_DBCONFIG_DQS_DML;
public static final int DBCONFIG_DQS_DDL = CApi.SQLITE_DBCONFIG_DQS_DDL;
public static final int DBCONFIG_ENABLE_VIEW = CApi.SQLITE_DBCONFIG_ENABLE_VIEW;
public static final int DBCONFIG_LEGACY_FILE_FORMAT = CApi.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT;
public static final int DBCONFIG_TRUSTED_SCHEMA = CApi.SQLITE_DBCONFIG_TRUSTED_SCHEMA;
public static final int DBCONFIG_STMT_SCANSTATUS = CApi.SQLITE_DBCONFIG_STMT_SCANSTATUS;
public static final int DBCONFIG_REVERSE_SCANORDER = CApi.SQLITE_DBCONFIG_REVERSE_SCANORDER;
// sqlite3_config() ops
public static final int CONFIG_SINGLETHREAD = CApi.SQLITE_CONFIG_SINGLETHREAD;
public static final int CONFIG_MULTITHREAD = CApi.SQLITE_CONFIG_MULTITHREAD;
public static final int CONFIG_SERIALIZED = CApi.SQLITE_CONFIG_SERIALIZED;
// Encodings
public static final int UTF8 = CApi.SQLITE_UTF8;
public static final int UTF16 = CApi.SQLITE_UTF16;
public static final int UTF16LE = CApi.SQLITE_UTF16LE;
public static final int UTF16BE = CApi.SQLITE_UTF16BE;
/* We elide the UTF16_ALIGNED from this interface because it
is irrelevant for the Java interface. */
// SQL data type IDs
public static final int INTEGER = CApi.SQLITE_INTEGER;
public static final int FLOAT = CApi.SQLITE_FLOAT;
public static final int TEXT = CApi.SQLITE_TEXT;
public static final int BLOB = CApi.SQLITE_BLOB;
public static final int NULL = CApi.SQLITE_NULL;
// Authorizer codes.
public static final int DENY = CApi.SQLITE_DENY;
public static final int IGNORE = CApi.SQLITE_IGNORE;
public static final int CREATE_INDEX = CApi.SQLITE_CREATE_INDEX;
public static final int CREATE_TABLE = CApi.SQLITE_CREATE_TABLE;
public static final int CREATE_TEMP_INDEX = CApi.SQLITE_CREATE_TEMP_INDEX;
public static final int CREATE_TEMP_TABLE = CApi.SQLITE_CREATE_TEMP_TABLE;
public static final int CREATE_TEMP_TRIGGER = CApi.SQLITE_CREATE_TEMP_TRIGGER;
public static final int CREATE_TEMP_VIEW = CApi.SQLITE_CREATE_TEMP_VIEW;
public static final int CREATE_TRIGGER = CApi.SQLITE_CREATE_TRIGGER;
public static final int CREATE_VIEW = CApi.SQLITE_CREATE_VIEW;
public static final int DELETE = CApi.SQLITE_DELETE;
public static final int DROP_INDEX = CApi.SQLITE_DROP_INDEX;
public static final int DROP_TABLE = CApi.SQLITE_DROP_TABLE;
public static final int DROP_TEMP_INDEX = CApi.SQLITE_DROP_TEMP_INDEX;
public static final int DROP_TEMP_TABLE = CApi.SQLITE_DROP_TEMP_TABLE;
public static final int DROP_TEMP_TRIGGER = CApi.SQLITE_DROP_TEMP_TRIGGER;
public static final int DROP_TEMP_VIEW = CApi.SQLITE_DROP_TEMP_VIEW;
public static final int DROP_TRIGGER = CApi.SQLITE_DROP_TRIGGER;
public static final int DROP_VIEW = CApi.SQLITE_DROP_VIEW;
public static final int INSERT = CApi.SQLITE_INSERT;
public static final int PRAGMA = CApi.SQLITE_PRAGMA;
public static final int READ = CApi.SQLITE_READ;
public static final int SELECT = CApi.SQLITE_SELECT;
public static final int TRANSACTION = CApi.SQLITE_TRANSACTION;
public static final int UPDATE = CApi.SQLITE_UPDATE;
public static final int ATTACH = CApi.SQLITE_ATTACH;
public static final int DETACH = CApi.SQLITE_DETACH;
public static final int ALTER_TABLE = CApi.SQLITE_ALTER_TABLE;
public static final int REINDEX = CApi.SQLITE_REINDEX;
public static final int ANALYZE = CApi.SQLITE_ANALYZE;
public static final int CREATE_VTABLE = CApi.SQLITE_CREATE_VTABLE;
public static final int DROP_VTABLE = CApi.SQLITE_DROP_VTABLE;
public static final int FUNCTION = CApi.SQLITE_FUNCTION;
public static final int SAVEPOINT = CApi.SQLITE_SAVEPOINT;
public static final int RECURSIVE = CApi.SQLITE_RECURSIVE;
//! Used only by the open() factory functions.
private Sqlite(sqlite3 db){
this.db = db;
}
/** Maps org.sqlite.jni.capi.sqlite3 to Sqlite instances. */
private static final java.util.Map<org.sqlite.jni.capi.sqlite3, Sqlite> nativeToWrapper
= new java.util.HashMap<>();
/**
When any given thread is done using the SQLite library, calling
this will free up any native-side resources which may be
associated specifically with that thread. This is not strictly
necessary, in particular in applications which only use SQLite
from a single thread, but may help free some otherwise errant
resources.
Calling into SQLite from a given thread after this has been
called in that thread is harmless. The library will simply start
to re-cache certain state for that thread.
Contrariwise, failing to call this will effectively leak a small
amount of cached state for the thread, which may add up to
significant amounts if the application uses SQLite from many
threads.
This must never be called while actively using SQLite from this
thread, e.g. from within a query loop or a callback which is
operating on behalf of the library.
*/
static void uncacheThread(){
CApi.sqlite3_java_uncache_thread();
}
/**
Returns the Sqlite object associated with the given sqlite3
object, or null if there is no such mapping.
*/
static Sqlite fromNative(sqlite3 low){
synchronized(nativeToWrapper){
return nativeToWrapper.get(low);
}
}
/**
Returns a newly-opened db connection or throws SqliteException if
opening fails. All arguments are as documented for
sqlite3_open_v2().
Design question: do we want static factory functions or should
this be reformulated as a constructor?
*/
public static Sqlite open(String filename, int flags, String vfsName){
final OutputPointer.sqlite3 out = new OutputPointer.sqlite3();
final int rc = CApi.sqlite3_open_v2(filename, out, flags, vfsName);
final sqlite3 n = out.take();
if( 0!=rc ){
if( null==n ) throw new SqliteException(rc);
final SqliteException ex = new SqliteException(n);
n.close();
throw ex;
}
final Sqlite rv = new Sqlite(n);
synchronized(nativeToWrapper){
nativeToWrapper.put(n, rv);
}
runAutoExtensions(rv);
return rv;
}
public static Sqlite open(String filename, int flags){
return open(filename, flags, null);
}
public static Sqlite open(String filename){
return open(filename, OPEN_READWRITE|OPEN_CREATE, null);
}
public static String libVersion(){
return CApi.sqlite3_libversion();
}
public static int libVersionNumber(){
return CApi.sqlite3_libversion_number();
}
public static String libSourceId(){
return CApi.sqlite3_sourceid();
}
/**
Returns the value of the native library's build-time value of the
SQLITE_THREADSAFE build option.
*/
public static int libThreadsafe(){
return CApi.sqlite3_threadsafe();
}
/**
Analog to sqlite3_compileoption_get().
*/
public static String compileOptionGet(int n){
return CApi.sqlite3_compileoption_get(n);
}
/**
Analog to sqlite3_compileoption_used().
*/
public static boolean compileOptionUsed(String optName){
return CApi.sqlite3_compileoption_used(optName);
}
private static boolean hasNormalizeSql =
compileOptionUsed("ENABLE_NORMALIZE");
private static boolean hasSqlLog =
compileOptionUsed("ENABLE_SQLLOG");
/**
Throws UnsupportedOperationException if check is false.
flag is expected to be the name of an SQLITE_ENABLE_...
build flag.
*/
private static void checkSupported(boolean check, String flag){
if( !check ){
throw new UnsupportedOperationException(
"Library was built without "+flag
);
}
}
/**
Analog to sqlite3_complete().
*/
public static boolean isCompleteStatement(String sql){
switch(CApi.sqlite3_complete(sql)){
case 0: return false;
case CApi.SQLITE_MISUSE:
throw new IllegalArgumentException("Input may not be null.");
case CApi.SQLITE_NOMEM:
throw new OutOfMemoryError();
default:
return true;
}
}
public static int keywordCount(){
return CApi.sqlite3_keyword_count();
}
public static boolean keywordCheck(String word){
return CApi.sqlite3_keyword_check(word);
}
public static String keywordName(int index){
return CApi.sqlite3_keyword_name(index);
}
public static boolean strglob(String glob, String txt){
return 0==CApi.sqlite3_strglob(glob, txt);
}
public static boolean strlike(String glob, String txt, char escChar){
return 0==CApi.sqlite3_strlike(glob, txt, escChar);
}
/**
Output object for use with status() and libStatus().
*/
public static final class Status {
/** The current value for the requested status() or libStatus() metric. */
long current;
/** The peak value for the requested status() or libStatus() metric. */
long peak;
};
/**
As per sqlite3_status64(), but returns its current and high-water
results as a Status object. Throws if the first argument is
not one of the STATUS_... constants.
*/
public static Status libStatus(int op, boolean resetStats){
org.sqlite.jni.capi.OutputPointer.Int64 pCurrent =
new org.sqlite.jni.capi.OutputPointer.Int64();
org.sqlite.jni.capi.OutputPointer.Int64 pHighwater =
new org.sqlite.jni.capi.OutputPointer.Int64();
checkRcStatic( CApi.sqlite3_status64(op, pCurrent, pHighwater, resetStats) );
final Status s = new Status();
s.current = pCurrent.value;
s.peak = pHighwater.value;
return s;
}
/**
As per sqlite3_db_status(), but returns its current and
high-water results as a Status object. Throws if the first
argument is not one of the DBSTATUS_... constants or on any other
misuse.
*/
public Status status(int op, boolean resetStats){
org.sqlite.jni.capi.OutputPointer.Int32 pCurrent =
new org.sqlite.jni.capi.OutputPointer.Int32();
org.sqlite.jni.capi.OutputPointer.Int32 pHighwater =
new org.sqlite.jni.capi.OutputPointer.Int32();
checkRc( CApi.sqlite3_db_status(thisDb(), op, pCurrent, pHighwater, resetStats) );
final Status s = new Status();
s.current = pCurrent.value;
s.peak = pHighwater.value;
return s;
}
@Override public void close(){
if(null!=this.db){
synchronized(nativeToWrapper){
nativeToWrapper.remove(this.db);
}
this.db.close();
this.db = null;
}
}
/**
Returns this object's underlying native db handle, or null if
this instance has been closed. This is very specifically not
public.
*/
sqlite3 nativeHandle(){ return this.db; }
private sqlite3 thisDb(){
if( null==db || 0==db.getNativePointer() ){
throw new IllegalArgumentException("This database instance is closed.");
}
return this.db;
}
// private byte[] stringToUtf8(String s){
// return s==null ? null : s.getBytes(StandardCharsets.UTF_8);
// }
/**
If rc!=0, throws an SqliteException. If this db is currently
opened and has non-0 sqlite3_errcode(), the error state is
extracted from it, else only the string form of rc is used. It is
the caller's responsibility to filter out non-error codes such as
SQLITE_ROW and SQLITE_DONE before calling this.
As a special case, if rc is SQLITE_NOMEM, an OutOfMemoryError is
thrown.
*/
private void checkRc(int rc){
if( 0!=rc ){
if( CApi.SQLITE_NOMEM==rc ){
throw new OutOfMemoryError();
}else if( null==db || 0==CApi.sqlite3_errcode(db) ){
throw new SqliteException(rc);
}else{
throw new SqliteException(db);
}
}
}
/**
Like checkRc() but behaves as if that function were
called with a null db object.
*/
private static void checkRcStatic(int rc){
if( 0!=rc ){
if( CApi.SQLITE_NOMEM==rc ){
throw new OutOfMemoryError();
}else{
throw new SqliteException(rc);
}
}
}
/**
Toggles the use of extended result codes on or off. By default
they are turned off, but they can be enabled by default by
including the OPEN_EXRESCODE flag when opening a database.
Because this API reports db-side errors using exceptions,
enabling this may change the values returned by
SqliteException.errcode().
*/
public void useExtendedResultCodes(boolean on){
checkRc( CApi.sqlite3_extended_result_codes(thisDb(), on) );
}
/**
Analog to sqlite3_prepare_v3(), this prepares the first SQL
statement from the given input string and returns it as a
Stmt. It throws an SqliteException if preparation fails or an
IllegalArgumentException if the input is empty (e.g. contains
only comments or whitespace).
The first argument must be SQL input in UTF-8 encoding.
prepFlags must be 0 or a bitmask of the PREPARE_... constants.
For processing multiple statements from a single input, use
prepareMulti().
Design note: though the C-level API succeeds with a null
statement object for empty inputs, that approach is cumbersome to
use in higher-level APIs because every prepared statement has to
be checked for null before using it.
*/
public Stmt prepare(byte utf8Sql[], int prepFlags){
final OutputPointer.sqlite3_stmt out = new OutputPointer.sqlite3_stmt();
final int rc = CApi.sqlite3_prepare_v3(thisDb(), utf8Sql, prepFlags, out);
checkRc(rc);
final sqlite3_stmt q = out.take();
if( null==q ){
/* The C-level API treats input which is devoid of SQL
statements (e.g. all comments or an empty string) as success
but returns a NULL sqlite3_stmt object. In higher-level APIs,
wrapping a "successful NULL" object that way is tedious to
use because it forces clients and/or wrapper-level code to
check for that unusual case. In practice, higher-level
bindings are generally better-served by treating empty SQL
input as an error. */
throw new IllegalArgumentException("Input contains no SQL statements.");
}
return new Stmt(this, q);
}
/**
Equivalent to prepare(X, prepFlags), where X is
sql.getBytes(StandardCharsets.UTF_8).
*/
public Stmt prepare(String sql, int prepFlags){
return prepare( sql.getBytes(StandardCharsets.UTF_8), prepFlags );
}
/**
Equivalent to prepare(sql, 0).
*/
public Stmt prepare(String sql){
return prepare(sql, 0);
}
/**
Callback type for use with prepareMulti().
*/
public interface PrepareMulti {
/**
Gets passed a Stmt which it may handle in arbitrary ways.
Ownership of st is passed to this function. It must throw on
error.
*/
void call(Sqlite.Stmt st);
}
/**
A PrepareMulti implementation which calls another PrepareMulti
object and then finalizes its statement.
*/
public static class PrepareMultiFinalize implements PrepareMulti {
private final PrepareMulti pm;
/**
Proxies the given PrepareMulti via this object's call() method.
*/
public PrepareMultiFinalize(PrepareMulti proxy){
this.pm = proxy;
}
/**
Passes st to the call() method of the object this one proxies,
then finalizes st, propagating any exceptions from call() after
finalizing st.
*/
@Override public void call(Stmt st){
try{ pm.call(st); }
finally{ st.finalizeStmt(); }
}
}
/**
Equivalent to prepareMulti(sql,0,visitor).
*/
public void prepareMulti(String sql, PrepareMulti visitor){
prepareMulti( sql, 0, visitor );
}
/**
Equivalent to prepareMulti(X,prepFlags,visitor), where X is
sql.getBytes(StandardCharsets.UTF_8).
*/
public void prepareMulti(String sql, int prepFlags, PrepareMulti visitor){
prepareMulti(sql.getBytes(StandardCharsets.UTF_8), prepFlags, visitor);
}
/**
A variant of prepare() which can handle multiple SQL statements
in a single input string. For each statement in the given string,
the statement is passed to visitor.call() a single time, passing
ownership of the statement to that function. This function does
not step() or close() statements - those operations are left to
caller or the visitor function.
Unlike prepare(), this function does not fail if the input
contains only whitespace or SQL comments. In that case it is up
to the caller to arrange for that to be an error (if desired).
PrepareMultiFinalize offers a proxy which finalizes each
statement after it is passed to another client-defined visitor.
Be aware that certain legal SQL constructs may fail in the
preparation phase, before the corresponding statement can be
stepped. Most notably, authorizer checks which disallow access to
something in a statement behave that way.
*/
public void prepareMulti(byte sqlUtf8[], int prepFlags, PrepareMulti visitor){
int pos = 0, n = 1;
byte[] sqlChunk = sqlUtf8;
final org.sqlite.jni.capi.OutputPointer.sqlite3_stmt outStmt =
new org.sqlite.jni.capi.OutputPointer.sqlite3_stmt();
final org.sqlite.jni.capi.OutputPointer.Int32 oTail =
new org.sqlite.jni.capi.OutputPointer.Int32();
while( pos < sqlChunk.length ){
sqlite3_stmt stmt = null;
if( pos>0 ){
sqlChunk = java.util.Arrays.copyOfRange(sqlChunk, pos, sqlChunk.length);
}
if( 0==sqlChunk.length ) break;
checkRc(
CApi.sqlite3_prepare_v3(db, sqlChunk, prepFlags, outStmt, oTail)
);
pos = oTail.value;
stmt = outStmt.take();
if( null==stmt ){
/* empty statement, e.g. only comments or whitespace, was parsed. */
continue;
}
visitor.call(new Stmt(this, stmt));
}
}
public void createFunction(String name, int nArg, int eTextRep, ScalarFunction f){
int rc = CApi.sqlite3_create_function(thisDb(), name, nArg, eTextRep,
new SqlFunction.ScalarAdapter(f));
if( 0!=rc ) throw new SqliteException(db);
}
public void createFunction(String name, int nArg, ScalarFunction f){
this.createFunction(name, nArg, CApi.SQLITE_UTF8, f);
}
public void createFunction(String name, int nArg, int eTextRep, AggregateFunction f){
int rc = CApi.sqlite3_create_function(thisDb(), name, nArg, eTextRep,
new SqlFunction.AggregateAdapter(f));
if( 0!=rc ) throw new SqliteException(db);
}
public void createFunction(String name, int nArg, AggregateFunction f){
this.createFunction(name, nArg, CApi.SQLITE_UTF8, f);
}
public void createFunction(String name, int nArg, int eTextRep, WindowFunction f){
int rc = CApi.sqlite3_create_function(thisDb(), name, nArg, eTextRep,
new SqlFunction.WindowAdapter(f));
if( 0!=rc ) throw new SqliteException(db);
}
public void createFunction(String name, int nArg, WindowFunction f){
this.createFunction(name, nArg, CApi.SQLITE_UTF8, f);
}
public long changes(){
return CApi.sqlite3_changes64(thisDb());
}
public long totalChanges(){
return CApi.sqlite3_total_changes64(thisDb());
}
public long lastInsertRowId(){
return CApi.sqlite3_last_insert_rowid(thisDb());
}
public void setLastInsertRowId(long rowId){
CApi.sqlite3_set_last_insert_rowid(thisDb(), rowId);
}
public void interrupt(){
CApi.sqlite3_interrupt(thisDb());
}
public boolean isInterrupted(){
return CApi.sqlite3_is_interrupted(thisDb());
}
public boolean isAutoCommit(){
return CApi.sqlite3_get_autocommit(thisDb());
}
/**
Analog to sqlite3_txn_state(). Returns one of TXN_NONE, TXN_READ,
or TXN_WRITE to denote this database's current transaction state
for the given schema name (or the most restrictive state of any
schema if zSchema is null).
*/
public int transactionState(String zSchema){
return CApi.sqlite3_txn_state(thisDb(), zSchema);
}
/**
Analog to sqlite3_db_name(). Returns null if passed an unknown
index.
*/
public String dbName(int dbNdx){
return CApi.sqlite3_db_name(thisDb(), dbNdx);
}
/**
Analog to sqlite3_db_filename(). Returns null if passed an
unknown db name.
*/
public String dbFileName(String dbName){
return CApi.sqlite3_db_filename(thisDb(), dbName);
}
/**
Analog to sqlite3_db_config() for the call forms which take one
of the boolean-type db configuration flags (namely the
DBCONFIG_... constants defined in this class). On success it
returns the result of that underlying call. Throws on error.
*/
public boolean dbConfig(int op, boolean on){
org.sqlite.jni.capi.OutputPointer.Int32 pOut =
new org.sqlite.jni.capi.OutputPointer.Int32();
checkRc( CApi.sqlite3_db_config(thisDb(), op, on ? 1 : 0, pOut) );
return pOut.get()!=0;
}
/**
Analog to the variant of sqlite3_db_config() for configuring the
SQLITE_DBCONFIG_MAINDBNAME option. Throws on error.
*/
public void setMainDbName(String name){
checkRc(
CApi.sqlite3_db_config(thisDb(), CApi.SQLITE_DBCONFIG_MAINDBNAME,
name)
);
}
/**
Analog to sqlite3_db_readonly() but throws an SqliteException
with result code SQLITE_NOTFOUND if given an unknown database
name.
*/
public boolean readOnly(String dbName){
final int rc = CApi.sqlite3_db_readonly(thisDb(), dbName);
if( 0==rc ) return false;
else if( rc>0 ) return true;
throw new SqliteException(CApi.SQLITE_NOTFOUND);
}
/**
Analog to sqlite3_db_release_memory().
*/
public void releaseMemory(){
CApi.sqlite3_db_release_memory(thisDb());
}
/**
Analog to sqlite3_release_memory().
*/
public static int libReleaseMemory(int n){
return CApi.sqlite3_release_memory(n);
}
/**
Analog to sqlite3_limit(). limitId must be one of the
LIMIT_... constants.
Returns the old limit for the given option. If newLimit is
negative, it returns the old limit without modifying the limit.
If sqlite3_limit() returns a negative value, this function throws
an SqliteException with the SQLITE_RANGE result code but no
further error info (because that case does not qualify as a
db-level error). Such errors may indicate an invalid argument
value or an invalid range for newLimit (the underlying function
does not differentiate between those).
*/
public int limit(int limitId, int newLimit){
final int rc = CApi.sqlite3_limit(thisDb(), limitId, newLimit);
if( rc<0 ){
throw new SqliteException(CApi.SQLITE_RANGE);
}
return rc;
}
/**
Analog to sqlite3_errstr().
*/
static String errstr(int resultCode){
return CApi.sqlite3_errstr(resultCode);
}
/**
A wrapper object for use with tableColumnMetadata(). They are
created and populated only via that interface.
*/
public final class TableColumnMetadata {
Boolean pNotNull = null;
Boolean pPrimaryKey = null;
Boolean pAutoinc = null;
String pzCollSeq = null;
String pzDataType = null;
private TableColumnMetadata(){}
public String getDataType(){ return pzDataType; }
public String getCollation(){ return pzCollSeq; }
public boolean isNotNull(){ return pNotNull; }
public boolean isPrimaryKey(){ return pPrimaryKey; }
public boolean isAutoincrement(){ return pAutoinc; }
}
/**
Returns data about a database, table, and (optionally) column
(which may be null), as per sqlite3_table_column_metadata().
Throws if passed invalid arguments, else returns the result as a
new TableColumnMetadata object.
*/
TableColumnMetadata tableColumnMetadata(
String zDbName, String zTableName, String zColumnName
){
org.sqlite.jni.capi.OutputPointer.String pzDataType
= new org.sqlite.jni.capi.OutputPointer.String();
org.sqlite.jni.capi.OutputPointer.String pzCollSeq
= new org.sqlite.jni.capi.OutputPointer.String();
org.sqlite.jni.capi.OutputPointer.Bool pNotNull
= new org.sqlite.jni.capi.OutputPointer.Bool();
org.sqlite.jni.capi.OutputPointer.Bool pPrimaryKey
= new org.sqlite.jni.capi.OutputPointer.Bool();
org.sqlite.jni.capi.OutputPointer.Bool pAutoinc
= new org.sqlite.jni.capi.OutputPointer.Bool();
final int rc = CApi.sqlite3_table_column_metadata(
thisDb(), zDbName, zTableName, zColumnName,
pzDataType, pzCollSeq, pNotNull, pPrimaryKey, pAutoinc
);
checkRc(rc);
TableColumnMetadata rv = new TableColumnMetadata();
rv.pzDataType = pzDataType.value;
rv.pzCollSeq = pzCollSeq.value;
rv.pNotNull = pNotNull.value;
rv.pPrimaryKey = pPrimaryKey.value;
rv.pAutoinc = pAutoinc.value;
return rv;
}
public interface TraceCallback {
/**
Called by sqlite3 for various tracing operations, as per
sqlite3_trace_v2(). Note that this interface elides the 2nd
argument to the native trace callback, as that role is better
filled by instance-local state.
<p>These callbacks may throw, in which case their exceptions are
converted to C-level error information.
<p>The 2nd argument to this function, if non-null, will be a an
Sqlite or Sqlite.Stmt object, depending on the first argument
(see below).
<p>The final argument to this function is the "X" argument
documented for sqlite3_trace() and sqlite3_trace_v2(). Its type
depends on value of the first argument:
<p>- SQLITE_TRACE_STMT: pNative is a Sqlite.Stmt. pX is a String
containing the prepared SQL.
<p>- SQLITE_TRACE_PROFILE: pNative is a sqlite3_stmt. pX is a Long
holding an approximate number of nanoseconds the statement took
to run.
<p>- SQLITE_TRACE_ROW: pNative is a sqlite3_stmt. pX is null.
<p>- SQLITE_TRACE_CLOSE: pNative is a sqlite3. pX is null.
*/
void call(int traceFlag, Object pNative, Object pX);
}
/**
Analog to sqlite3_trace_v2(). traceMask must be a mask of the
TRACE_... constants. Pass a null callback to remove tracing.
Throws on error.
*/
public void trace(int traceMask, TraceCallback callback){
final Sqlite self = this;
final org.sqlite.jni.capi.TraceV2Callback tc =
(null==callback) ? null : new org.sqlite.jni.capi.TraceV2Callback(){
@SuppressWarnings("unchecked")
@Override public int call(int flag, Object pNative, Object pX){
switch(flag){
case TRACE_ROW:
case TRACE_PROFILE:
case TRACE_STMT:
callback.call(flag, Sqlite.Stmt.fromNative((sqlite3_stmt)pNative), pX);
break;
case TRACE_CLOSE:
callback.call(flag, self, pX);
break;
}
return 0;
}
};
checkRc( CApi.sqlite3_trace_v2(thisDb(), traceMask, tc) );
};
/**
Corresponds to the sqlite3_stmt class. Use Sqlite.prepare() to
create new instances.
*/
public static final class Stmt implements AutoCloseable {
private Sqlite _db = null;
private sqlite3_stmt stmt = null;
/** Only called by the prepare() factory functions. */
Stmt(Sqlite db, sqlite3_stmt stmt){
this._db = db;
this.stmt = stmt;
synchronized(nativeToWrapper){
nativeToWrapper.put(this.stmt, this);
}
}
sqlite3_stmt nativeHandle(){
return stmt;
}
/** Maps org.sqlite.jni.capi.sqlite3_stmt to Stmt instances. */
private static final java.util.Map<org.sqlite.jni.capi.sqlite3_stmt, Stmt> nativeToWrapper
= new java.util.HashMap<>();
/**
Returns the Stmt object associated with the given sqlite3_stmt
object, or null if there is no such mapping.
*/
static Stmt fromNative(sqlite3_stmt low){
synchronized(nativeToWrapper){
return nativeToWrapper.get(low);
}
}
/**
If this statement is still opened, its low-level handle is
returned, else an IllegalArgumentException is thrown.
*/
private sqlite3_stmt thisStmt(){
if( null==stmt || 0==stmt.getNativePointer() ){
throw new IllegalArgumentException("This Stmt has been finalized.");
}
return stmt;
}
/** Throws if n is out of range of this statement's result column
count. Intended to be used by the columnXyz() methods. */
private sqlite3_stmt checkColIndex(int n){
if(n<0 || n>=columnCount()){
throw new IllegalArgumentException("Column index "+n+" is out of range.");
}
return thisStmt();
}
/**
Corresponds to sqlite3_finalize(), but we cannot override the
name finalize() here because this one requires a different
signature. It does not throw on error here because "destructors
do not throw." If it returns non-0, the object is still
finalized, but the result code is an indication that something
went wrong in a prior call into the statement's API, as
documented for sqlite3_finalize().
*/
public int finalizeStmt(){
int rc = 0;
if( null!=stmt ){
synchronized(nativeToWrapper){
nativeToWrapper.remove(this.stmt);
}
CApi.sqlite3_finalize(stmt);
stmt = null;
_db = null;
}
return rc;
}
@Override public void close(){
finalizeStmt();
}
/**
Throws if rc is any value other than 0, SQLITE_ROW, or
SQLITE_DONE, else returns rc. Error state for the exception is
extracted from this statement object (if it's opened) or the
string form of rc.
*/
private int checkRc(int rc){
switch(rc){
case 0:
case CApi.SQLITE_ROW:
case CApi.SQLITE_DONE: return rc;
default:
if( null==stmt ) throw new SqliteException(rc);
else throw new SqliteException(this);
}
}
/**
Works like sqlite3_step() but returns true for SQLITE_ROW,
false for SQLITE_DONE, and throws SqliteException for any other
result.
*/
public boolean step(){
switch(checkRc(CApi.sqlite3_step(thisStmt()))){
case CApi.SQLITE_ROW: return true;
case CApi.SQLITE_DONE: return false;
default:
throw new IllegalStateException(
"This \"cannot happen\": all possible result codes were checked already."
);
}
}
/**
Works like sqlite3_step(), returning the same result codes as
that function unless throwOnError is true, in which case it
will throw an SqliteException for any result codes other than
Sqlite.ROW or Sqlite.DONE.
The utility of this overload over the no-argument one is the
ability to handle BUSY and LOCKED errors more easily.
*/
public int step(boolean throwOnError){
final int rc = (null==stmt)
? Sqlite.MISUSE
: CApi.sqlite3_step(stmt);
return throwOnError ? checkRc(rc) : rc;
}
/**
Returns the Sqlite which prepared this statement, or null if
this statement has been finalized.
*/
public Sqlite getDb(){ return this._db; }
/**
Works like sqlite3_reset() but throws on error.
*/
public void reset(){
checkRc(CApi.sqlite3_reset(thisStmt()));
}
public boolean isBusy(){
return CApi.sqlite3_stmt_busy(thisStmt());
}
public boolean isReadOnly(){
return CApi.sqlite3_stmt_readonly(thisStmt());
}
public String sql(){
return CApi.sqlite3_sql(thisStmt());
}
public String expandedSql(){
return CApi.sqlite3_expanded_sql(thisStmt());
}
/**
Analog to sqlite3_stmt_explain() but throws if op is invalid.
*/
public void explain(int op){
checkRc(CApi.sqlite3_stmt_explain(thisStmt(), op));
}
/**
Analog to sqlite3_stmt_isexplain().
*/
public int isExplain(){
return CApi.sqlite3_stmt_isexplain(thisStmt());
}
/**
Analog to sqlite3_normalized_sql(), but throws
UnsupportedOperationException if the library was built without
the SQLITE_ENABLE_NORMALIZE flag.
*/
public String normalizedSql(){
Sqlite.checkSupported(hasNormalizeSql, "SQLITE_ENABLE_NORMALIZE");
return CApi.sqlite3_normalized_sql(thisStmt());
}
public void clearBindings(){
CApi.sqlite3_clear_bindings( thisStmt() );
}
public void bindInt(int ndx, int val){
checkRc(CApi.sqlite3_bind_int(thisStmt(), ndx, val));
}
public void bindInt64(int ndx, long val){
checkRc(CApi.sqlite3_bind_int64(thisStmt(), ndx, val));
}
public void bindDouble(int ndx, double val){
checkRc(CApi.sqlite3_bind_double(thisStmt(), ndx, val));
}
public void bindObject(int ndx, Object o){
checkRc(CApi.sqlite3_bind_java_object(thisStmt(), ndx, o));
}
public void bindNull(int ndx){
checkRc(CApi.sqlite3_bind_null(thisStmt(), ndx));
}
public int bindParameterCount(){
return CApi.sqlite3_bind_parameter_count(thisStmt());
}
public int bindParameterIndex(String paramName){
return CApi.sqlite3_bind_parameter_index(thisStmt(), paramName);
}
public String bindParameterName(int ndx){
return CApi.sqlite3_bind_parameter_name(thisStmt(), ndx);
}
public void bindText(int ndx, byte[] utf8){
checkRc(CApi.sqlite3_bind_text(thisStmt(), ndx, utf8));
}
public void bindText(int ndx, String asUtf8){
checkRc(CApi.sqlite3_bind_text(thisStmt(), ndx, asUtf8));
}
public void bindText16(int ndx, byte[] utf16){
checkRc(CApi.sqlite3_bind_text16(thisStmt(), ndx, utf16));
}
public void bindText16(int ndx, String asUtf16){
checkRc(CApi.sqlite3_bind_text16(thisStmt(), ndx, asUtf16));
}
public void bindZeroBlob(int ndx, int n){
checkRc(CApi.sqlite3_bind_zeroblob(thisStmt(), ndx, n));
}
public void bindBlob(int ndx, byte[] bytes){
checkRc(CApi.sqlite3_bind_blob(thisStmt(), ndx, bytes));
}
public byte[] columnBlob(int ndx){
return CApi.sqlite3_column_blob( checkColIndex(ndx), ndx );
}
public byte[] columnText(int ndx){
return CApi.sqlite3_column_text( checkColIndex(ndx), ndx );
}
public String columnText16(int ndx){
return CApi.sqlite3_column_text16( checkColIndex(ndx), ndx );
}
public int columnBytes(int ndx){
return CApi.sqlite3_column_bytes( checkColIndex(ndx), ndx );
}
public int columnBytes16(int ndx){
return CApi.sqlite3_column_bytes16( checkColIndex(ndx), ndx );
}
public int columnInt(int ndx){
return CApi.sqlite3_column_int( checkColIndex(ndx), ndx );
}
public long columnInt64(int ndx){
return CApi.sqlite3_column_int64( checkColIndex(ndx), ndx );
}
public double columnDouble(int ndx){
return CApi.sqlite3_column_double( checkColIndex(ndx), ndx );
}
public int columnType(int ndx){
return CApi.sqlite3_column_type( checkColIndex(ndx), ndx );
}
public String columnDeclType(int ndx){
return CApi.sqlite3_column_decltype( checkColIndex(ndx), ndx );
}
/**
Analog to sqlite3_column_count() but throws if this statement
has been finalized.
*/
public int columnCount(){
/* We cannot reliably cache the column count in a class
member because an ALTER TABLE from a separate statement
can invalidate that count and we have no way, short of
installing a COMMIT handler or the like, of knowing when
to re-read it. We cannot install such a handler without
interfering with a client's ability to do so. */
return CApi.sqlite3_column_count(thisStmt());
}
public int columnDataCount(){
return CApi.sqlite3_data_count( thisStmt() );
}
public Object columnObject(int ndx){
return CApi.sqlite3_column_java_object( checkColIndex(ndx), ndx );
}
public <T> T columnObject(int ndx, Class<T> type){
return CApi.sqlite3_column_java_object( checkColIndex(ndx), ndx, type );
}
public String columnName(int ndx){
return CApi.sqlite3_column_name( checkColIndex(ndx), ndx );
}
public String columnDatabaseName(int ndx){
return CApi.sqlite3_column_database_name( checkColIndex(ndx), ndx );
}
public String columnOriginName(int ndx){
return CApi.sqlite3_column_origin_name( checkColIndex(ndx), ndx );
}
public String columnTableName(int ndx){
return CApi.sqlite3_column_table_name( checkColIndex(ndx), ndx );
}
} /* Stmt class */
/**
Interface for auto-extensions, as per the
sqlite3_auto_extension() API.
Design note: the chicken/egg timing of auto-extension execution
requires that this feature be entirely re-implemented in Java
because the C-level API has no access to the Sqlite type so
cannot pass on an object of that type while the database is being
opened. One side effect of this reimplementation is that this
class's list of auto-extensions is 100% independent of the
C-level list so, e.g., clearAutoExtensions() will have no effect
on auto-extensions added via the C-level API and databases opened
from that level of API will not be passed to this level's
AutoExtension instances.
*/
public interface AutoExtension {
public void call(Sqlite db);
}
private static final java.util.Set<AutoExtension> autoExtensions =
new java.util.LinkedHashSet<>();
/**
Passes db to all auto-extensions. If any one of them throws,
db.close() is called before the exception is propagated.
*/
private static void runAutoExtensions(Sqlite db){
AutoExtension list[];
synchronized(autoExtensions){
/* Avoid that modifications to the AutoExtension list from within
auto-extensions affect this execution of this list. */
list = autoExtensions.toArray(new AutoExtension[0]);
}
try {
for( AutoExtension ax : list ) ax.call(db);
}catch(Exception e){
db.close();
throw e;
}
}
/**
Analog to sqlite3_auto_extension(), adds the given object to the
list of auto-extensions if it is not already in that list. The
given object will be run as part of Sqlite.open(), and passed the
being-opened database. If the extension throws then open() will
fail.
This API does not guaranty whether or not manipulations made to
the auto-extension list from within auto-extension callbacks will
affect the current traversal of the auto-extension list. Whether
or not they do is unspecified and subject to change between
versions. e.g. if an AutoExtension calls addAutoExtension(),
whether or not the new extension will be run on the being-opened
database is undefined.
Note that calling Sqlite.open() from an auto-extension will
necessarily result in recursion loop and (eventually) a stack
overflow.
*/
public static void addAutoExtension( AutoExtension e ){
if( null==e ){
throw new IllegalArgumentException("AutoExtension may not be null.");
}
synchronized(autoExtensions){
autoExtensions.add(e);
}
}
/**
Removes the given object from the auto-extension list if it is in
that list, otherwise this has no side-effects beyond briefly
locking that list.
*/
public static void removeAutoExtension( AutoExtension e ){
synchronized(autoExtensions){
autoExtensions.remove(e);
}
}
/**
Removes all auto-extensions which were added via addAutoExtension().
*/
public static void clearAutoExtensions(){
synchronized(autoExtensions){
autoExtensions.clear();
}
}
/**
Encapsulates state related to the sqlite3 backup API. Use
Sqlite.initBackup() to create new instances.
*/
public static final class Backup implements AutoCloseable {
private sqlite3_backup b = null;
private Sqlite dbTo = null;
private Sqlite dbFrom = null;
Backup(Sqlite dbDest, String schemaDest,Sqlite dbSrc, String schemaSrc){
this.dbTo = dbDest;
this.dbFrom = dbSrc;
b = CApi.sqlite3_backup_init(dbDest.nativeHandle(), schemaDest,
dbSrc.nativeHandle(), schemaSrc);
if(null==b) toss();
}
private void toss(){
int rc = CApi.sqlite3_errcode(dbTo.nativeHandle());
if(0!=rc) throw new SqliteException(dbTo);
rc = CApi.sqlite3_errcode(dbFrom.nativeHandle());
if(0!=rc) throw new SqliteException(dbFrom);
throw new SqliteException(CApi.SQLITE_ERROR);
}
private sqlite3_backup getNative(){
if( null==b ) throw new IllegalStateException("This Backup is already closed.");
return b;
}
/**
If this backup is still active, this completes the backup and
frees its native resources, otherwise it this is a no-op.
*/
public void finish(){
if( null!=b ){
CApi.sqlite3_backup_finish(b);
b = null;
dbTo = null;
dbFrom = null;
}
}
/** Equivalent to finish(). */
@Override public void close(){
this.finish();
}
/**
Analog to sqlite3_backup_step(). Returns 0 if stepping succeeds
or, Sqlite.DONE if the end is reached, Sqlite.BUSY if one of
the databases is busy, Sqlite.LOCKED if one of the databases is
locked, and throws for any other result code or if this object
has been closed. Note that BUSY and LOCKED are not necessarily
permanent errors, so do not trigger an exception.
*/
public int step(int pageCount){
final int rc = CApi.sqlite3_backup_step(getNative(), pageCount);
switch(rc){
case 0:
case Sqlite.DONE:
case Sqlite.BUSY:
case Sqlite.LOCKED:
return rc;
default:
toss();
return CApi.SQLITE_ERROR/*not reached*/;
}
}
/**
Analog to sqlite3_backup_pagecount().
*/
public int pageCount(){
return CApi.sqlite3_backup_pagecount(getNative());
}
/**
Analog to sqlite3_backup_remaining().
*/
public int remaining(){
return CApi.sqlite3_backup_remaining(getNative());
}
}
/**
Analog to sqlite3_backup_init(). If schemaSrc is null, "main" is
assumed. Throws if either this db or dbSrc (the source db) are
not opened, if either of schemaDest or schemaSrc are null, or if
the underlying call to sqlite3_backup_init() fails.
The returned object must eventually be cleaned up by either
arranging for it to be auto-closed (e.g. using
try-with-resources) or by calling its finish() method.
*/
public Backup initBackup(String schemaDest, Sqlite dbSrc, String schemaSrc){
thisDb();
dbSrc.thisDb();
if( null==schemaSrc || null==schemaDest ){
throw new IllegalArgumentException(
"Neither the source nor destination schema name may be null."
);
}
return new Backup(this, schemaDest, dbSrc, schemaSrc);
}
/**
Callback type for use with createCollation().
*/
public interface Collation {
/**
Called by the SQLite core to compare inputs. Implementations
must compare its two arguments using memcmp(3) semantics.
Warning: the SQLite core has no mechanism for reporting errors
from custom collations and its workflow does not accommodate
propagation of exceptions from callbacks. Any exceptions thrown
from collations will be silently supressed and sorting results
will be unpredictable.
*/
int call(byte[] lhs, byte[] rhs);
}
/**
Analog to sqlite3_create_collation().
Throws if name is null or empty, c is null, or the encoding flag
is invalid. The encoding must be one of the UTF8, UTF16, UTF16LE,
or UTF16BE constants.
*/
public void createCollation(String name, int encoding, Collation c){
thisDb();
if( null==name || 0==name.length()){
throw new IllegalArgumentException("Collation name may not be null or empty.");
}
if( null==c ){
throw new IllegalArgumentException("Collation may not be null.");
}
switch(encoding){
case UTF8:
case UTF16:
case UTF16LE:
case UTF16BE:
break;
default:
throw new IllegalArgumentException("Invalid Collation encoding.");
}
checkRc(
CApi.sqlite3_create_collation(
thisDb(), name, encoding, new org.sqlite.jni.capi.CollationCallback(){
@Override public int call(byte[] lhs, byte[] rhs){
try{return c.call(lhs, rhs);}
catch(Exception e){return 0;}
}
@Override public void xDestroy(){}
}
)
);
}
/**
Callback for use with onCollationNeeded().
*/
public interface CollationNeeded {
/**
Must behave as documented for the callback for
sqlite3_collation_needed().
Warning: the C API has no mechanism for reporting or
propagating errors from this callback, so any exceptions it
throws are suppressed.
*/
void call(Sqlite db, int encoding, String collationName);
}
/**
Sets up the given object to be called by the SQLite core when it
encounters a collation name which it does not know. Pass a null
object to disconnect the object from the core. This replaces any
existing collation-needed loader, or is a no-op if the given
object is already registered. Throws if registering the loader
fails.
*/
public void onCollationNeeded( CollationNeeded cn ){
org.sqlite.jni.capi.CollationNeededCallback cnc = null;
if( null!=cn ){
cnc = new org.sqlite.jni.capi.CollationNeededCallback(){
@Override public void call(sqlite3 db, int encoding, String collationName){
final Sqlite xdb = Sqlite.fromNative(db);
if(null!=xdb) cn.call(xdb, encoding, collationName);
}
};
}
checkRc( CApi.sqlite3_collation_needed(thisDb(), cnc) );
}
/**
Callback for use with busyHandler().
*/
public interface BusyHandler {
/**
Must function as documented for the C-level
sqlite3_busy_handler() callback argument, minus the (void*)
argument the C-level function requires.
If this function throws, it is translated to a database-level
error.
*/
int call(int n);
}
/**
Analog to sqlite3_busy_timeout().
*/
public void setBusyTimeout(int ms){
checkRc(CApi.sqlite3_busy_timeout(thisDb(), ms));
}
/**
Analog to sqlite3_busy_handler(). If b is null then any
current handler is cleared.
*/
public void setBusyHandler( BusyHandler b ){
org.sqlite.jni.capi.BusyHandlerCallback bhc = null;
if( null!=b ){
bhc = new org.sqlite.jni.capi.BusyHandlerCallback(){
@Override public int call(int n){
return b.call(n);
}
};
}
checkRc( CApi.sqlite3_busy_handler(thisDb(), bhc) );
}
public interface CommitHook {
/**
Must behave as documented for the C-level sqlite3_commit_hook()
callback. If it throws, the exception is translated into
a db-level error.
*/
int call();
}
/**
A level of indirection to permit setCommitHook() to have similar
semantics as the C API, returning the previous hook. The caveat
is that if the low-level API is used to install a hook, it will
have a different hook type than Sqlite.CommitHook so
setCommitHook() will return null instead of that object.
*/
private static class CommitHookProxy
implements org.sqlite.jni.capi.CommitHookCallback {
final CommitHook commitHook;
CommitHookProxy(CommitHook ch){
this.commitHook = ch;
}
@Override public int call(){
return commitHook.call();
}
}
/**
Analog to sqlite3_commit_hook(). Returns the previous hook, if
any (else null). Throws if this db is closed.
Minor caveat: if a commit hook is set on this object's underlying
db handle using the lower-level SQLite API, this function may
return null when replacing it, despite there being a hook,
because it will have a different callback type. So long as the
handle is only manipulated via the high-level API, this caveat
does not apply.
*/
public CommitHook setCommitHook( CommitHook c ){
CommitHookProxy chp = null;
if( null!=c ){
chp = new CommitHookProxy(c);
}
final org.sqlite.jni.capi.CommitHookCallback rv =
CApi.sqlite3_commit_hook(thisDb(), chp);
return (rv instanceof CommitHookProxy)
? ((CommitHookProxy)rv).commitHook
: null;
}
public interface RollbackHook {
/**
Must behave as documented for the C-level sqlite3_rollback_hook()
callback. If it throws, the exception is translated into
a db-level error.
*/
void call();
}
/**
A level of indirection to permit setRollbackHook() to have similar
semantics as the C API, returning the previous hook. The caveat
is that if the low-level API is used to install a hook, it will
have a different hook type than Sqlite.RollbackHook so
setRollbackHook() will return null instead of that object.
*/
private static class RollbackHookProxy
implements org.sqlite.jni.capi.RollbackHookCallback {
final RollbackHook rollbackHook;
RollbackHookProxy(RollbackHook ch){
this.rollbackHook = ch;
}
@Override public void call(){rollbackHook.call();}
}
/**
Analog to sqlite3_rollback_hook(). Returns the previous hook, if
any (else null). Throws if this db is closed.
Minor caveat: if a rollback hook is set on this object's underlying
db handle using the lower-level SQLite API, this function may
return null when replacing it, despite there being a hook,
because it will have a different callback type. So long as the
handle is only manipulated via the high-level API, this caveat
does not apply.
*/
public RollbackHook setRollbackHook( RollbackHook c ){
RollbackHookProxy chp = null;
if( null!=c ){
chp = new RollbackHookProxy(c);
}
final org.sqlite.jni.capi.RollbackHookCallback rv =
CApi.sqlite3_rollback_hook(thisDb(), chp);
return (rv instanceof RollbackHookProxy)
? ((RollbackHookProxy)rv).rollbackHook
: null;
}
public interface UpdateHook {
/**
Must function as described for the C-level sqlite3_update_hook()
callback.
*/
void call(int opId, String dbName, String tableName, long rowId);
}
/**
A level of indirection to permit setUpdateHook() to have similar
semantics as the C API, returning the previous hook. The caveat
is that if the low-level API is used to install a hook, it will
have a different hook type than Sqlite.UpdateHook so
setUpdateHook() will return null instead of that object.
*/
private static class UpdateHookProxy
implements org.sqlite.jni.capi.UpdateHookCallback {
final UpdateHook updateHook;
UpdateHookProxy(UpdateHook ch){
this.updateHook = ch;
}
@Override public void call(int opId, String dbName, String tableName, long rowId){
updateHook.call(opId, dbName, tableName, rowId);
}
}
/**
Analog to sqlite3_update_hook(). Returns the previous hook, if
any (else null). Throws if this db is closed.
Minor caveat: if a update hook is set on this object's underlying
db handle using the lower-level SQLite API, this function may
return null when replacing it, despite there being a hook,
because it will have a different callback type. So long as the
handle is only manipulated via the high-level API, this caveat
does not apply.
*/
public UpdateHook setUpdateHook( UpdateHook c ){
UpdateHookProxy chp = null;
if( null!=c ){
chp = new UpdateHookProxy(c);
}
final org.sqlite.jni.capi.UpdateHookCallback rv =
CApi.sqlite3_update_hook(thisDb(), chp);
return (rv instanceof UpdateHookProxy)
? ((UpdateHookProxy)rv).updateHook
: null;
}
/**
Callback interface for use with setProgressHandler().
*/
public interface ProgressHandler {
/**
Must behave as documented for the C-level sqlite3_progress_handler()
callback. If it throws, the exception is translated into
a db-level error.
*/
int call();
}
/**
Analog to sqlite3_progress_handler(), sets the current progress
handler or clears it if p is null.
Note that this API, in contrast to setUpdateHook(),
setRollbackHook(), and setCommitHook(), cannot return the
previous handler. That inconsistency is part of the lower-level C
API.
*/
public void setProgressHandler( int n, ProgressHandler p ){
org.sqlite.jni.capi.ProgressHandlerCallback phc = null;
if( null!=p ){
phc = new org.sqlite.jni.capi.ProgressHandlerCallback(){
@Override public int call(){ return p.call(); }
};
}
CApi.sqlite3_progress_handler( thisDb(), n, phc );
}
/**
Callback for use with setAuthorizer().
*/
public interface Authorizer {
/**
Must function as described for the C-level
sqlite3_set_authorizer() callback. If it throws, the error is
converted to a db-level error and the exception is suppressed.
*/
int call(int opId, String s1, String s2, String s3, String s4);
}
/**
Analog to sqlite3_set_authorizer(), this sets the current
authorizer callback, or clears if it passed null.
*/
public void setAuthorizer( Authorizer a ) {
org.sqlite.jni.capi.AuthorizerCallback ac = null;
if( null!=a ){
ac = new org.sqlite.jni.capi.AuthorizerCallback(){
@Override public int call(int opId, String s1, String s2, String s3, String s4){
return a.call(opId, s1, s2, s3, s4);
}
};
}
checkRc( CApi.sqlite3_set_authorizer( thisDb(), ac ) );
}
/**
Object type for use with blobOpen()
*/
public final class Blob implements AutoCloseable {
private Sqlite db;
private sqlite3_blob b;
Blob(Sqlite db, sqlite3_blob b){
this.db = db;
this.b = b;
}
/**
If this blob is still opened, its low-level handle is
returned, else an IllegalArgumentException is thrown.
*/
private sqlite3_blob thisBlob(){
if( null==b || 0==b.getNativePointer() ){
throw new IllegalArgumentException("This Blob has been finalized.");
}
return b;
}
/**
Analog to sqlite3_blob_close().
*/
@Override public void close(){
if( null!=b ){
CApi.sqlite3_blob_close(b);
b = null;
db = null;
}
}
/**
Throws if the JVM does not have JNI-level support for
ByteBuffer.
*/
private void checkNio(){
if( !Sqlite.JNI_SUPPORTS_NIO ){
throw new UnsupportedOperationException(
"This JVM does not support JNI access to ByteBuffer."
);
}
}
/**
Analog to sqlite3_blob_reopen() but throws on error.
*/
public void reopen(long newRowId){
db.checkRc( CApi.sqlite3_blob_reopen(thisBlob(), newRowId) );
}
/**
Analog to sqlite3_blob_write() but throws on error.
*/
public void write( byte[] bytes, int atOffset ){
db.checkRc( CApi.sqlite3_blob_write(thisBlob(), bytes, atOffset) );
}
/**
Analog to sqlite3_blob_read() but throws on error.
*/
public void read( byte[] dest, int atOffset ){
db.checkRc( CApi.sqlite3_blob_read(thisBlob(), dest, atOffset) );
}
/**
Analog to sqlite3_blob_bytes().
*/
public int bytes(){
return CApi.sqlite3_blob_bytes(thisBlob());
}
}
/**
Analog to sqlite3_blob_open(). Returns a Blob object for the
given database, table, column, and rowid. The blob is opened for
read-write mode if writeable is true, else it is read-only.
The returned object must eventually be freed, before this
database is closed, by either arranging for it to be auto-closed
or calling its close() method.
Throws on error.
*/
public Blob blobOpen(String dbName, String tableName, String columnName,
long iRow, boolean writeable){
final OutputPointer.sqlite3_blob out = new OutputPointer.sqlite3_blob();
checkRc(
CApi.sqlite3_blob_open(thisDb(), dbName, tableName, columnName,
iRow, writeable ? 1 : 0, out)
);
return new Blob(this, out.take());
}
/**
Callback for use with libConfigLog().
*/
public interface ConfigLog {
/**
Must function as described for a C-level callback for
sqlite3_config()'s SQLITE_CONFIG_LOG callback, with the slight
signature change. Any exceptions thrown from this callback are
necessarily suppressed.
*/
void call(int errCode, String msg);
}
/**
Analog to sqlite3_config() with the SQLITE_CONFIG_LOG option,
this sets or (if log is null) clears the current logger.
*/
public static void libConfigLog(ConfigLog log){
final org.sqlite.jni.capi.ConfigLogCallback l =
null==log
? null
: new org.sqlite.jni.capi.ConfigLogCallback() {
@Override public void call(int errCode, String msg){
log.call(errCode, msg);
}
};
checkRcStatic(CApi.sqlite3_config(l));
}
/**
Callback for use with libConfigSqlLog().
*/
public interface ConfigSqlLog {
/**
Must function as described for a C-level callback for
sqlite3_config()'s SQLITE_CONFIG_SQLLOG callback, with the
slight signature change. Any exceptions thrown from this
callback are necessarily suppressed.
*/
void call(Sqlite db, String msg, int msgType);
}
/**
Analog to sqlite3_config() with the SQLITE_CONFIG_SQLLOG option,
this sets or (if log is null) clears the current logger.
If SQLite is built without SQLITE_ENABLE_SQLLOG defined then this
will throw an UnsupportedOperationException.
*/
public static void libConfigSqlLog(ConfigSqlLog log){
Sqlite.checkSupported(hasNormalizeSql, "SQLITE_ENABLE_SQLLOG");
final org.sqlite.jni.capi.ConfigSqlLogCallback l =
null==log
? null
: new org.sqlite.jni.capi.ConfigSqlLogCallback() {
@Override public void call(sqlite3 db, String msg, int msgType){
try{
log.call(fromNative(db), msg, msgType);
}catch(Exception e){
/* Suppressed */
}
}
};
checkRcStatic(CApi.sqlite3_config(l));
}
/**
Analog to the C-level sqlite3_config() with one of the
SQLITE_CONFIG_... constants defined as CONFIG_... in this
class. Throws on error, including passing of an unknown option or
if a specified option is not supported by the underlying build of
the SQLite library.
*/
public static void libConfigOp( int op ){
checkRcStatic(CApi.sqlite3_config(op));
}
}