diff --git a/ext/jni/src/c/sqlite3-jni.c b/ext/jni/src/c/sqlite3-jni.c index 74a518c6e6..bc15212251 100644 --- a/ext/jni/src/c/sqlite3-jni.c +++ b/ext/jni/src/c/sqlite3-jni.c @@ -113,14 +113,6 @@ # define SQLITE_THREADSAFE 1 #endif -/* -** 2023-08-25: initial attempts at running with SQLITE_THREADSAFE=0 -** lead to as-yet-uninvestigated bad reference errors from JNI. -*/ -#if 0 && SQLITE_THREADSAFE==0 -# error "This code currently requires SQLITE_THREADSAFE!=0." -#endif - /**********************************************************************/ /* SQLITE_USE_... */ #ifndef SQLITE_USE_URI @@ -132,9 +124,11 @@ ** Which sqlite3.c we're using needs to be configurable to enable ** building against a custom copy, e.g. the SEE variant. We have to ** include sqlite3.c, as opposed to sqlite3.h, in order to get access -** to SQLITE_MAX_... and friends. This increases the rebuild time -** considerably but we need this in order to keep the exported values -** of SQLITE_MAX_... and SQLITE_LIMIT_... in sync with the C build. +** to some interal details like SQLITE_MAX_... and friends. This +** increases the rebuild time considerably but we need this in order +** to access some internal functionality and keep the to-Java-exported +** values of SQLITE_MAX_... and SQLITE_LIMIT_... in sync with the C +** build. */ #ifndef SQLITE_C # define SQLITE_C sqlite3.c @@ -452,7 +446,8 @@ struct S3JniDb { #endif S3JniDb * pNext /* Next entry in SJG.perDb.aFree */; }; -#define S3JniDb_clientdata_key "S3JniDb" + +static const char * const S3JniDb_clientdata_key = "S3JniDb"; #define S3JniDb_from_clientdata(pDb) \ (pDb ? sqlite3_get_clientdata(pDb, S3JniDb_clientdata_key) : 0) @@ -1463,36 +1458,23 @@ static S3JniDb * S3JniDb_alloc(JNIEnv * const env, jobject jDb){ ** Returns the S3JniDb object for the given org.sqlite.jni.sqlite3 ** object, or NULL if jDb is NULL, no pointer can be extracted ** from it, or no matching entry can be found. -** -** Requires locking the S3JniDb mutex. */ static S3JniDb * S3JniDb__from_java(JNIEnv * const env, jobject jDb){ S3JniDb * s = 0; sqlite3 * pDb = 0; - S3JniDb_mutex_enter; if( jDb ) pDb = PtrGet_sqlite3(jDb); s = S3JniDb_from_clientdata(pDb); - S3JniDb_mutex_leave; return s; } #define S3JniDb_from_java(jObject) S3JniDb__from_java(env,(jObject)) - -static S3JniDb * S3JniDb__from_java_unlocked(JNIEnv * const env, jobject jDb){ - sqlite3 * pDb = 0; - S3JniDb_mutex_assertLocker; - if( jDb ) pDb = PtrGet_sqlite3(jDb); - return S3JniDb_from_clientdata(pDb); -} -#define S3JniDb_from_java_unlocked(JDB) S3JniDb__from_java_unlocked(env, (JDB)) - /* ** S3JniDb finalizer for use with sqlite3_set_clientdata(). */ static void S3JniDb_xDestroy(void *p){ S3JniDeclLocal_env; S3JniDb * const ps = p; - assert( !ps->pNext ); + assert( !ps->pNext && "Else ps is already in the free-list."); S3JniDb_set_aside(ps); } @@ -2012,6 +1994,11 @@ static void udf_xInverse(sqlite3_context* cx, int argc, JniDecl(jint,JniNameSuffix)(JniArgsEnvClass, jobject pStmt, jint n){ \ return (jint)CName(PtrGet_sqlite3_stmt(pStmt), (int)n); \ } +/** Create a trivial JNI wrapper for (boolish-int CName(sqlite3_stmt*)). */ +#define WRAP_BOOL_STMT(JniNameSuffix,CName) \ + JniDecl(jboolean,JniNameSuffix)(JniArgsEnvClass, jobject pStmt){ \ + return CName(PtrGet_sqlite3_stmt(pStmt)) ? JNI_TRUE : JNI_FALSE; \ + } /** Create a trivial JNI wrapper for (jstring CName(sqlite3_stmt*,int)). */ #define WRAP_STR_STMT_INT(JniNameSuffix,CName) \ JniDecl(jstring,JniNameSuffix)(JniArgsEnvClass, jobject pStmt, jint ndx){ \ @@ -2061,6 +2048,9 @@ WRAP_INT_DB(1preupdate_1depth, sqlite3_preupdate_depth) WRAP_INT_INT(1release_1memory, sqlite3_release_memory) WRAP_INT_INT(1sleep, sqlite3_sleep) WRAP_MUTF8_VOID(1sourceid, sqlite3_sourceid) +WRAP_INT_STMT_INT(1stmt_1explain, sqlite3_stmt_explain) +WRAP_INT_STMT(1stmt_1isexplain, sqlite3_stmt_isexplain) +WRAP_BOOL_STMT(1stmt_1readonly, sqlite3_stmt_readonly) WRAP_INT_VOID(1threadsafe, sqlite3_threadsafe) WRAP_INT_DB(1total_1changes, sqlite3_total_changes) WRAP_INT64_DB(1total_1changes64, sqlite3_total_changes64) @@ -2513,7 +2503,7 @@ S3JniApi(sqlite3_collation_needed(),jint,1collation_1needed)( int rc = 0; S3JniDb_mutex_enter; - ps = S3JniDb_from_java_unlocked(jDb); + ps = S3JniDb_from_java(jDb); if( !ps ){ S3JniDb_mutex_leave; return SQLITE_MISUSE; @@ -2655,7 +2645,7 @@ static jobject s3jni_commit_rollback_hook(int isCommit, JNIEnv * const env, S3JniHook * pHook; S3JniDb_mutex_enter; - ps = S3JniDb_from_java_unlocked(jDb); + ps = S3JniDb_from_java(jDb); if( !ps ){ s3jni_db_error(ps->pDb, SQLITE_NOMEM, 0); S3JniDb_mutex_leave; @@ -2878,7 +2868,7 @@ S3JniApi(sqlite3_create_collation() sqlite3_create_collation_v2(), S3JniDb * ps; S3JniDb_mutex_enter; - ps = S3JniDb_from_java_unlocked(jDb); + ps = S3JniDb_from_java(jDb); if( !ps ){ rc = SQLITE_MISUSE; }else{ diff --git a/ext/jni/src/c/sqlite3-jni.h b/ext/jni/src/c/sqlite3-jni.h index 90dc9ea260..f987d1b52b 100644 --- a/ext/jni/src/c/sqlite3-jni.h +++ b/ext/jni/src/c/sqlite3-jni.h @@ -1643,6 +1643,30 @@ JNIEXPORT jint JNICALL Java_org_sqlite_jni_SQLite3Jni_sqlite3_1status64 JNIEXPORT jint JNICALL Java_org_sqlite_jni_SQLite3Jni_sqlite3_1step (JNIEnv *, jclass, jobject); +/* + * Class: org_sqlite_jni_SQLite3Jni + * Method: sqlite3_stmt_explain + * Signature: (Lorg/sqlite/jni/sqlite3_stmt;I)I + */ +JNIEXPORT jint JNICALL Java_org_sqlite_jni_SQLite3Jni_sqlite3_1stmt_1explain + (JNIEnv *, jclass, jobject, jint); + +/* + * Class: org_sqlite_jni_SQLite3Jni + * Method: sqlite3_stmt_isexplain + * Signature: (Lorg/sqlite/jni/sqlite3_stmt;)I + */ +JNIEXPORT jint JNICALL Java_org_sqlite_jni_SQLite3Jni_sqlite3_1stmt_1isexplain + (JNIEnv *, jclass, jobject); + +/* + * Class: org_sqlite_jni_SQLite3Jni + * Method: sqlite3_stmt_readonly + * Signature: (Lorg/sqlite/jni/sqlite3_stmt;)Z + */ +JNIEXPORT jboolean JNICALL Java_org_sqlite_jni_SQLite3Jni_sqlite3_1stmt_1readonly + (JNIEnv *, jclass, jobject); + /* * Class: org_sqlite_jni_SQLite3Jni * Method: sqlite3_strglob diff --git a/ext/jni/src/org/sqlite/jni/SQLite3Jni.java b/ext/jni/src/org/sqlite/jni/SQLite3Jni.java index 30078f9085..54ed4f35e0 100644 --- a/ext/jni/src/org/sqlite/jni/SQLite3Jni.java +++ b/ext/jni/src/org/sqlite/jni/SQLite3Jni.java @@ -1325,6 +1325,17 @@ public final class SQLite3Jni { @Canonical public static native int sqlite3_step(@NotNull sqlite3_stmt stmt); + @Canonical + public static native int sqlite3_stmt_explain( + @NotNull sqlite3_stmt stmt, int op + ); + + @Canonical + public static native int sqlite3_stmt_isexplain(@NotNull sqlite3_stmt stmt); + + @Canonical + public static native boolean sqlite3_stmt_readonly(@NotNull sqlite3_stmt stmt); + /** Internal impl of the public sqlite3_strglob() method. Neither argument may be NULL and both MUST be NUL-terminated UTF-8. diff --git a/ext/jni/src/org/sqlite/jni/Tester1.java b/ext/jni/src/org/sqlite/jni/Tester1.java index a9672acca5..4bd7e42ed6 100644 --- a/ext/jni/src/org/sqlite/jni/Tester1.java +++ b/ext/jni/src/org/sqlite/jni/Tester1.java @@ -192,7 +192,7 @@ public class Tester1 implements Runnable { static sqlite3_stmt prepare(sqlite3 db, boolean throwOnError, String sql){ final OutputPointer.sqlite3_stmt outStmt = new OutputPointer.sqlite3_stmt(); - int rc = sqlite3_prepare(db, sql, outStmt); + int rc = sqlite3_prepare_v2(db, sql, outStmt); if( throwOnError ){ affirm( 0 == rc ); } @@ -203,9 +203,11 @@ public class Tester1 implements Runnable { } return rv; } + static sqlite3_stmt prepare(sqlite3 db, String sql){ return prepare(db, true, sql); } + private void showCompileOption(){ int i = 0; String optName; @@ -260,6 +262,7 @@ public class Tester1 implements Runnable { affirm(0 == rc); sqlite3_stmt stmt = outStmt.take(); affirm(0 != stmt.getNativePointer()); + affirm( !sqlite3_stmt_readonly(stmt) ); affirm( db == sqlite3_db_handle(stmt) ); rc = sqlite3_step(stmt); if( SQLITE_DONE != rc ){ @@ -360,6 +363,7 @@ public class Tester1 implements Runnable { affirm(sqlite3_changes64(db) > changes64); affirm(sqlite3_total_changes64(db) > changesT64); stmt = prepare(db, "SELECT a FROM t ORDER BY a DESC;"); + affirm( sqlite3_stmt_readonly(stmt) ); int total2 = 0; while( SQLITE_ROW == sqlite3_step(stmt) ){ total2 += sqlite3_column_int(stmt, 0); @@ -1362,7 +1366,7 @@ public class Tester1 implements Runnable { private void testColumnMetadata(){ - sqlite3 db = createNewDb(); + final sqlite3 db = createNewDb(); execSql(db, new String[] { "CREATE TABLE t(a duck primary key not null collate noCase); ", "INSERT INTO t(a) VALUES(1),(2),(3);" @@ -1397,7 +1401,7 @@ public class Tester1 implements Runnable { } private void testTxnState(){ - sqlite3 db = createNewDb(); + final sqlite3 db = createNewDb(); affirm( SQLITE_TXN_NONE == sqlite3_txn_state(db, null) ); execSql(db, "BEGIN;"); affirm( SQLITE_TXN_NONE == sqlite3_txn_state(db, null) ); @@ -1410,6 +1414,32 @@ public class Tester1 implements Runnable { sqlite3_close_v2(db); } + + private void testExplain(){ + final sqlite3 db = createNewDb(); + sqlite3_stmt stmt = prepare(db,"SELECT 1"); + + affirm( 0 == sqlite3_stmt_isexplain(stmt) ); + int rc = sqlite3_stmt_explain(stmt, 1); + affirm( 1 == sqlite3_stmt_isexplain(stmt) ); + rc = sqlite3_stmt_explain(stmt, 2); + affirm( 2 == sqlite3_stmt_isexplain(stmt) ); + sqlite3_finalize(stmt); + + + sqlite3_close_v2(db); + } + + /* Copy/paste/rename this to add new tests. */ + private void _testTemplate(){ + final sqlite3 db = createNewDb(); + sqlite3_stmt stmt = prepare(db,"SELECT 1"); + + sqlite3_finalize(stmt); + sqlite3_close_v2(db); + } + + @ManualTest /* we really only want to run this test manually. */ private void testSleep(){ out("Sleeping briefly... "); diff --git a/ext/jni/src/org/sqlite/jni/package-info.java b/ext/jni/src/org/sqlite/jni/package-info.java index 2ca997955a..21fdef27d7 100644 --- a/ext/jni/src/org/sqlite/jni/package-info.java +++ b/ext/jni/src/org/sqlite/jni/package-info.java @@ -1,19 +1,58 @@ /** This package houses a JNI binding to the SQLite3 C API. -

The docs are in progress. +

The primary interfaces are in {@link + org.sqlite.jni.SQLite3Jni}.

-

The primary interfaces are in {@link org.sqlite.jni.SQLite3Jni}. +

API Goals and Requirements

+ + + +

Non-Goals

+ +

State of this API

As of version 3.43, this software is in "tech preview" form. We - tentatively plan to stamp it as stable with the 3.44 release. + tentatively plan to stamp it as stable with the 3.44 release.

Threading Considerations

This API is, if built with SQLITE_THREADSAFE set to 1 or 2, - thread-safe, insofar as the C API guarantees, with some addenda: + thread-safe, insofar as the C API guarantees, with some addenda: