database/sqlite
1
0
Fork 0
mirror of https://github.com/sqlite/sqlite.git synced 2025-07-29 08:01:23 +03:00
Code Activity

Lots of javadoc-related tweaks.

Browse Source 
FossilOrigin-Name: cfe06f90e2c0231efded98767ef3cc646d3a7daa34d77b62b7c04b5aae9448fd
This commit is contained in:
stephan
2023-08-28 07:28:36 +00:00
parent 23dfa67c1e
commit 2597ec6385
28 changed files with 342 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
ext/jni/src/c/sqlite3-jni.c
View File

@ -2517,6 +2517,15 @@ S3JniApi(sqlite3_column_text(),jbyteArray,1column_1text_1utf8)(
return p ? s3jni_new_jbyteArray(p, n) : NULL;
}
S3JniApi(sqlite3_column_text(),jstring,1column_1text)(
JniArgsEnvClass, jobject jpStmt, jint ndx
){
sqlite3_stmt * const stmt = PtrGet_sqlite3_stmt(jpStmt);
const int n = sqlite3_column_bytes(stmt, (int)ndx);
const unsigned char * const p = sqlite3_column_text(stmt, (int)ndx);
return p ? s3jni_utf8_to_jstring( (const char *)p, n) : 0;
}
S3JniApi(sqlite3_column_text16(),jstring,1column_1text16)(
JniArgsEnvClass, jobject jpStmt, jint ndx
){

8
ext/jni/src/c/sqlite3-jni.h
View File

@ -1043,6 +1043,14 @@ JNIEXPORT jstring JNICALL Java_org_sqlite_jni_SQLite3Jni_sqlite3_1column_1table_
JNIEXPORT jbyteArray JNICALL Java_org_sqlite_jni_SQLite3Jni_sqlite3_1column_1text_1utf8
(JNIEnv *, jclass, jobject, jint);
/*
* Class: org_sqlite_jni_SQLite3Jni
* Method: sqlite3_column_text
* Signature: (Lorg/sqlite/jni/sqlite3_stmt;I)Ljava/lang/String;
*/
JNIEXPORT jstring JNICALL Java_org_sqlite_jni_SQLite3Jni_sqlite3_1column_1text
(JNIEnv *, jclass, jobject, jint);
/*
* Class: org_sqlite_jni_SQLite3Jni
* Method: sqlite3_column_text16

34
ext/jni/src/org/sqlite/jni/AbstractCollationCallback.java Normal file
View File

@ -0,0 +1,34 @@
/*
** 2023-08-25
**
** 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 JNI bindings for the sqlite3 C API.
*/
package org.sqlite.jni;
import org.sqlite.jni.annotation.NotNull;
/**
An implementation of {@link CollationCallback} which provides a
no-op xDestroy() method.
*/
public abstract class AbstractCollationCallback
implements CollationCallback, XDestroyCallback {
/**
Must compare the given byte arrays and return the result using
{@code memcmp()} semantics.
*/
public abstract int call(@NotNull byte[] lhs, @NotNull byte[] rhs);
/**
Optionally override to be notified when the UDF is finalized by
SQLite. This implementation does nothing.
*/
public void xDestroy(){}
}

8
ext/jni/src/org/sqlite/jni/AggregateFunction.java
View File

@ -15,12 +15,12 @@ package org.sqlite.jni;
/**
SQLFunction subclass for creating aggregate functions. Its T is
the data type of its "accumulator" state, an instance of which is
A SQLFunction implementation for aggregate functions. Its T is the
data type of its "accumulator" state, an instance of which is
intended to be be managed using the getAggregateState() and
takeAggregateState() methods.
*/
public abstract class AggregateFunction<T> extends SQLFunction {
public abstract class AggregateFunction<T> implements SQLFunction {
/**
As for the xStep() argument of the C API's
@ -48,7 +48,7 @@ public abstract class AggregateFunction<T> extends SQLFunction {
/**
To be called from the implementation's xStep() method, as well
as the xValue() and xInverse() methods of the Window<T>
as the xValue() and xInverse() methods of the {@link WindowFunction}
subclass, to fetch the current per-call UDF state. On the
first call to this method for any given sqlite3_context
argument, the context is set to the given initial value. On all other

4
ext/jni/src/org/sqlite/jni/AuthorizerCallback.java
View File

@ -15,14 +15,12 @@ package org.sqlite.jni;
import org.sqlite.jni.annotation.*;
/**
Callback for use with sqlite3_set_authorizer().
Callback for use with {@link SQLite3Jni#sqlite3_set_authorizer}.
*/
public interface AuthorizerCallback extends SQLite3CallbackProxy {
/**
Must function as described for the C-level
sqlite3_set_authorizer() callback.
Must not throw.
*/
int call(int opId, @Nullable String s1, @Nullable String s2,
@Nullable String s3, @Nullable String s4);

17
ext/jni/src/org/sqlite/jni/AutoExtensionCallback.java
View File

@ -14,28 +14,27 @@
package org.sqlite.jni;
/**
A callback for use with the sqlite3_auto_extension() family of
APIs.
Callback for use with the {@link SQLite3Jni#sqlite3_auto_extension}
family of APIs.
*/
public interface AutoExtensionCallback extends SQLite3CallbackProxy {
/**
Must function as described for a C-level
sqlite3_auto_extension() callback, with the caveat that the
signature is shorter.
sqlite3_auto_extension() callback.
This callback may throw and the exception's error message will
<p>This callback may throw and the exception's error message will
be set as the db's error string.
Tips for implementations:
<p>Tips for implementations:
- Opening a database from an auto-extension handler will lead to
<p>- Opening a database from an auto-extension handler will lead to
an endless recursion of the auto-handler triggering itself
indirectly for each newly-opened database.
- If this routine is stateful, it may be useful to make the
<p>- If this routine is stateful, it may be useful to make the
overridden method synchronized.
- Results are undefined if db is closed by an auto-extension.
<p>- Results are undefined if the given db is closed by an auto-extension.
*/
int call(sqlite3 db);
}

10
ext/jni/src/org/sqlite/jni/BusyHandlerCallback.java
View File

@ -13,18 +13,14 @@
*/
package org.sqlite.jni;
/**
Callback for use with sqlite3_busy_handler()
Callback for use with {@link SQLite3Jni#sqlite3_busy_handler}.
*/
public abstract class BusyHandlerCallback implements SQLite3CallbackProxy {
public interface BusyHandlerCallback extends SQLite3CallbackProxy {
/**
Must function as documented for the C-level
sqlite3_busy_handler() callback argument, minus the (void*)
argument the C-level function requires.
Any exceptions thrown by this callback are suppressed in order to
retain the C-style API semantics of the JNI bindings.
*/
public abstract int call(int n);
int call(int n);
}

16
ext/jni/src/org/sqlite/jni/CollationCallback.java
View File

@ -12,20 +12,24 @@
** This file is part of the JNI bindings for the sqlite3 C API.
*/
package org.sqlite.jni;
import org.sqlite.jni.annotation.NotNull;
/**
Callback for use with sqlite3_create_collation()
Callback for use with {@link SQLite3Jni#sqlite3_create_collation}.
@see AbstractCollationCallback
*/
public abstract class CollationCallback
implements SQLite3CallbackProxy, XDestroyCallback {
public interface CollationCallback
extends SQLite3CallbackProxy, XDestroyCallback {
/**
Must compare the given byte arrays using memcmp() semantics.
Must compare the given byte arrays and return the result using
{@code memcmp()} semantics.
*/
public abstract int call(byte[] lhs, byte[] rhs);
int call(@NotNull byte[] lhs, @NotNull byte[] rhs);
/**
Called by SQLite when the collation is destroyed. If a collation
requires custom cleanup, override this method.
*/
public void xDestroy(){}
void xDestroy();
}

2
ext/jni/src/org/sqlite/jni/CollationNeededCallback.java
View File

@ -14,7 +14,7 @@
package org.sqlite.jni;
/**
Callback for use with sqlite3_collation_needed().
Callback for use with {@link SQLite3Jni#sqlite3_collation_needed}.
*/
public interface CollationNeededCallback extends SQLite3CallbackProxy {
/**

2
ext/jni/src/org/sqlite/jni/CommitHookCallback.java
View File

@ -14,7 +14,7 @@
package org.sqlite.jni;
/**
Callback for use with sqlite3_commit_hook()
Callback for use with {@link SQLite3Jni#sqlite3_commit_hook}.
*/
public interface CommitHookCallback extends SQLite3CallbackProxy {
/**

4
ext/jni/src/org/sqlite/jni/PreupdateHookCallback.java
View File

@ -14,12 +14,12 @@
package org.sqlite.jni;
/**
Callback for use with sqlite3_preupdate_hook().
Callback for use with {@link SQLite3Jni#sqlite3_preupdate_hook}.
*/
public interface PreupdateHookCallback extends SQLite3CallbackProxy {
/**
Must function as described for the C-level sqlite3_preupdate_hook()
callback. Must not throw.
callback.
*/
void call(sqlite3 db, int op, String dbName, String dbTable,
long iKey1, long iKey2 );

4
ext/jni/src/org/sqlite/jni/ProgressHandlerCallback.java
View File

@ -14,13 +14,13 @@
package org.sqlite.jni;
/**
Callback for use with sqlite3_progress_handler()
Callback for use with {@link SQLite3Jni#sqlite3_progress_handler}.
*/
public interface ProgressHandlerCallback extends SQLite3CallbackProxy {
/**
Works as documented for the C-level sqlite3_progress_handler() callback.
If it throws, the exception message is passed on to the db and
<p>If it throws, the exception message is passed on to the db and
the exception is suppressed.
*/
int call();

4
ext/jni/src/org/sqlite/jni/RollbackHookCallback.java
View File

@ -14,12 +14,12 @@
package org.sqlite.jni;
/**
Callback for use with sqlite3_rollback_hook()
Callback for use with {@link SQLite3Jni#sqlite3_rollback_hook}.
*/
public interface RollbackHookCallback extends SQLite3CallbackProxy {
/**
Works as documented for the C-level sqlite3_rollback_hook()
callback. Must not throw.
callback.
*/
void call();
}

10
ext/jni/src/org/sqlite/jni/SQLFunction.java
View File

@ -31,7 +31,7 @@ package org.sqlite.jni;
SQLFunction base class and the method names and signatures used by
the UDF callback interfaces.
*/
public abstract class SQLFunction {
public interface SQLFunction {
/**
PerContextState assists aggregate and window functions in
@ -53,11 +53,11 @@ public abstract class SQLFunction {
state, of a client-defined type (the T part of this class), which
persists across a "matching set" of the UDF's callbacks.
<p>This class is a helper providing commonly-needed functionality -
it is not required for use with aggregate or window functions.
<p>This class is a helper providing commonly-needed functionality
- it is not required for use with aggregate or window functions.
Client UDFs are free to perform such mappings using custom
approaches. The provided Aggregate<T> and Window<T> classes
use this.
approaches. The provided {@link AggregateFunction} and {@link
WindowFunction} classes use this.
*/
public static final class PerContextState<T> {
private final java.util.Map<Long,ValueHolder<T>> map

24
ext/jni/src/org/sqlite/jni/SQLite3CallbackProxy.java
View File

@ -18,17 +18,27 @@ package org.sqlite.jni;
classes which have a call() method implementing some specific
callback interface on behalf of the C library.
<p>Unless very explicitely documented otherwise, callbacks must
never throw. Any which do throw but should not might trigger debug
output regarding the error, but the exception will not be
propagated. For callback interfaces which support returning error
info to the core, the JNI binding will convert any exceptions to
C-level error information. For callback interfaces which do not
support, all exceptions will necessarily be suppressed in order to
retain the C-style no-throw semantics.
<p>Callbacks of this style follow a common naming convention:
<p>1) They use the UpperCamelCase form of the C function they're
proxying for, minus the sqlite3_ prefix, plus a Callback
suffix. e.g. sqlite3_busy_handler()'s callback is named
BusyHandlerCallback. Exceptions are made where that would
potentially be ambiguous, e.g. ConfigSqllogCallback instead of
config_callback because the sqlite3_config() interface may need to
support more callback types in the future.
proxying for, minus the {@code sqlite3_} prefix, plus a {@code
Callback} suffix. e.g. {@code sqlite3_busy_handler()}'s callback is
named {@code BusyHandlerCallback}. Exceptions are made where that
would potentially be ambiguous, e.g. {@link ConfigSqllogCallback}
instead of {@code ConfigCallback} because the {@code
sqlite3_config()} interface may need to support more callback types
in the future.
<p>2) They all have a call() method but its signature is
<p>2) They all have a {@code call()} method but its signature is
callback-specific.
*/
public interface SQLite3CallbackProxy {}

140
ext/jni/src/org/sqlite/jni/SQLite3Jni.java
View File

@ -324,70 +324,87 @@ public final class SQLite3Jni {
@NotNull sqlite3 db, int ms
);
@Canonical
public static native boolean sqlite3_cancel_auto_extension(
@NotNull AutoExtensionCallback ax
);
@Canonical
public static native int sqlite3_changes(
@NotNull sqlite3 db
);
@Canonical
public static native long sqlite3_changes64(
@NotNull sqlite3 db
);
@Canonical
public static native int sqlite3_clear_bindings(
@NotNull sqlite3_stmt stmt
);
@Canonical
public static native int sqlite3_close(
@Nullable sqlite3 db
);
@Canonical
public static native int sqlite3_close_v2(
@Nullable sqlite3 db
);
@Canonical
public static native byte[] sqlite3_column_blob(
@NotNull sqlite3_stmt stmt, int ndx
);
@Canonical
public static native int sqlite3_column_bytes(
@NotNull sqlite3_stmt stmt, int ndx
);
@Canonical
public static native int sqlite3_column_bytes16(
@NotNull sqlite3_stmt stmt, int ndx
);
@Canonical
public static native int sqlite3_column_count(
@NotNull sqlite3_stmt stmt
);
@Canonical
public static native double sqlite3_column_double(
@NotNull sqlite3_stmt stmt, int ndx
);
@Canonical
public static native int sqlite3_column_int(
@NotNull sqlite3_stmt stmt, int ndx
);
@Canonical
public static native long sqlite3_column_int64(
@NotNull sqlite3_stmt stmt, int ndx
);
@Canonical
public static native String sqlite3_column_name(
@NotNull sqlite3_stmt stmt, int ndx
);
@Canonical
public static native String sqlite3_column_database_name(
@NotNull sqlite3_stmt stmt, int ndx
);
@Canonical
public static native String sqlite3_column_origin_name(
@NotNull sqlite3_stmt stmt, int ndx
);
@Canonical
public static native String sqlite3_column_table_name(
@NotNull sqlite3_stmt stmt, int ndx
);
@ -396,18 +413,25 @@ public final class SQLite3Jni {
Returns the given column's contents as UTF-8-encoded (not MUTF-8)
text. Returns null if the C-level sqlite3_column_text() returns
NULL.
@see #sqlite3_column_text
*/
@Canonical(cname="sqlite3_column_text")
public static native byte[] sqlite3_column_text_utf8(
@NotNull sqlite3_stmt stmt, int ndx
);
public static String sqlite3_column_text(
@NotNull sqlite3_stmt stmt, int ndx
){
final byte[] ba = sqlite3_column_text_utf8(stmt, ndx);
return ba==null ? null : new String(ba, StandardCharsets.UTF_8);
}
/**
Provides the same feature as the same-named C API but returns the
text in Java-native encoding rather than the C API's UTF-8.
@see #sqlite3_column_text16
*/
public static native String sqlite3_column_text(
@NotNull sqlite3_stmt stmt, int ndx
);
@Canonical
public static native String sqlite3_column_text16(
@NotNull sqlite3_stmt stmt, int ndx
);
@ -449,10 +473,12 @@ public final class SQLite3Jni {
// return rv;
// }
@Canonical
public static native int sqlite3_column_type(
@NotNull sqlite3_stmt stmt, int ndx
);
@Canonical
public static native sqlite3_value sqlite3_column_value(
@NotNull sqlite3_stmt stmt, int ndx
);
@ -461,22 +487,27 @@ public final class SQLite3Jni {
This functions like C's sqlite3_collation_needed16() because
Java's string type is compatible with that interface.
*/
@Canonical
public static native int sqlite3_collation_needed(
@NotNull sqlite3 db, @Nullable CollationNeededCallback callback
);
@Canonical
public static native sqlite3 sqlite3_context_db_handle(
@NotNull sqlite3_context cx
);
@Canonical
public static native CommitHookCallback sqlite3_commit_hook(
@NotNull sqlite3 db, @Nullable CommitHookCallback hook
);
@Canonical
public static native String sqlite3_compileoption_get(
int n
);
@Canonical
public static native boolean sqlite3_compileoption_used(
@NotNull String optName
);
@ -497,6 +528,9 @@ public final class SQLite3Jni {
library APIs are being called.
*/
@Canonical(comment="Option subset: "+
"SQLITE_CONFIG_SINGLETHREAD, SQLITE_CONFIG_MULTITHREAD, "+
"SQLITE_CONFIG_SERIALIZED")
public static native int sqlite3_config(int op);
/**
@ -514,8 +548,10 @@ public final class SQLite3Jni {
library APIs are being called.
*/
@Canonical(comment="Option subset: SQLITE_CONFIG_SQLLOG")
public static native int sqlite3_config( @Nullable ConfigSqllogCallback logger );
@Canonical
public static native int sqlite3_create_collation(
@NotNull sqlite3 db, @NotNull String name, int eTextRep,
@NotNull CollationCallback col
@ -529,11 +565,13 @@ public final class SQLite3Jni {
SQLFunction's subclasses (ScalarFunction, AggregateFunction<T>,
and WindowFunction<T>) for details.
*/
@Canonical
public static native int sqlite3_create_function(
@NotNull sqlite3 db, @NotNull String functionName,
int nArg, int eTextRep, @NotNull SQLFunction func
);
@Canonical
public static native int sqlite3_data_count(
@NotNull sqlite3_stmt stmt
);
@ -543,6 +581,7 @@ public final class SQLite3Jni {
variadic arguments. Returns SQLITE_MISUSE if op is not one of the
SQLITE_DBCONFIG_... options which uses this call form.
*/
@Canonical
public static native int sqlite3_db_config(
@NotNull sqlite3 db, int op, int onOff, @Nullable OutputPointer.Int32 out
);
@ -554,53 +593,71 @@ public final class SQLite3Jni {
SQLITE_DBCONFIG_MAINDBNAME, but that set of options may be
extended in future versions.
*/
@Canonical(comment="Supports only a subset of options.")
public static native int sqlite3_db_config(
@NotNull sqlite3 db, int op, @NotNull String val
);
@Canonical
public static native String sqlite3_db_filename(
@NotNull sqlite3 db, @NotNull String dbName
);
@Canonical
public static native sqlite3 sqlite3_db_handle( @NotNull sqlite3_stmt stmt );
@Canonical
public static native int sqlite3_db_status(
@NotNull sqlite3 db, int op, @NotNull OutputPointer.Int32 pCurrent,
@NotNull OutputPointer.Int32 pHighwater, boolean reset
);
@Canonical
public static native int sqlite3_errcode(@NotNull sqlite3 db);
@Canonical
public static native String sqlite3_expanded_sql(@NotNull sqlite3_stmt stmt);
@Canonical
public static native int sqlite3_extended_errcode(@NotNull sqlite3 db);
@Canonical
public static native boolean sqlite3_extended_result_codes(
@NotNull sqlite3 db, boolean onoff
);
@Canonical
public static native String sqlite3_errmsg(@NotNull sqlite3 db);
@Canonical
public static native String sqlite3_errstr(int resultCode);
/**
Note that the returned byte offset values assume UTF-8-encoded
inputs, so won't always match character offsets in Java Strings.
*/
@Canonical
public static native int sqlite3_error_offset(@NotNull sqlite3 db);
@Canonical
public static native int sqlite3_finalize(@NotNull sqlite3_stmt stmt);
@Canonical
public static native int sqlite3_initialize();
@Canonical
public static native void sqlite3_interrupt(@NotNull sqlite3 db);
@Canonical
public static native boolean sqlite3_is_interrupted(@NotNull sqlite3 db);
@Canonical
public static native long sqlite3_last_insert_rowid(@NotNull sqlite3 db);
@Canonical
public static native String sqlite3_libversion();
@Canonical
public static native int sqlite3_libversion_number();
/**
@ -616,6 +673,7 @@ public final class SQLite3Jni {
object and it is up to the caller to sqlite3_close() that
db handle.
*/
@Canonical
public static native int sqlite3_open(
@Nullable String filename, @NotNull OutputPointer.sqlite3 ppDb
);
@ -634,6 +692,7 @@ public final class SQLite3Jni {
return out.take();
};
@Canonical
public static native int sqlite3_open_v2(
@Nullable String filename, @NotNull OutputPointer.sqlite3 ppDb,
int flags, @Nullable String zVfs
@ -670,6 +729,7 @@ public final class SQLite3Jni {
necessary, however, and overloads are provided which gloss over
that.
*/
@Canonical
private static native int sqlite3_prepare(
@NotNull sqlite3 db, @NotNull byte[] sqlUtf8, int maxBytes,
@NotNull OutputPointer.sqlite3_stmt outStmt,
@ -719,6 +779,7 @@ public final class SQLite3Jni {
See sqlite3_prepare() for details about the slight API differences
from the C API.
*/
@Canonical
private static native int sqlite3_prepare_v2(
@NotNull sqlite3 db, @NotNull byte[] sqlUtf8, int maxBytes,
@NotNull OutputPointer.sqlite3_stmt outStmt,
@ -760,6 +821,7 @@ public final class SQLite3Jni {
return out.take();
}
@Canonical
private static native int sqlite3_prepare_v3(
@NotNull sqlite3 db, @NotNull byte[] sqlUtf8, int maxBytes,
int prepFlags, @NotNull OutputPointer.sqlite3_stmt outStmt,
@ -806,18 +868,21 @@ public final class SQLite3Jni {
acts as a proxy for C's sqlite3_preupdate_blobwrite(), else it returns
SQLITE_MISUSE with no side effects.
*/
@Canonical
public static native int sqlite3_preupdate_blobwrite(@NotNull sqlite3 db);
/**
If the C API was built with SQLITE_ENABLE_PREUPDATE_HOOK defined, this
acts as a proxy for C's sqlite3_preupdate_count(), else it returns
SQLITE_MISUSE with no side effects.
*/
@Canonical
public static native int sqlite3_preupdate_count(@NotNull sqlite3 db);
/**
If the C API was built with SQLITE_ENABLE_PREUPDATE_HOOK defined, this
acts as a proxy for C's sqlite3_preupdate_depth(), else it returns
SQLITE_MISUSE with no side effects.
*/
@Canonical
public static native int sqlite3_preupdate_depth(@NotNull sqlite3 db);
/**
@ -825,6 +890,7 @@ public final class SQLite3Jni {
acts as a proxy for C's sqlite3_preupdate_hook(), else it returns null
with no side effects.
*/
@Canonical
public static native PreupdateHookCallback sqlite3_preupdate_hook(
@NotNull sqlite3 db, @Nullable PreupdateHookCallback hook
);
@ -834,6 +900,7 @@ public final class SQLite3Jni {
this acts as a proxy for C's sqlite3_preupdate_new(), else it
returns SQLITE_MISUSE with no side effects.
*/
@Canonical
public static native int sqlite3_preupdate_new(@NotNull sqlite3 db, int col,
@NotNull OutputPointer.sqlite3_value out);
@ -852,6 +919,7 @@ public final class SQLite3Jni {
this acts as a proxy for C's sqlite3_preupdate_old(), else it
returns SQLITE_MISUSE with no side effects.
*/
@Canonical
public static native int sqlite3_preupdate_old(@NotNull sqlite3 db, int col,
@NotNull OutputPointer.sqlite3_value out);
@ -865,10 +933,12 @@ public final class SQLite3Jni {
return out.take();
}
@Canonical
public static native void sqlite3_progress_handler(
@NotNull sqlite3 db, int n, @Nullable ProgressHandlerCallback h
);
@Canonical
public static native int sqlite3_reset(@NotNull sqlite3_stmt stmt);
/**
@ -876,8 +946,10 @@ public final class SQLite3Jni {
extensions are currently running. (The JNI-level list of
extensions cannot be manipulated while it is being traversed.)
*/
@Canonical
public static native void sqlite3_reset_auto_extension();
@Canonical
public static native void sqlite3_result_double(
@NotNull sqlite3_context cx, double v
);
@ -889,6 +961,7 @@ public final class SQLite3Jni {
results in the C-level sqlite3_result_error() being called with
a complaint about the invalid argument.
*/
@Canonical
private static native void sqlite3_result_error(
@NotNull sqlite3_context cx, @NotNull byte[] msg, int eTextRep
);
@ -929,26 +1002,32 @@ public final class SQLite3Jni {
sqlite3_result_error(cx, e.getMessage());
}
@Canonical
public static native void sqlite3_result_error_toobig(
@NotNull sqlite3_context cx
);
@Canonical
public static native void sqlite3_result_error_nomem(
@NotNull sqlite3_context cx
);
@Canonical
public static native void sqlite3_result_error_code(
@NotNull sqlite3_context cx, int c
);
@Canonical
public static native void sqlite3_result_null(
@NotNull sqlite3_context cx
);
@Canonical
public static native void sqlite3_result_int(
@NotNull sqlite3_context cx, int v
);
@Canonical
public static native void sqlite3_result_int64(
@NotNull sqlite3_context cx, long v
);
@ -1031,18 +1110,22 @@ public final class SQLite3Jni {
sqlite3_result_text(cx, v);
}
@Canonical
public static native void sqlite3_result_value(
@NotNull sqlite3_context cx, @NotNull sqlite3_value v
);
@Canonical
public static native void sqlite3_result_zeroblob(
@NotNull sqlite3_context cx, int n
);
@Canonical
public static native int sqlite3_result_zeroblob64(
@NotNull sqlite3_context cx, long n
);
@Canonical
private static native void sqlite3_result_blob(
@NotNull sqlite3_context cx, @Nullable byte[] blob, int maxLen
);
@ -1068,6 +1151,7 @@ public final class SQLite3Jni {
If @param maxLen is larger than blob.length, it is truncated to
that value. If it is negative, results are undefined.
*/
@Canonical
private static native void sqlite3_result_blob64(
@NotNull sqlite3_context cx, @Nullable byte[] blob, long maxLen
);
@ -1078,6 +1162,7 @@ public final class SQLite3Jni {
sqlite3_result_blob64(cx, blob, (long)(null==blob ? 0 : blob.length));
}
@Canonical
private static native void sqlite3_result_text(
@NotNull sqlite3_context cx, @Nullable byte[] utf8, int maxLen
);
@ -1118,6 +1203,7 @@ public final class SQLite3Jni {
negative, results are undefined. If text is null, the subsequent
arguments are ignored.
*/
@Canonical
private static native void sqlite3_result_text64(
@NotNull sqlite3_context cx, @Nullable byte[] text,
long maxLength, int encoding
@ -1143,15 +1229,17 @@ public final class SQLite3Jni {
}
}
@Canonical
public static native RollbackHookCallback sqlite3_rollback_hook(
@NotNull sqlite3 db, @Nullable RollbackHookCallback hook
);
//! Sets or unsets (if auth is null) the current authorizer.
@Canonical
public static native int sqlite3_set_authorizer(
@NotNull sqlite3 db, @Nullable AuthorizerCallback auth
);
@Canonical
public static native void sqlite3_set_last_insert_rowid(
@NotNull sqlite3 db, long rowid
);
@ -1166,31 +1254,39 @@ public final class SQLite3Jni {
to use those objects after this routine is called invoked
undefined behavior.
*/
@Canonical
public static synchronized native int sqlite3_shutdown();
@Canonical
public static native int sqlite3_sleep(int ms);
@Canonical
public static native String sqlite3_sourceid();
@Canonical
public static native String sqlite3_sql(@NotNull sqlite3_stmt stmt);
@Canonical
public static native int sqlite3_status(
int op, @NotNull OutputPointer.Int32 pCurrent,
@NotNull OutputPointer.Int32 pHighwater, boolean reset
);
@Canonical
public static native int sqlite3_status64(
int op, @NotNull OutputPointer.Int64 pCurrent,
@NotNull OutputPointer.Int64 pHighwater, boolean reset
);
@Canonical
public static native int sqlite3_step(@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.
*/
@Canonical
private static native int sqlite3_strglob(
@NotNull byte[] glob, @NotNull byte[] txt
);
@ -1208,6 +1304,7 @@ public final class SQLite3Jni {
Internal impl of the public sqlite3_strlike() method. Neither
argument may be NULL and both MUST be NUL-terminated UTF-8.
*/
@Canonical
private static native int sqlite3_strlike(
@NotNull byte[] glob, @NotNull byte[] txt, int escChar
);
@ -1222,10 +1319,13 @@ public final class SQLite3Jni {
);
}
@Canonical
public static native int sqlite3_threadsafe();
@Canonical
public static native int sqlite3_total_changes(@NotNull sqlite3 db);
@Canonical
public static native long sqlite3_total_changes64(@NotNull sqlite3 db);
/**
@ -1237,32 +1337,43 @@ public final class SQLite3Jni {
implementation returns non-0 if initialization of the tracer
mapping state fails.
*/
@Canonical
public static native int sqlite3_trace_v2(
@NotNull sqlite3 db, int traceMask, @Nullable TraceV2Callback tracer
);
@Canonical
public static native UpdateHookCallback sqlite3_update_hook(
sqlite3 db, UpdateHookCallback hook
);
@Canonical
public static native byte[] sqlite3_value_blob(@NotNull sqlite3_value v);
@Canonical
public static native int sqlite3_value_bytes(@NotNull sqlite3_value v);
@Canonical
public static native int sqlite3_value_bytes16(@NotNull sqlite3_value v);
@Canonical
public static native double sqlite3_value_double(@NotNull sqlite3_value v);
@Canonical
public static native sqlite3_value sqlite3_value_dup(
@NotNull sqlite3_value v
);
@Canonical
public static native int sqlite3_value_encoding(@NotNull sqlite3_value v);
@Canonical
public static native void sqlite3_value_free(@Nullable sqlite3_value v);
@Canonical
public static native int sqlite3_value_int(@NotNull sqlite3_value v);
@Canonical
public static native long sqlite3_value_int64(@NotNull sqlite3_value v);
/**
@ -1293,8 +1404,17 @@ public final class SQLite3Jni {
Returns the given value as UTF-8-encoded bytes, or null if the
underlying C-level sqlite3_value_text() returns NULL.
*/
@Canonical(cname="sqlite3_value_text",
comment="Renamed because its String-returning overload would "+
"otherwise be ambiguous.")
public static native byte[] sqlite3_value_text_utf8(@NotNull sqlite3_value v);
/**
Provides the same feature as the same-named C API but returns the
text in Java-native encoding rather than the C API's UTF-8.
@see #sqlite3_value_text16
*/
public static native String sqlite3_value_text(@NotNull sqlite3_value v);
/**
@ -1305,16 +1425,22 @@ public final class SQLite3Jni {
sqlite3_value_text() fetches UTF-8 (SQLite's default encoding)
and converts it to UTF-16 in Java.
*/
@Canonical
public static native String sqlite3_value_text16(@NotNull sqlite3_value v);
@Canonical
public static native int sqlite3_value_type(@NotNull sqlite3_value v);
@Canonical
public static native int sqlite3_value_numeric_type(@NotNull sqlite3_value v);
@Canonical
public static native int sqlite3_value_nochange(@NotNull sqlite3_value v);
@Canonical
public static native int sqlite3_value_frombind(@NotNull sqlite3_value v);
@Canonical
public static native int sqlite3_value_subtype(@NotNull sqlite3_value v);
/**

6
ext/jni/src/org/sqlite/jni/ScalarFunction.java
View File

@ -15,9 +15,9 @@ package org.sqlite.jni;
/**
SQLFunction subclass for creating scalar functions.
A SQLFunction implementation for scalar functions.
*/
public abstract class ScalarFunction extends SQLFunction {
public abstract class ScalarFunction implements SQLFunction {
/**
As for the xFunc() argument of the C API's
sqlite3_create_function(). If this function throws, it is
@ -27,7 +27,7 @@ public abstract class ScalarFunction extends SQLFunction {
/**
Optionally override to be notified when the UDF is finalized by
SQLite.
SQLite. This implementation does nothing.
*/
public void xDestroy() {}
}

7
ext/jni/src/org/sqlite/jni/TraceV2Callback.java
View File

@ -12,9 +12,10 @@
** This file is part of the JNI bindings for the sqlite3 C API.
*/
package org.sqlite.jni;
import org.sqlite.jni.annotation.Nullable;
/**
Callback proxy for use with sqlite3_trace_v2().
Callback for use with {@link SQLite3Jni#sqlite3_trace_v2}.
*/
public interface TraceV2Callback extends SQLite3CallbackProxy {
/**
@ -23,7 +24,7 @@ public interface TraceV2Callback extends SQLite3CallbackProxy {
argument to the native trace callback, as that role is better
filled by instance-local state.
These callbacks may throw, in which case their exceptions are
<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
@ -45,5 +46,5 @@ public interface TraceV2Callback extends SQLite3CallbackProxy {
<p>- SQLITE_TRACE_CLOSE: pNative is a sqlite3. pX is null.
*/
int call(int traceFlag, Object pNative, Object pX);
int call(int traceFlag, Object pNative, @Nullable Object pX);
}

4
ext/jni/src/org/sqlite/jni/UpdateHookCallback.java
View File

@ -14,12 +14,12 @@
package org.sqlite.jni;
/**
Callback for use with sqlite3_update_hook().
Callback for use with {@link SQLite3Jni#sqlite3_update_hook}.
*/
public interface UpdateHookCallback extends SQLite3CallbackProxy {
/**
Must function as described for the C-level sqlite3_update_hook()
callback. Must not throw.
callback.
*/
void call(int opId, String dbName, String tableName, long rowId);
}

10
ext/jni/src/org/sqlite/jni/WindowFunction.java
View File

@ -15,11 +15,11 @@ package org.sqlite.jni;
/**
An SQLFunction subclass for creating window functions. Note that
Window<T> inherits from Aggregate<T> and each instance is
required to implement the inherited abstract methods from that
class. See Aggregate<T> for information on managing the UDF's
invocation-specific state.
A SQLFunction implementation for window functions. Note that
WindowFunction inherits from {@link AggregateFunction} and each
instance is required to implement the inherited abstract methods
from that class. See {@link AggregateFunction} for information on
managing the UDF's invocation-specific state.
*/
public abstract class WindowFunction<T> extends AggregateFunction<T> {

40
ext/jni/src/org/sqlite/jni/annotation/Canonical.java
View File

@ -2,15 +2,43 @@ package org.sqlite.jni.annotation;
/**
This annotation is for marking functions as "canonical", meaning
that they exist in the C API. The intent is to distinguish them
from functions added specifically to the Java API.
that they map directly to a function in the core sqlite3 C API. The
intent is to distinguish them from functions added specifically to
the Java API.
<p>Canonical functions, unless specifically documented, have the
same semantics as their counterparts in @{link
https://sqlite.org/c3ref/intro.html the C API documentation}, despite
their signatures perhaps differing.
same semantics as their counterparts in
<a href="https://sqlite.org/c3ref/intro.html">the C API documentation</a>,
despite their signatures perhaps differing. The Java API adds a
number of overloads to simplify use, as well as a few Java-specific
functions, and those are never flagged as @Canonical.
<p>In some cases, the canonical version of a function is private
and exposed to Java via public overloads.
<p>In rare cases, the Java interface for a canonical function has a
different name than its C counterpart. For such cases,
(cname=the-C-side-name) is passed to this annotation and a
Java-side implementation with a slightly different signature is
added to with the canonical name. As of this writing, that applies
only to {@link org.sqlite.jni.SQLite3Jni#sqlite3_value_text_utf8}
and {@link org.sqlite.jni.SQLite3Jni#sqlite3_column_text_utf8}.
<p>The comment property can be used to add a comment.
*/
@java.lang.annotation.Documented
@java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.SOURCE)
@java.lang.annotation.Target(java.lang.annotation.ElementType.METHOD)
public @interface Canonical{}
public @interface Canonical{
/**
Java functions which directly map to a canonical function but
change its name for some reason should not the original name
in this property.
*/
String cname() default ""/*doesn't allow null*/;
/**
Brief comments about the binding, e.g. noting any major
semantic differences.
*/
String comment() default "";
}

13
ext/jni/src/org/sqlite/jni/annotation/NotNull.java
View File

@ -2,11 +2,14 @@ package org.sqlite.jni.annotation;
/**
This annotation is for flagging parameters which may not legally be
null. Note that the C-style API does not throw any exceptions on
its own because it has a no-throw policy in order to retain its
C-style semantics, but it may trigger NullPointerExceptions (or
similar) if passed a null for a parameter flagged with this
annotation.
null. When used in the context of callback methods which are
called into from the C APIs, this annotation communicates that the
C API will never pass a null value to the callback.
<p>Note that the C-style API does not throw any exceptions on its
own because it has a no-throw policy in order to retain its C-style
semantics, but it may trigger NullPointerExceptions (or similar) if
passed a null for a parameter flagged with this annotation.
<p>This annotation is informational only. No policy is in place to
programmatically ensure that NotNull is conformed to in client

5
ext/jni/src/org/sqlite/jni/annotation/Nullable.java
View File

@ -3,7 +3,10 @@ package org.sqlite.jni.annotation;
/**
This annotation is for flagging parameters which may legally be
null, noting that they may behave differently if passed null but
are prepared to expect null as a value.
are prepared to expect null as a value. When used in the context of
callback methods which are called into from the C APIs, this
annotation communicates that the C API may pass a null value to the
callback.
<p>This annotation is solely for the use by the classes in this
package but is made public so that javadoc will link to it from the

4
ext/jni/src/org/sqlite/jni/annotation/package-info.java Normal file
View File

@ -0,0 +1,4 @@
/**
This package houses annotations specific a JNI binding to the SQLite3 C API.
*/
package org.sqlite.jni.annotation;

6
ext/jni/src/org/sqlite/jni/tester/SQLTester.java
View File

@ -152,12 +152,12 @@ class Outer {
/**
This class provides an application which aims to implement the
rudimentary SQL-driven test tool described in the accompanying
test-script-interpreter.md.
{@code test-script-interpreter.md}.
This is a work in progress.
<p>This is a work in progress.
An instance of this application provides a core set of services
<p>An instance of this application provides a core set of services
which TestScript instances use for processing testing logic.
TestScripts, in turn, delegate the concrete test work to Command
objects, which the TestScript parses on their behalf.