admin/SQLite-fork
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Adding the sqlite sourcecode

Browse Source
This commit is contained in:
Jiří Stach committed 2025-07-17 11:54:48 +02:00
1 parent bdb54a1f8f
commit 406b584760
2208 files changed
+1172785 -1
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

ext/jni/GNUmakefile
+505
View File
@@ -0,0 +1,505 @@
# Quick-and-dirty makefile to bootstrap the sqlite3-jni project. This
# build assumes a Linux-like system.
default: all
JAVA_HOME ?= $(HOME)/jdk/current
# e.g. /usr/lib/jvm/default-javajava-19-openjdk-amd64
JDK_HOME ?= $(JAVA_HOME)
# ^^^ JDK_HOME is not as widely used as JAVA_HOME
bin.jar := $(JDK_HOME)/bin/jar
bin.java := $(JDK_HOME)/bin/java
bin.javac := $(JDK_HOME)/bin/javac
bin.javadoc := $(JDK_HOME)/bin/javadoc
ifeq (,$(wildcard $(JDK_HOME)))
$(error set JDK_HOME to the top-most dir of your JDK installation.)
endif
MAKEFILE := $(lastword $(MAKEFILE_LIST))
$(MAKEFILE):
package.jar := sqlite3-jni.jar
dir.top := ../..
dir.tool := ../../tool
dir.jni := $(patsubst %/,%,$(dir $(MAKEFILE)))
dir.src := $(dir.jni)/src
dir.src.c := $(dir.src)/c
dir.bld := $(dir.jni)/bld
dir.bld.c := $(dir.bld)
dir.src.jni := $(dir.src)/org/sqlite/jni
dir.src.capi := $(dir.src.jni)/capi
dir.src.fts5 := $(dir.src.jni)/fts5
dir.tests := $(dir.src)/tests
mkdir ?= mkdir -p
$(dir.bld.c):
$(mkdir) $@
javac.flags ?= -Xlint:unchecked -Xlint:deprecation
java.flags ?=
javac.flags += -encoding utf8
# -------------^^^^^^^^^^^^^^ required for Windows builds
jnicheck ?= 1
ifeq (1,$(jnicheck))
java.flags += -Xcheck:jni
endif
classpath := $(dir.src)
CLEAN_FILES := $(package.jar)
DISTCLEAN_FILES := $(dir.jni)/*~ $(dir.src.c)/*~ $(dir.src.jni)/*~
sqlite3-jni.h := $(dir.src.c)/sqlite3-jni.h
.NOTPARALLEL: $(sqlite3-jni.h)
CApi.java := $(dir.src.capi)/CApi.java
SQLTester.java := $(dir.src.capi)/SQLTester.java
CApi.class := $(CApi.java:.java=.class)
SQLTester.class := $(SQLTester.java:.java=.class)
########################################################################
# The future of FTS5 customization in this API is as yet unclear.
# The pieces are all in place, and are all thin proxies so not much
# complexity, but some semantic changes were required in porting
# which are largely untested.
#
# Reminder: this flag influences the contents of $(sqlite3-jni.h),
# which is checked in. Please do not check in changes to that file in
# which the fts5 APIs have been stripped unless that feature is
# intended to be stripped for good.
enable.fts5 ?= 1
ifeq (,$(wildcard $(dir.tests)/*))
enable.tester := 0
else
enable.tester := 1
endif
# bin.version-info = binary to output various sqlite3 version info
# building the distribution zip file.
bin.version-info := $(dir.top)/version-info
.NOTPARALLEL: $(bin.version-info)
$(bin.version-info): $(dir.tool)/version-info.c $(sqlite3.h) $(dir.top)/Makefile
$(MAKE) -C $(dir.top) version-info
# Be explicit about which Java files to compile so that we can work on
# in-progress files without requiring them to be in a compilable state.
JAVA_FILES.main := $(patsubst %,$(dir.src.jni)/annotation/%,\
Experimental.java \
NotNull.java \
Nullable.java \
) $(patsubst %,$(dir.src.capi)/%,\
AbstractCollationCallback.java \
AggregateFunction.java \
AuthorizerCallback.java \
AutoExtensionCallback.java \
BusyHandlerCallback.java \
CollationCallback.java \
CollationNeededCallback.java \
CommitHookCallback.java \
ConfigLogCallback.java \
ConfigSqlLogCallback.java \
NativePointerHolder.java \
OutputPointer.java \
PrepareMultiCallback.java \
PreupdateHookCallback.java \
ProgressHandlerCallback.java \
ResultCode.java \
RollbackHookCallback.java \
ScalarFunction.java \
SQLFunction.java \
CallbackProxy.java \
CApi.java \
TableColumnMetadata.java \
TraceV2Callback.java \
UpdateHookCallback.java \
ValueHolder.java \
WindowFunction.java \
XDestroyCallback.java \
sqlite3.java \
sqlite3_blob.java \
sqlite3_context.java \
sqlite3_stmt.java \
sqlite3_value.java \
) $(patsubst %,$(dir.src.jni)/wrapper1/%,\
AggregateFunction.java \
ScalarFunction.java \
SqlFunction.java \
Sqlite.java \
SqliteException.java \
ValueHolder.java \
WindowFunction.java \
)
JAVA_FILES.unittest := $(patsubst %,$(dir.src.jni)/%,\
capi/Tester1.java \
wrapper1/Tester2.java \
)
ifeq (1,$(enable.fts5))
JAVA_FILES.unittest += $(patsubst %,$(dir.src.fts5)/%,\
TesterFts5.java \
)
JAVA_FILES.main += $(patsubst %,$(dir.src.fts5)/%,\
fts5_api.java \
fts5_extension_function.java \
fts5_tokenizer.java \
Fts5.java \
Fts5Context.java \
Fts5ExtensionApi.java \
Fts5PhraseIter.java \
Fts5Tokenizer.java \
XTokenizeCallback.java \
)
endif
JAVA_FILES.tester := $(SQLTester.java)
JAVA_FILES.package.info := \
$(dir.src.jni)/package-info.java \
$(dir.src.jni)/annotation/package-info.java
CLASS_FILES.main := $(JAVA_FILES.main:.java=.class)
CLASS_FILES.unittest := $(JAVA_FILES.unittest:.java=.class)
CLASS_FILES.tester := $(JAVA_FILES.tester:.java=.class)
JAVA_FILES += $(JAVA_FILES.main) $(JAVA_FILES.unittest)
ifeq (1,$(enable.tester))
JAVA_FILES += $(JAVA_FILES.tester)
endif
CLASS_FILES :=
define CLASSFILE_DEPS
all: $(1).class
$(1).class: $(1).java
CLASS_FILES += $(1).class
endef
$(foreach B,$(basename \
$(JAVA_FILES.main) $(JAVA_FILES.unittest) $(JAVA_FILES.tester)),\
$(eval $(call CLASSFILE_DEPS,$(B))))
$(CLASS_FILES): $(MAKEFILE)
$(bin.javac) $(javac.flags) -h $(dir.bld.c) -cp $(classpath) $(JAVA_FILES)
#.PHONY: classfiles
########################################################################
# Set up sqlite3.c and sqlite3.h...
#
# To build with SEE (https://sqlite.org/see), either put sqlite3-see.c
# in the top of this build tree or pass
# sqlite3.c=PATH_TO_sqlite3-see.c to the build. Note that only
# encryption modules with no 3rd-party dependencies will currently
# work here: AES256-OFB, AES128-OFB, and AES128-CCM. Not
# coincidentally, those 3 modules are included in the sqlite3-see.c
# bundle.
#
# A custom sqlite3.c must not have any spaces in its name.
# $(sqlite3.canonical.c) must point to the sqlite3.c in
# the sqlite3 canonical source tree, as that source file
# is required for certain utility and test code.
sqlite3.canonical.c := $(firstword $(wildcard $(dir.src.c)/sqlite3.c) $(dir.top)/sqlite3.c)
sqlite3.canonical.h := $(firstword $(wildcard $(dir.src.c)/sqlite3.h) $(dir.top)/sqlite3.h)
sqlite3.c := $(sqlite3.canonical.c)
sqlite3.h := $(sqlite3.canonical.h)
#ifeq (,$(shell grep sqlite3_activate_see $(sqlite3.c) 2>/dev/null))
# SQLITE_C_IS_SEE := 0
#else
# SQLITE_C_IS_SEE := 1
# $(info This is an SEE build.)
#endif
.NOTPARALLEL: $(sqlite3.h)
$(sqlite3.h):
$(MAKE) -C $(dir.top) sqlite3.c
$(sqlite3.c): $(sqlite3.h)
opt.threadsafe ?= 1
opt.fatal-oom ?= 1
opt.debug ?= 1
opt.metrics ?= 1
SQLITE_OPT = \
-DSQLITE_THREADSAFE=$(opt.threadsafe) \
-DSQLITE_TEMP_STORE=2 \
-DSQLITE_USE_URI=1 \
-DSQLITE_OMIT_LOAD_EXTENSION \
-DSQLITE_OMIT_DEPRECATED \
-DSQLITE_OMIT_SHARED_CACHE \
-DSQLITE_C=$(sqlite3.c) \
-DSQLITE_JNI_FATAL_OOM=$(opt.fatal-oom) \
-DSQLITE_JNI_ENABLE_METRICS=$(opt.metrics)
opt.extras ?= 1
ifeq (1,$(opt.extras))
SQLITE_OPT += -DSQLITE_ENABLE_RTREE \
-DSQLITE_ENABLE_EXPLAIN_COMMENTS \
-DSQLITE_ENABLE_STMTVTAB \
-DSQLITE_ENABLE_DBPAGE_VTAB \
-DSQLITE_ENABLE_DBSTAT_VTAB \
-DSQLITE_ENABLE_BYTECODE_VTAB \
-DSQLITE_ENABLE_OFFSET_SQL_FUNC \
-DSQLITE_ENABLE_PREUPDATE_HOOK \
-DSQLITE_ENABLE_NORMALIZE \
-DSQLITE_ENABLE_SQLLOG \
-DSQLITE_ENABLE_COLUMN_METADATA
endif
ifeq (1,$(opt.debug))
SQLITE_OPT += -DSQLITE_DEBUG -g -DDEBUG -UNDEBUG
else
SQLITE_OPT += -Os
endif
ifeq (1,$(enable.fts5))
SQLITE_OPT += -DSQLITE_ENABLE_FTS5
endif
sqlite3-jni.c := $(dir.src.c)/sqlite3-jni.c
sqlite3-jni.o := $(dir.bld.c)/sqlite3-jni.o
sqlite3-jni.h := $(dir.src.c)/sqlite3-jni.h
package.dll := $(dir.bld.c)/libsqlite3-jni.so
# All javac-generated .h files must be listed in $(sqlite3-jni.h.in):
sqlite3-jni.h.in :=
# $(java.with.jni) lists all Java files which contain JNI decls:
java.with.jni :=
define ADD_JNI_H
sqlite3-jni.h.in += $$(dir.bld.c)/org_sqlite_jni$(3)_$(2).h
java.with.jni += $(1)/$(2).java
$$(dir.bld.c)/org_sqlite_jni$(3)_$(2).h: $(1)/$(2).java
endef
# Invoke ADD_JNI_H once for each Java file which includes JNI
# declarations:
$(eval $(call ADD_JNI_H,$(dir.src.capi),CApi,_capi))
$(eval $(call ADD_JNI_H,$(dir.src.capi),SQLTester,_capi))
ifeq (1,$(enable.fts5))
$(eval $(call ADD_JNI_H,$(dir.src.fts5),Fts5ExtensionApi,_fts5))
$(eval $(call ADD_JNI_H,$(dir.src.fts5),fts5_api,_fts5))
$(eval $(call ADD_JNI_H,$(dir.src.fts5),fts5_tokenizer,_fts5))
endif
$(sqlite3-jni.h.in): $(dir.bld.c)
#package.dll.cfiles :=
package.dll.cflags = \
-std=c99 \
-fPIC \
-I. \
-I$(dir $(sqlite3.h)) \
-I$(dir.src.c) \
-I$(JDK_HOME)/include \
$(patsubst %,-I%,$(patsubst %.h,,$(wildcard $(JDK_HOME)/include/*))) \
-Wall
# The gross $(patsubst...) above is to include the platform-specific
# subdir which lives under $(JDK_HOME)/include and is a required
# include path for client-level code.
#
# Using (-Wall -Wextra) triggers an untennable number of
# gcc warnings from sqlite3.c for mundane things like
# unused parameters.
########################################################################
ifeq (1,$(enable.tester))
package.dll.cflags += -DSQLITE_JNI_ENABLE_SQLTester
endif
$(sqlite3-jni.h): $(sqlite3-jni.h.in) $(MAKEFILE)
@cat $(sqlite3-jni.h.in) > $@.tmp
@if cmp $@ $@.tmp >/dev/null; then \
rm -f $@.tmp; \
echo "$@ not modified"; \
else \
mv $@.tmp $@; \
echo "Updated $@"; \
fi
@if [ x1 != x$(enable.fts5) ]; then \
echo "*** REMINDER:"; \
echo "*** enable.fts5=0, so please do not check in changes to $@."; \
fi
$(package.dll): $(sqlite3-jni.h) $(sqlite3.c) $(sqlite3.h)
$(package.dll): $(sqlite3-jni.c) $(MAKEFILE)
$(CC) $(package.dll.cflags) $(SQLITE_OPT) \
$(sqlite3-jni.c) -shared -o $@
all: $(package.dll)
.PHONY: test test-one
Tester1.flags ?=
Tester2.flags ?=
test.flags.jvm = -ea -Djava.library.path=$(dir.bld.c) \
$(java.flags) -cp $(classpath)
test.deps := $(CLASS_FILES) $(package.dll)
test-one: $(test.deps)
$(bin.java) $(test.flags.jvm) org.sqlite.jni.capi.Tester1 $(Tester1.flags)
$(bin.java) $(test.flags.jvm) org.sqlite.jni.wrapper1.Tester2 $(Tester2.flags)
test-sqllog: $(test.deps)
@echo "Testing with -sqllog..."
$(bin.java) $(test.flags.jvm) org.sqlite.jni.capi.Tester1 $(Tester1.flags) -sqllog
test-mt: $(test.deps)
@echo "Testing in multi-threaded mode:";
$(bin.java) $(test.flags.jvm) org.sqlite.jni.capi.Tester1 \
-t 7 -r 50 -shuffle $(Tester1.flags)
$(bin.java) $(test.flags.jvm) org.sqlite.jni.wrapper1.Tester2 \
-t 7 -r 50 -shuffle $(Tester2.flags)
test: test-one test-mt
tests: test test-sqllog
tester.scripts := $(sort $(wildcard $(dir.src)/tests/*.test))
tester.flags ?= # --verbose
.PHONY: tester tester-local tester-ext
ifeq (1,$(enable.tester))
tester-local: $(CLASS_FILES.tester) $(package.dll)
$(bin.java) -ea -Djava.library.path=$(dir.bld.c) \
$(java.flags) -cp $(classpath) \
org.sqlite.jni.capi.SQLTester $(tester.flags) $(tester.scripts)
tester: tester-local
else
tester:
@echo "SQLTester support is disabled."
endif
tester.extdir.default := $(dir.tests)/ext
tester.extdir ?= $(tester.extdir.default)
tester.extern-scripts := $(wildcard $(tester.extdir)/*.test)
ifneq (,$(tester.extern-scripts))
tester-ext:
$(bin.java) -ea -Djava.library.path=$(dir.bld.c) \
$(java.flags) -cp $(classpath) \
org.sqlite.jni.capi.SQLTester $(tester.flags) $(tester.extern-scripts)
else
tester-ext:
@echo "******************************************************"; \
echo "*** Include the out-of-tree test suite in the 'tester'"; \
echo "*** target by either symlinking its directory to"; \
echo "*** $(tester.extdir.default) or passing it to make"; \
echo "*** as tester.extdir=/path/to/that/dir."; \
echo "******************************************************";
endif
tester-ext: tester-local
tester: tester-ext
tests: tester
########################################################################
# Build each SQLITE_THREADMODE variant and run all tests against them.
multitest: clean
define MULTIOPT
multitest: multitest-$(1)
multitest-$(1):
$$(MAKE) opt.debug=$$(opt.debug) $(patsubst %,opt.%,$(2)) \
tests clean enable.fts5=1
endef
$(eval $(call MULTIOPT,01,threadsafe=0 oom=1))
$(eval $(call MULTIOPT,00,threadsafe=0 oom=0))
$(eval $(call MULTIOPT,11,threadsafe=1 oom=1))
$(eval $(call MULTIOPT,10,threadsafe=1 oom=0))
$(eval $(call MULTIOPT,21,threadsafe=2 oom=1))
$(eval $(call MULTIOPT,20,threadsafe=2 oom=0))
########################################################################
# jar bundle...
package.jar.in := $(abspath $(dir.src)/jar.in)
CLEAN_FILES += $(package.jar.in)
JAVA_FILES.jar := $(JAVA_FILES.main) $(JAVA_FILES.unittest) $(JAVA_FILES.package.info)
CLASS_FILES.jar := $(filter-out %/package-info.class,$(JAVA_FILES.jar:.java=.class))
$(package.jar.in): $(package.dll) $(MAKEFILE)
ls -1 \
$(dir.src.jni)/*/*.java $(dir.src.jni)/*/*.class \
| sed -e 's,^$(dir.src)/,,' | sort > $@
$(package.jar): $(CLASS_FILES.jar) $(MAKEFILE) $(package.jar.in)
@rm -f $(dir.src)/c/*~ $(dir.src.jni)/*~
cd $(dir.src); $(bin.jar) -cfe ../$@ org.sqlite.jni.capi.Tester1 @$(package.jar.in)
@ls -la $@
@echo "To use this jar you will need the -Djava.library.path=DIR/CONTAINING/libsqlite3-jni.so flag."
@echo "e.g. java -Djava.library.path=bld -jar $@"
jar: $(package.jar)
run-jar: $(package.jar) $(package.dll)
$(bin.java) -Djava.library.path=$(dir.bld) -jar $(package.jar) $(run-jar.flags)
########################################################################
# javadoc...
dir.doc := $(dir.jni)/javadoc
doc.index := $(dir.doc)/index.html
javadoc.exclude := -exclude org.sqlite.jni.fts5
# ^^^^ 2023-09-13: elide the fts5 parts from the public docs for
# the time being, as it's not clear where the Java bindings for
# those bits are going.
# javadoc.exclude += -exclude org.sqlite.jni.capi
# ^^^^ exclude the capi API only for certain builds (TBD)
$(doc.index): $(JAVA_FILES.main) $(MAKEFILE)
@if [ -d $(dir.doc) ]; then rm -fr $(dir.doc)/*; fi
$(bin.javadoc) -cp $(classpath) -d $(dir.doc) -quiet \
-subpackages org.sqlite.jni $(javadoc.exclude)
@echo "javadoc output is in $@"
.PHONY: doc javadoc docserve
.FORCE: doc
doc: $(doc.index)
javadoc: $(doc.index)
# Force rebuild of docs
redoc:
@rm -f $(doc.index)
@$(MAKE) doc
docserve: $(doc.index)
cd $(dir.doc) && althttpd -max-age 1 -page index.html
########################################################################
# Clean up...
CLEAN_FILES += $(dir.bld.c)/* \
$(dir.src.jni)/*.class \
$(dir.src.jni)/*/*.class \
$(package.dll) \
hs_err_pid*.log
.PHONY: clean distclean
clean:
-rm -f $(CLEAN_FILES)
distclean: clean
-rm -f $(DISTCLEAN_FILES)
-rm -fr $(dir.bld.c) $(dir.doc)
########################################################################
# distribution bundle rules...
ifeq (,$(filter snapshot,$(MAKECMDGOALS)))
dist-name-prefix := sqlite-jni
else
dist-name-prefix := sqlite-jni-snapshot-$(shell /usr/bin/date +%Y%m%d)
endif
dist-name := $(dist-name-prefix)-TEMP
dist-dir.top := $(dist-name)
dist-dir.src := $(dist-dir.top)/src
dist.top.extras := \
README.md
.PHONY: dist snapshot
dist: \
$(bin.version-info) $(sqlite3.canonical.c) \
$(package.jar) $(MAKEFILE)
@echo "Making end-user deliverables..."
@echo "****************************************************************************"; \
echo "*** WARNING: be sure to build this with JDK8 (javac 1.8) for compatibility."; \
echo "*** reasons!"; $$($(bin.javac) -version); \
echo "****************************************************************************"
@rm -fr $(dist-dir.top)
@mkdir -p $(dist-dir.src)
@cp -p $(dist.top.extras) $(dist-dir.top)/.
@cp -p jar-dist.make $(dist-dir.top)/Makefile
@cp -p $(dir.src.c)/*.[ch] $(dist-dir.src)/.
@cp -p $(sqlite3.canonical.c) $(sqlite3.canonical.h) $(dist-dir.src)/.
@set -e; \
vnum=$$($(bin.version-info) --download-version); \
vjar=$$($(bin.version-info) --version); \
vdir=$(dist-name-prefix)-$$vnum; \
arczip=$$vdir.zip; \
cp -p $(package.jar) $(dist-dir.top)/sqlite3-jni-$${vjar}.jar; \
echo "Making $$arczip ..."; \
rm -fr $$arczip $$vdir; \
mv $(dist-dir.top) $$vdir; \
zip -qr $$arczip $$vdir; \
rm -fr $$vdir; \
ls -la $$arczip; \
set +e; \
unzip -lv $$arczip || echo "Missing unzip app? Not fatal."
snapshot: dist
.PHONY: dist-clean
clean: dist-clean
dist-clean:
rm -fr $(dist-name) $(wildcard sqlite-jni-*.zip)
ext/jni/README.md
+316
View File
@@ -0,0 +1,316 @@
SQLite3 via JNI
========================================================================
This directory houses a Java Native Interface (JNI) binding for the
sqlite3 API. If you are reading this from the distribution ZIP file,
links to resources in the canonical source tree will note work. The
canonical copy of this file can be browsed at:
<https://sqlite.org/src/doc/trunk/ext/jni/README.md>
Technical support is available in the forum:
<https://sqlite.org/forum>
> **FOREWARNING:** this subproject is very much in development and
subject to any number of changes. Please do not rely on any
information about its API until this disclaimer is removed. The JNI
bindings released with version 3.43 are a "tech preview." Once
finalized, strong backward compatibility guarantees will apply.
Project goals/requirements:
- A [1-to-1(-ish) mapping of the C API](#1to1ish) to Java via JNI,
insofar as cross-language semantics allow for. A closely-related
goal is that [the C documentation](https://sqlite.org/c3ref/intro.html)
should be usable as-is, insofar as possible, for the JNI binding.
- Support Java as far back as version 8 (2014).
- Environment-independent. Should work everywhere both Java
and SQLite3 do.
- No 3rd-party dependencies beyond the JDK. That includes no
build-level dependencies for specific IDEs and toolchains. We
welcome the addition of build files for arbitrary environments
insofar as they neither interfere with each other nor become
a maintenance burden for the sqlite developers.
Non-goals:
- Creation of high-level OO wrapper APIs. Clients are free to create
them off of the C-style API.
- Virtual tables are unlikely to be supported due to the amount of
glue code needed to fit them into Java.
- Support for mixed-mode operation, where client code accesses SQLite
both via the Java-side API and the C API via their own native
code. Such cases would be a minefield of potential mis-interactions
between this project's JNI bindings and mixed-mode client code.
Hello World
-----------------------------------------------------------------------
```java
import org.sqlite.jni.*;
import static org.sqlite.jni.CApi.*;
...
final sqlite3 db = sqlite3_open(":memory:");
try {
final int rc = sqlite3_errcode(db);
if( 0 != rc ){
if( null != db ){
System.out.print("Error opening db: "+sqlite3_errmsg(db));
}else{
System.out.print("Error opening db: rc="+rc);
}
... handle error ...
}
// ... else use the db ...
}finally{
// ALWAYS close databases using sqlite3_close() or sqlite3_close_v2()
// when done with them. All of their active statement handles must
// first have been passed to sqlite3_finalize().
sqlite3_close_v2(db);
}
```
Building
========================================================================
The canonical builds assumes a Linux-like environment and requires:
- GNU Make
- A JDK supporting Java 8 or higher
- A modern C compiler. gcc and clang should both work.
Put simply:
```console
$ export JAVA_HOME=/path/to/jdk/root
$ make
$ make test
$ make clean
```
The jar distribution can be created with `make jar`, but note that it
does not contain the binary DLL file. A different DLL is needed for
each target platform.
<a id='1to1ish'></a>
One-to-One(-ish) Mapping to C
========================================================================
This JNI binding aims to provide as close to a 1-to-1 experience with
the C API as cross-language semantics allow. Interface changes are
necessarily made where cross-language semantics do not allow a 1-to-1,
and judiciously made where a 1-to-1 mapping would be unduly cumbersome
to use in Java. In all cases, this binding makes every effort to
provide semantics compatible with the C API documentation even if the
interface to those semantics is slightly different. Any cases which
deviate from those semantics (either removing or adding semantics) are
clearly documented.
Where it makes sense to do so for usability, Java-side overloads are
provided which accept or return data in alternative forms or provide
sensible default argument values. In all such cases they are thin
proxies around the corresponding C APIs and do not introduce new
semantics.
In a few cases, Java-specific capabilities have been added in
new APIs, all of which have "_java" somewhere in their names.
Examples include:
- `sqlite3_result_java_object()`
- `sqlite3_column_java_object()`
- `sqlite3_value_java_object()`
which, as one might surmise, collectively enable the passing of
arbitrary Java objects from user-defined SQL functions through to the
caller.
Golden Rule: Garbage Collection Cannot Free SQLite Resources
------------------------------------------------------------------------
It is important that all databases and prepared statement handles get
cleaned up by client code. A database cannot be closed if it has open
statement handles. `sqlite3_close()` fails if the db cannot be closed
whereas `sqlite3_close_v2()` recognizes that case and marks the db as
a "zombie," pending finalization when the library detects that all
pending statements have been closed. Be aware that Java garbage
collection _cannot_ close a database or finalize a prepared statement.
Those things require explicit API calls.
Classes for which it is sensible support Java's `AutoCloseable`
interface so can be used with try-with-resources constructs.
Golden Rule #2: _Never_ Throw from Callbacks (Unless...)
------------------------------------------------------------------------
All routines in this API, barring explicitly documented exceptions,
retain C-like semantics. For example, they are not permitted to throw
or propagate exceptions and must return error information (if any) via
result codes or `null`. The only cases where the C-style APIs may
throw is through client-side misuse, e.g. passing in a null where it
may cause a `NullPointerException`. The APIs clearly mark function
parameters which should not be null, but does not generally actively
defend itself against such misuse. Some C-style APIs explicitly accept
`null` as a no-op for usability's sake, and some of the JNI APIs
deliberately return an error code, instead of segfaulting, when passed
a `null`.
Client-defined callbacks _must never throw exceptions_ unless _very
explicitly documented_ as being throw-safe. Exceptions are generally
reserved for higher-level bindings which are constructed to
specifically deal with them and ensure that they do not leak C-level
resources. In some cases, callback handlers are permitted to throw, in
which cases they get translated to C-level result codes and/or
messages. If a callback which is not permitted to throw throws, its
exception may trigger debug output but will otherwise be suppressed.
The reason some callbacks are permitted to throw and others not is
because all such callbacks act as proxies for C function callback
interfaces and some of those interfaces have no error-reporting
mechanism. Those which are capable of propagating errors back through
the library convert exceptions from callbacks into corresponding
C-level error information. Those which cannot propagate errors
necessarily suppress any exceptions in order to maintain the C-style
semantics of the APIs.
Unwieldy Constructs are Re-mapped
------------------------------------------------------------------------
Some constructs, when modelled 1-to-1 from C to Java, are unduly
clumsy to work with in Java because they try to shoehorn C's way of
doing certain things into Java's wildly different ways. The following
subsections cover those, starting with a verbose explanation and
demonstration of where such changes are "really necessary"...
### Custom Collations
A prime example of where interface changes for Java are necessary for
usability is [registration of a custom
collation](https://sqlite.org/c3ref/create_collation.html):
```c
// C:
int sqlite3_create_collation(sqlite3 * db, const char * name, int eTextRep,
void *pUserData,
int (*xCompare)(void*,int,void const *,int,void const *));
int sqlite3_create_collation_v2(sqlite3 * db, const char * name, int eTextRep,
void *pUserData,
int (*xCompare)(void*,int,void const *,int,void const *),
void (*xDestroy)(void*));
```
The `pUserData` object is optional client-defined state for the
`xCompare()` and/or `xDestroy()` callback functions, both of which are
passed that object as their first argument. That data is passed around
"externally" in C because that's how C models the world. If we were to
bind that part as-is to Java, the result would be awkward to use (^Yes,
we tried this.):
```java
// Java:
int sqlite3_create_collation(sqlite3 db, String name, int eTextRep,
Object pUserData, xCompareType xCompare);
int sqlite3_create_collation_v2(sqlite3 db, String name, int eTextRep,
Object pUserData,
xCompareType xCompare, xDestroyType xDestroy);
```
The awkwardness comes from (A) having two distinctly different objects
for callbacks and (B) having their internal state provided separately,
which is ill-fitting in Java. For the sake of usability, C APIs which
follow that pattern use a slightly different Java interface:
```java
int sqlite3_create_collation(sqlite3 db, String name, int eTextRep,
SomeCallbackType collation);
```
Where the `Collation` class has an abstract `call()` method and
no-op `xDestroy()` method which can be overridden if needed, leading to
a much more Java-esque usage:
```java
int rc = sqlite3_create_collation(db, "mycollation", SQLITE_UTF8, new SomeCallbackType(){
// Required comparison function:
@Override public int call(byte[] lhs, byte[] rhs){ ... }
// Optional finalizer function:
@Override public void xDestroy(){ ... }
// Optional local state:
private String localState1 =
"This is local state. There are many like it, but this one is mine.";
private MyStateType localState2 = new MyStateType();
...
});
```
Noting that:
- It is possible to bind in call-scope-local state via closures, if
desired, as opposed to packing it into the Collation object.
- No capabilities of the C API are lost or unduly obscured via the
above API reshaping, so power users need not make any compromises.
- In the specific example above, `sqlite3_create_collation_v2()`
becomes superfluous because the provided interface effectively
provides both the v1 and v2 interfaces, the difference being that
overriding the `xDestroy()` method effectively gives it v2
semantics.
### User-defined SQL Functions (a.k.a. UDFs)
The [`sqlite3_create_function()`](https://sqlite.org/c3ref/create_function.html)
family of APIs make heavy use of function pointers to provide
client-defined callbacks, necessitating interface changes in the JNI
binding. The Java API has only one core function-registration function:
```java
int sqlite3_create_function(sqlite3 db, String funcName, int nArgs,
int encoding, SQLFunction func);
```
> Design question: does the encoding argument serve any purpose in
Java? That's as-yet undetermined. If not, it will be removed.
`SQLFunction` is not used directly, but is instead instantiated via
one of its three subclasses:
- `ScalarFunction` implements simple scalar functions using but a
single callback.
- `AggregateFunction` implements aggregate functions using two
callbacks.
- `WindowFunction` implements window functions using four
callbacks.
Search [`Tester1.java`](/file/ext/jni/src/org/sqlite/jni/capi/Tester1.java) for
`SQLFunction` for how it's used.
Reminder: see the disclaimer at the top of this document regarding the
in-flux nature of this API.
### And so on...
Various APIs which accept callbacks, e.g. `sqlite3_trace_v2()` and
`sqlite3_update_hook()`, use interfaces similar to those shown above.
Despite the changes in signature, the JNI layer makes every effort to
provide the same semantics as the C API documentation suggests.
ext/jni/jar-dist.make
+60
View File
@@ -0,0 +1,60 @@
#!/this/is/make
#^^^^ help emacs out
#
# This is a POSIX-make-compatible makefile for building the sqlite3
# JNI library from "dist" zip file. It must be edited to set the
# proper top-level JDK directory and, depending on the platform, add a
# platform-specific -I directory. It should build as-is with any
# 2020s-era version of gcc or clang. It requires JDK version 8 or
# higher and that JAVA_HOME points to the top-most installation
# directory of that JDK. On Ubuntu-style systems the JDK is typically
# installed under /usr/lib/jvm/java-VERSION-PLATFORM.
default: all
JAVA_HOME = /usr/lib/jvm/java-1.8.0-openjdk-amd64
CFLAGS = \
-fPIC \
-Isrc \
-I$(JAVA_HOME)/include \
-I$(JAVA_HOME)/include/linux \
-I$(JAVA_HOME)/include/apple \
-I$(JAVA_HOME)/include/bsd \
-Wall
SQLITE_OPT = \
-DSQLITE_ENABLE_RTREE \
-DSQLITE_ENABLE_EXPLAIN_COMMENTS \
-DSQLITE_ENABLE_STMTVTAB \
-DSQLITE_ENABLE_DBPAGE_VTAB \
-DSQLITE_ENABLE_DBSTAT_VTAB \
-DSQLITE_ENABLE_BYTECODE_VTAB \
-DSQLITE_ENABLE_OFFSET_SQL_FUNC \
-DSQLITE_OMIT_LOAD_EXTENSION \
-DSQLITE_OMIT_DEPRECATED \
-DSQLITE_OMIT_SHARED_CACHE \
-DSQLITE_THREADSAFE=1 \
-DSQLITE_TEMP_STORE=2 \
-DSQLITE_USE_URI=1 \
-DSQLITE_ENABLE_FTS5 \
-DSQLITE_DEBUG
sqlite3-jni.dll = libsqlite3-jni.so
$(sqlite3-jni.dll):
@echo "************************************************************************"; \
echo "*** If this fails to build, be sure to edit this makefile ***"; \
echo "*** to configure it for your system. ***"; \
echo "************************************************************************"
$(CC) $(CFLAGS) $(SQLITE_OPT) \
src/sqlite3-jni.c -shared -o $@
@echo "Now try running it with: make test"
test.flags = -Djava.library.path=. sqlite3-jni-*.jar
test: $(sqlite3-jni.dll)
java -jar $(test.flags)
java -jar $(test.flags) -t 7 -r 10 -shuffle
clean:
-rm -f $(sqlite3-jni.dll)
all: $(sqlite3-jni.dll)
ext/jni/src/c/sqlite3-jni.c
+6343
View File
File diff suppressed because it is too large. Load diff
ext/jni/src/c/sqlite3-jni.h
+2461
View File
File diff suppressed because it is too large. Load diff
ext/jni/src/org/sqlite/jni/annotation/Experimental.java
+30
View File
@@ -0,0 +1,30 @@
/*
** 2023-09-27
**
** 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 houses the Experimental annotation for the sqlite3 C API.
*/
package org.sqlite.jni.annotation;
import java.lang.annotation.*;
/**
This annotation is for flagging methods, constructors, and types
which are expressly experimental and subject to any amount of
change or outright removal. Client code should not rely on such
features.
*/
@Documented
@Retention(RetentionPolicy.SOURCE)
@Target({
ElementType.METHOD,
ElementType.CONSTRUCTOR,
ElementType.TYPE
})
public @interface Experimental{}
ext/jni/src/org/sqlite/jni/annotation/NotNull.java
+71
View File
@@ -0,0 +1,71 @@
/*
** 2023-09-27
**
** 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 houses the NotNull annotation for the sqlite3 C API.
*/
package org.sqlite.jni.annotation;
import java.lang.annotation.*;
/**
This annotation is for flagging parameters which may not legally be
null or point to closed/finalized C-side resources.
<p>In the case of Java types which map directly to C struct types
(e.g. {@link org.sqlite.jni.capi.sqlite3}, {@link
org.sqlite.jni.capi.sqlite3_stmt}, and {@link
org.sqlite.jni.capi.sqlite3_context}), a closed/finalized resource
is also considered to be null for purposes this annotation because
the C-side effect of passing such a handle is the same as if null
is passed.</p>
<p>When used in the context of Java interfaces which are called
from the C APIs, this annotation communicates that the C API will
never pass a null value to the callback for that parameter.</p>
<p>Passing a null, for this annotation's definition of null, for
any parameter marked with this annotation specifically invokes
undefined behavior (see below).</p>
<p>Passing 0 (i.e. C NULL) or a negative value for any long-type
parameter marked with this annotation specifically invokes undefined
behavior (see below). Such values are treated as C pointers in the
JNI layer.</p>
<p><b>Undefined behaviour:</b> the JNI build uses the {@code
SQLITE_ENABLE_API_ARMOR} build flag, meaning that the C code
invoked with invalid NULL pointers and the like will not invoke
undefined behavior in the conventional C sense, but may, for
example, return result codes which are not documented for the
affected APIs or may otherwise behave unpredictably. In no known
cases will such arguments result in C-level code dereferencing a
NULL pointer or accessing out-of-bounds (or otherwise invalid)
memory. In other words, they may cause unexpected behavior but
should never cause an outright crash or security issue.</p>
<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>
<p>This annotation is informational only. No policy is in place to
programmatically ensure that NotNull is conformed to in client
code.</p>
<p>This annotation is solely for the use by the classes in the
org.sqlite.jni package and subpackages, but is made public so that
javadoc will link to it from the annotated functions. It is not
part of the public API and client-level code must not rely on
it.</p>
*/
@Documented
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.PARAMETER)
public @interface NotNull{}
ext/jni/src/org/sqlite/jni/annotation/Nullable.java
+33
View File
@@ -0,0 +1,33 @@
/*
** 2023-09-27
**
** 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 houses the Nullable annotation for the sqlite3 C API.
*/
package org.sqlite.jni.annotation;
import java.lang.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. 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
annotated functions. It is not part of the public API and
client-level code must not rely on it.
*/
@Documented
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.PARAMETER)
public @interface Nullable{}
ext/jni/src/org/sqlite/jni/annotation/package-info.java
+17
View File
@@ -0,0 +1,17 @@
/*
** 2023-09-27
**
** 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 package houses annotations specific to the JNI bindings of the
SQLite3 C API.
*/
package org.sqlite.jni.annotation;
ext/jni/src/org/sqlite/jni/capi/AbstractCollationCallback.java
+34
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.capi;
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(){}
}
ext/jni/src/org/sqlite/jni/capi/AggregateFunction.java
+138
View File
@@ -0,0 +1,138 @@
/*
** 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.capi;
/**
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> implements SQLFunction {
/**
As for the xStep() argument of the C API's
sqlite3_create_function(). If this function throws, the
exception is not propagated and a warning might be emitted to a
debugging channel.
*/
public abstract void xStep(sqlite3_context cx, sqlite3_value[] args);
/**
As for the xFinal() argument of the C API's sqlite3_create_function().
If this function throws, it is translated into an sqlite3_result_error().
*/
public abstract void xFinal(sqlite3_context cx);
/**
Optionally override to be notified when the UDF is finalized by
SQLite.
*/
public void xDestroy() {}
/**
PerContextState assists aggregate and window functions in
managing their accumulator state across calls to the UDF's
callbacks.
<p>T must be of a type which can be legally stored as a value in
java.util.HashMap<KeyType,T>.
<p>If a given aggregate or window function is called multiple times
in a single SQL statement, e.g. SELECT MYFUNC(A), MYFUNC(B)...,
then the clients need some way of knowing which call is which so
that they can map their state between their various UDF callbacks
and reset it via xFinal(). This class takes care of such
mappings.
<p>This class works by mapping
sqlite3_context.getAggregateContext() to a single piece of
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.
Client UDFs are free to perform such mappings using custom
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
= new java.util.HashMap<>();
/**
Should be called from a UDF's xStep(), xValue(), and xInverse()
methods, passing it that method's first argument and an initial
value for the persistent state. If there is currently no
mapping for the given context within the map, one is created
using the given initial value, else the existing one is used
and the 2nd argument is ignored. It returns a ValueHolder<T>
which can be used to modify that state directly without
requiring that the client update the underlying map's entry.
<p>The caller is obligated to eventually call
takeAggregateState() to clear the mapping.
*/
public ValueHolder<T> getAggregateState(sqlite3_context cx, T initialValue){
final Long key = cx.getAggregateContext(true);
ValueHolder<T> rc = null==key ? null : map.get(key);
if( null==rc ){
map.put(key, rc = new ValueHolder<>(initialValue));
}
return rc;
}
/**
Should be called from a UDF's xFinal() method and passed that
method's first argument. This function removes the value
associated with cx.getAggregateContext() from the map and
returns it, returning null if no other UDF method has been
called to set up such a mapping. The latter condition will be
the case if a UDF is used in a statement which has no result
rows.
*/
public T takeAggregateState(sqlite3_context cx){
final ValueHolder<T> h = map.remove(cx.getAggregateContext(false));
return null==h ? null : h.value;
}
}
/** Per-invocation state for the UDF. */
private final PerContextState<T> map = new PerContextState<>();
/**
To be called from the implementation's xStep() method, as well
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
calls, the 2nd argument is ignored.
@see SQLFunction.PerContextState#getAggregateState
*/
protected final ValueHolder<T> getAggregateState(sqlite3_context cx, T initialValue){
return map.getAggregateState(cx, initialValue);
}
/**
To be called from the implementation's xFinal() method to fetch
the final state of the UDF and remove its mapping.
see SQLFunction.PerContextState#takeAggregateState
*/
protected final T takeAggregateState(sqlite3_context cx){
return map.takeAggregateState(cx);
}
}
ext/jni/src/org/sqlite/jni/capi/AuthorizerCallback.java
+29
View File
@@ -0,0 +1,29 @@
/*
** 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.capi;
import org.sqlite.jni.annotation.*;
/**
Callback for use with {@link CApi#sqlite3_set_authorizer}.
*/
public interface AuthorizerCallback extends CallbackProxy {
/**
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, @Nullable String s1, @Nullable String s2,
@Nullable String s3, @Nullable String s4);
}
ext/jni/src/org/sqlite/jni/capi/AutoExtensionCallback.java
+40
View File
@@ -0,0 +1,40 @@
/*
** 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.capi;
/**
Callback for use with the {@link CApi#sqlite3_auto_extension}
family of APIs.
*/
public interface AutoExtensionCallback extends CallbackProxy {
/**
Must function as described for a C-level
sqlite3_auto_extension() callback.
<p>This callback may throw and the exception's error message will
be set as the db's error string.
<p>Tips for implementations:
<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.
<p>- If this routine is stateful, it may be useful to make the
overridden method synchronized.
<p>- Results are undefined if the given db is closed by an auto-extension.
*/
int call(sqlite3 db);
}
ext/jni/src/org/sqlite/jni/capi/BusyHandlerCallback.java
+26
View File
@@ -0,0 +1,26 @@
/*
** 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.capi;
/**
Callback for use with {@link CApi#sqlite3_busy_handler}.
*/
public interface BusyHandlerCallback extends CallbackProxy {
/**
Must function as documented for the C-level
sqlite3_busy_handler() callback argument, minus the (void*)
argument the C-level function requires.
*/
int call(int n);
}
ext/jni/src/org/sqlite/jni/capi/CApi.java
+2892
View File
File diff suppressed because it is too large. Load diff
ext/jni/src/org/sqlite/jni/capi/CallbackProxy.java
+45
View File
@@ -0,0 +1,45 @@
/*
** 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.capi;
/**
This marker interface exists solely for use as a documentation and
class-grouping tool. It should be applied to interfaces or
classes which have a call() method implementing some specific
callback interface on behalf of the C library.
<p>Unless very explicitly 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 returning error information, all exceptions will
necessarily be suppressed in order to retain the C-style no-throw
semantics and avoid invoking undefined behavior in the C layer.
<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 {@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 {@code call()} method but its signature is
callback-specific.
*/
public interface CallbackProxy {}
ext/jni/src/org/sqlite/jni/capi/CollationCallback.java
+35
View File
@@ -0,0 +1,35 @@
/*
** 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.capi;
import org.sqlite.jni.annotation.NotNull;
/**
Callback for use with {@link CApi#sqlite3_create_collation}.
@see AbstractCollationCallback
*/
public interface CollationCallback
extends CallbackProxy, XDestroyCallback {
/**
Must compare the given byte arrays and return the result using
{@code memcmp()} semantics.
*/
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.
*/
void xDestroy();
}
ext/jni/src/org/sqlite/jni/capi/CollationNeededCallback.java
+29
View File
@@ -0,0 +1,29 @@
/*
** 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.capi;
/**
Callback for use with {@link CApi#sqlite3_collation_needed}.
*/
public interface CollationNeededCallback extends CallbackProxy {
/**
Has the same semantics as the C-level sqlite3_create_collation()
callback.
<p>Because the C API has no mechanism for reporting errors
from this callbacks, any exceptions thrown by this callback
are suppressed.
*/
void call(sqlite3 db, int eTextRep, String collationName);
}
ext/jni/src/org/sqlite/jni/capi/CommitHookCallback.java
+26
View File
@@ -0,0 +1,26 @@
/*
** 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.capi;
/**
Callback for use with {@link CApi#sqlite3_commit_hook}.
*/
public interface CommitHookCallback extends CallbackProxy {
/**
Works as documented for the C-level sqlite3_commit_hook()
callback. If it throws, the exception is translated into
a db-level error.
*/
int call();
}
ext/jni/src/org/sqlite/jni/capi/ConfigLogCallback.java
+25
View File
@@ -0,0 +1,25 @@
/*
** 2023-08-23
**
** 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.capi;
/**
A callback for use with sqlite3_config().
*/
public interface ConfigLogCallback {
/**
Must function as described for a C-level callback for
{@link CApi#sqlite3_config(ConfigLogCallback)}, with the slight signature change.
*/
void call(int errCode, String msg);
}
ext/jni/src/org/sqlite/jni/capi/ConfigSqlLogCallback.java
+25
View File
@@ -0,0 +1,25 @@
/*
** 2023-08-23
**
** 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.capi;
/**
A callback for use with sqlite3_config().
*/
public interface ConfigSqlLogCallback {
/**
Must function as described for a C-level callback for
{@link CApi#sqlite3_config(ConfigSqlLogCallback)}, with the slight signature change.
*/
void call(sqlite3 db, String msg, int msgType );
}
ext/jni/src/org/sqlite/jni/capi/NativePointerHolder.java
+46
View File
@@ -0,0 +1,46 @@
/*
** 2023-07-21
**
** 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.capi;
/**
A helper for passing pointers between JNI C code and Java, in
particular for output pointers of high-level object types in the
sqlite3 C API, e.g. (sqlite3**) and (sqlite3_stmt**). This is
intended to be subclassed and the ContextType is intended to be the
class which is doing the subclassing. The intent of the ContextType
is strictly to provide some level of type safety by avoiding that
NativePointerHolder is not inadvertently passed to an incompatible
function signature.
These objects do not own the pointer they refer to. They are
intended simply to communicate that pointer between C and Java.
*/
public class NativePointerHolder<ContextType> {
//! Only set from JNI, where access permissions don't matter.
private volatile long nativePointer = 0;
/**
For use ONLY by package-level APIs which act as proxies for
close/finalize operations. Such ops must call this to zero out
the pointer so that this object is not carrying a stale
pointer. This function returns the prior value of the pointer and
sets it to 0.
*/
final long clearNativePointer() {
final long rv = nativePointer;
nativePointer= 0;
return rv;
}
public final long getNativePointer(){ return nativePointer; }
}
ext/jni/src/org/sqlite/jni/capi/OutputPointer.java
+253
View File
@@ -0,0 +1,253 @@
/*
** 2023-07-21
**
** 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.capi;
/**
Helper classes for handling JNI output pointers.
<p>We do not use a generic OutputPointer<T> because working with those
from the native JNI code is unduly quirky due to a lack of
autoboxing at that level.
<p>The usage is similar for all of these types:
<pre>{@code
OutputPointer.sqlite3 out = new OutputPointer.sqlite3();
assert( null==out.get() );
int rc = sqlite3_open(":memory:", out);
if( 0!=rc ) ... error;
assert( null!=out.get() );
sqlite3 db = out.take();
assert( null==out.get() );
}</pre>
<p>With the minor exception that the primitive types permit direct
access to the object's value via the `value` property, whereas the
JNI-level opaque types do not permit client-level code to set that
property.
<p>Warning: do not share instances of these classes across
threads. Doing so may lead to corrupting sqlite3-internal state.
*/
public final class OutputPointer {
/**
Output pointer for use with routines, such as sqlite3_open(),
which return a database handle via an output pointer. These
pointers can only be set by the JNI layer, not by client-level
code.
*/
public static final class sqlite3 {
private org.sqlite.jni.capi.sqlite3 value;
/** Initializes with a null value. */
public sqlite3(){value = null;}
/** Sets the current value to null. */
public void clear(){value = null;}
/** Returns the current value. */
public org.sqlite.jni.capi.sqlite3 get(){return value;}
/** Equivalent to calling get() then clear(). */
public org.sqlite.jni.capi.sqlite3 take(){
final org.sqlite.jni.capi.sqlite3 v = value;
value = null;
return v;
}
}
/**
Output pointer for sqlite3_blob_open(). These
pointers can only be set by the JNI layer, not by client-level
code.
*/
public static final class sqlite3_blob {
private org.sqlite.jni.capi.sqlite3_blob value;
/** Initializes with a null value. */
public sqlite3_blob(){value = null;}
/** Sets the current value to null. */
public void clear(){value = null;}
/** Returns the current value. */
public org.sqlite.jni.capi.sqlite3_blob get(){return value;}
/** Equivalent to calling get() then clear(). */
public org.sqlite.jni.capi.sqlite3_blob take(){
final org.sqlite.jni.capi.sqlite3_blob v = value;
value = null;
return v;
}
}
/**
Output pointer for use with routines, such as sqlite3_prepare(),
which return a statement handle via an output pointer. These
pointers can only be set by the JNI layer, not by client-level
code.
*/
public static final class sqlite3_stmt {
private org.sqlite.jni.capi.sqlite3_stmt value;
/** Initializes with a null value. */
public sqlite3_stmt(){value = null;}
/** Sets the current value to null. */
public void clear(){value = null;}
/** Returns the current value. */
public org.sqlite.jni.capi.sqlite3_stmt get(){return value;}
/** Equivalent to calling get() then clear(). */
public org.sqlite.jni.capi.sqlite3_stmt take(){
final org.sqlite.jni.capi.sqlite3_stmt v = value;
value = null;
return v;
}
}
/**
Output pointer for use with routines, such as sqlite3_prepupdate_new(),
which return a sqlite3_value handle via an output pointer. These
pointers can only be set by the JNI layer, not by client-level
code.
*/
public static final class sqlite3_value {
private org.sqlite.jni.capi.sqlite3_value value;
/** Initializes with a null value. */
public sqlite3_value(){value = null;}
/** Sets the current value to null. */
public void clear(){value = null;}
/** Returns the current value. */
public org.sqlite.jni.capi.sqlite3_value get(){return value;}
/** Equivalent to calling get() then clear(). */
public org.sqlite.jni.capi.sqlite3_value take(){
final org.sqlite.jni.capi.sqlite3_value v = value;
value = null;
return v;
}
}
/**
Output pointer for use with native routines which return booleans
via integer output pointers.
*/
public static final class Bool {
/**
This is public for ease of use. Accessors are provided for
consistency with the higher-level types.
*/
public boolean value;
/** Initializes with the value 0. */
public Bool(){this(false);}
/** Initializes with the value v. */
public Bool(boolean v){value = v;}
/** Returns the current value. */
public boolean get(){return value;}
/** Sets the current value to v. */
public void set(boolean v){value = v;}
}
/**
Output pointer for use with native routines which return integers via
output pointers.
*/
public static final class Int32 {
/**
This is public for ease of use. Accessors are provided for
consistency with the higher-level types.
*/
public int value;
/** Initializes with the value 0. */
public Int32(){this(0);}
/** Initializes with the value v. */
public Int32(int v){value = v;}
/** Returns the current value. */
public int get(){return value;}
/** Sets the current value to v. */
public void set(int v){value = v;}
}
/**
Output pointer for use with native routines which return 64-bit integers
via output pointers.
*/
public static final class Int64 {
/**
This is public for ease of use. Accessors are provided for
consistency with the higher-level types.
*/
public long value;
/** Initializes with the value 0. */
public Int64(){this(0);}
/** Initializes with the value v. */
public Int64(long v){value = v;}
/** Returns the current value. */
public long get(){return value;}
/** Sets the current value. */
public void set(long v){value = v;}
}
/**
Output pointer for use with native routines which return strings via
output pointers.
*/
public static final class String {
/**
This is public for ease of use. Accessors are provided for
consistency with the higher-level types.
*/
public java.lang.String value;
/** Initializes with a null value. */
public String(){this(null);}
/** Initializes with the value v. */
public String(java.lang.String v){value = v;}
/** Returns the current value. */
public java.lang.String get(){return value;}
/** Sets the current value. */
public void set(java.lang.String v){value = v;}
}
/**
Output pointer for use with native routines which return byte
arrays via output pointers.
*/
public static final class ByteArray {
/**
This is public for ease of use. Accessors are provided for
consistency with the higher-level types.
*/
public byte[] value;
/** Initializes with the value null. */
public ByteArray(){this(null);}
/** Initializes with the value v. */
public ByteArray(byte[] v){value = v;}
/** Returns the current value. */
public byte[] get(){return value;}
/** Sets the current value. */
public void set(byte[] v){value = v;}
}
/**
Output pointer for use with native routines which return
blobs via java.nio.ByteBuffer.
See {@link org.sqlite.jni.capi.CApi#sqlite3_jni_supports_nio}
*/
public static final class ByteBuffer {
/**
This is public for ease of use. Accessors are provided for
consistency with the higher-level types.
*/
public java.nio.ByteBuffer value;
/** Initializes with the value null. */
public ByteBuffer(){this(null);}
/** Initializes with the value v. */
public ByteBuffer(java.nio.ByteBuffer v){value = v;}
/** Returns the current value. */
public java.nio.ByteBuffer get(){return value;}
/** Sets the current value. */
public void set(java.nio.ByteBuffer v){value = v;}
}
}
ext/jni/src/org/sqlite/jni/capi/PrepareMultiCallback.java
+81
View File
@@ -0,0 +1,81 @@
/*
** 2023-09-13
**
** 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.capi;
/**
Callback for use with {@link CApi#sqlite3_prepare_multi}.
*/
public interface PrepareMultiCallback extends CallbackProxy {
/**
Gets passed a sqlite3_stmt which it may handle in arbitrary ways,
transferring ownership of it to this function.
sqlite3_prepare_multi() will _not_ finalize st - it is up
to the call() implementation how st is handled.
Must return 0 on success or an SQLITE_... code on error. If it
throws, sqlite3_prepare_multi() will transform the exception into
a db-level error in order to retain the C-style error semantics
of the API.
See the {@link Finalize} class for a wrapper which finalizes the
statement after calling a proxy PrepareMultiCallback.
*/
int call(sqlite3_stmt st);
/**
A PrepareMultiCallback impl which wraps a separate impl and finalizes
any sqlite3_stmt passed to its callback.
*/
public static final class Finalize implements PrepareMultiCallback {
private final PrepareMultiCallback p;
/**
p is the proxy to call() when this.call() is called.
*/
public Finalize( PrepareMultiCallback p ){
this.p = p;
}
/**
Calls the call() method of the proxied callback and either returns its
result or propagates an exception. Either way, it passes its argument to
sqlite3_finalize() before returning.
*/
@Override public int call(sqlite3_stmt st){
try {
return this.p.call(st);
}finally{
CApi.sqlite3_finalize(st);
}
}
}
/**
A PrepareMultiCallback impl which steps entirely through a result set,
ignoring all non-error results.
*/
final class StepAll implements PrepareMultiCallback {
public StepAll(){}
/**
Calls sqlite3_step() on st until it returns something other than
SQLITE_ROW. If the final result is SQLITE_DONE then 0 is returned,
else the result of the final step is returned.
*/
@Override public int call(sqlite3_stmt st){
int rc = CApi.SQLITE_DONE;
while( CApi.SQLITE_ROW == (rc = CApi.sqlite3_step(st)) ){}
return CApi.SQLITE_DONE==rc ? 0 : rc;
}
}
}
ext/jni/src/org/sqlite/jni/capi/PreupdateHookCallback.java
+27
View File
@@ -0,0 +1,27 @@
/*
** 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.capi;
/**
Callback for use with {@link CApi#sqlite3_preupdate_hook}.
*/
public interface PreupdateHookCallback extends CallbackProxy {
/**
Must function as described for the C-level sqlite3_preupdate_hook()
callback. If it throws, the exception is translated to a
db-level error and the exception is suppressed.
*/
void call(sqlite3 db, int op, String dbName, String dbTable,
long iKey1, long iKey2 );
}
ext/jni/src/org/sqlite/jni/capi/ProgressHandlerCallback.java
+27
View File
@@ -0,0 +1,27 @@
/*
** 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.capi;
/**
Callback for use with {@link CApi#sqlite3_progress_handler}.
*/
public interface ProgressHandlerCallback extends CallbackProxy {
/**
Works as documented for the C-level sqlite3_progress_handler() callback.
<p>If it throws, the exception message is passed on to the db and
the exception is suppressed.
*/
int call();
}
ext/jni/src/org/sqlite/jni/capi/ResultCode.java
+155
View File
@@ -0,0 +1,155 @@
/*
** 2023-07-21
**
** 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.capi;
/**
This enum contains all of the core and "extended" result codes used
by the sqlite3 library. It is provided not for use with the C-style
API (with which it won't work) but for higher-level code which may
find it useful to map SQLite result codes to human-readable names.
*/
public enum ResultCode {
SQLITE_OK(CApi.SQLITE_OK),
SQLITE_ERROR(CApi.SQLITE_ERROR),
SQLITE_INTERNAL(CApi.SQLITE_INTERNAL),
SQLITE_PERM(CApi.SQLITE_PERM),
SQLITE_ABORT(CApi.SQLITE_ABORT),
SQLITE_BUSY(CApi.SQLITE_BUSY),
SQLITE_LOCKED(CApi.SQLITE_LOCKED),
SQLITE_NOMEM(CApi.SQLITE_NOMEM),
SQLITE_READONLY(CApi.SQLITE_READONLY),
SQLITE_INTERRUPT(CApi.SQLITE_INTERRUPT),
SQLITE_IOERR(CApi.SQLITE_IOERR),
SQLITE_CORRUPT(CApi.SQLITE_CORRUPT),
SQLITE_NOTFOUND(CApi.SQLITE_NOTFOUND),
SQLITE_FULL(CApi.SQLITE_FULL),
SQLITE_CANTOPEN(CApi.SQLITE_CANTOPEN),
SQLITE_PROTOCOL(CApi.SQLITE_PROTOCOL),
SQLITE_EMPTY(CApi.SQLITE_EMPTY),
SQLITE_SCHEMA(CApi.SQLITE_SCHEMA),
SQLITE_TOOBIG(CApi.SQLITE_TOOBIG),
SQLITE_CONSTRAINT(CApi.SQLITE_CONSTRAINT),
SQLITE_MISMATCH(CApi.SQLITE_MISMATCH),
SQLITE_MISUSE(CApi.SQLITE_MISUSE),
SQLITE_NOLFS(CApi.SQLITE_NOLFS),
SQLITE_AUTH(CApi.SQLITE_AUTH),
SQLITE_FORMAT(CApi.SQLITE_FORMAT),
SQLITE_RANGE(CApi.SQLITE_RANGE),
SQLITE_NOTADB(CApi.SQLITE_NOTADB),
SQLITE_NOTICE(CApi.SQLITE_NOTICE),
SQLITE_WARNING(CApi.SQLITE_WARNING),
SQLITE_ROW(CApi.SQLITE_ROW),
SQLITE_DONE(CApi.SQLITE_DONE),
SQLITE_ERROR_MISSING_COLLSEQ(CApi.SQLITE_ERROR_MISSING_COLLSEQ),
SQLITE_ERROR_RETRY(CApi.SQLITE_ERROR_RETRY),
SQLITE_ERROR_SNAPSHOT(CApi.SQLITE_ERROR_SNAPSHOT),
SQLITE_IOERR_READ(CApi.SQLITE_IOERR_READ),
SQLITE_IOERR_SHORT_READ(CApi.SQLITE_IOERR_SHORT_READ),
SQLITE_IOERR_WRITE(CApi.SQLITE_IOERR_WRITE),
SQLITE_IOERR_FSYNC(CApi.SQLITE_IOERR_FSYNC),
SQLITE_IOERR_DIR_FSYNC(CApi.SQLITE_IOERR_DIR_FSYNC),
SQLITE_IOERR_TRUNCATE(CApi.SQLITE_IOERR_TRUNCATE),
SQLITE_IOERR_FSTAT(CApi.SQLITE_IOERR_FSTAT),
SQLITE_IOERR_UNLOCK(CApi.SQLITE_IOERR_UNLOCK),
SQLITE_IOERR_RDLOCK(CApi.SQLITE_IOERR_RDLOCK),
SQLITE_IOERR_DELETE(CApi.SQLITE_IOERR_DELETE),
SQLITE_IOERR_BLOCKED(CApi.SQLITE_IOERR_BLOCKED),
SQLITE_IOERR_NOMEM(CApi.SQLITE_IOERR_NOMEM),
SQLITE_IOERR_ACCESS(CApi.SQLITE_IOERR_ACCESS),
SQLITE_IOERR_CHECKRESERVEDLOCK(CApi.SQLITE_IOERR_CHECKRESERVEDLOCK),
SQLITE_IOERR_LOCK(CApi.SQLITE_IOERR_LOCK),
SQLITE_IOERR_CLOSE(CApi.SQLITE_IOERR_CLOSE),
SQLITE_IOERR_DIR_CLOSE(CApi.SQLITE_IOERR_DIR_CLOSE),
SQLITE_IOERR_SHMOPEN(CApi.SQLITE_IOERR_SHMOPEN),
SQLITE_IOERR_SHMSIZE(CApi.SQLITE_IOERR_SHMSIZE),
SQLITE_IOERR_SHMLOCK(CApi.SQLITE_IOERR_SHMLOCK),
SQLITE_IOERR_SHMMAP(CApi.SQLITE_IOERR_SHMMAP),
SQLITE_IOERR_SEEK(CApi.SQLITE_IOERR_SEEK),
SQLITE_IOERR_DELETE_NOENT(CApi.SQLITE_IOERR_DELETE_NOENT),
SQLITE_IOERR_MMAP(CApi.SQLITE_IOERR_MMAP),
SQLITE_IOERR_GETTEMPPATH(CApi.SQLITE_IOERR_GETTEMPPATH),
SQLITE_IOERR_CONVPATH(CApi.SQLITE_IOERR_CONVPATH),
SQLITE_IOERR_VNODE(CApi.SQLITE_IOERR_VNODE),
SQLITE_IOERR_AUTH(CApi.SQLITE_IOERR_AUTH),
SQLITE_IOERR_BEGIN_ATOMIC(CApi.SQLITE_IOERR_BEGIN_ATOMIC),
SQLITE_IOERR_COMMIT_ATOMIC(CApi.SQLITE_IOERR_COMMIT_ATOMIC),
SQLITE_IOERR_ROLLBACK_ATOMIC(CApi.SQLITE_IOERR_ROLLBACK_ATOMIC),
SQLITE_IOERR_DATA(CApi.SQLITE_IOERR_DATA),
SQLITE_IOERR_CORRUPTFS(CApi.SQLITE_IOERR_CORRUPTFS),
SQLITE_LOCKED_SHAREDCACHE(CApi.SQLITE_LOCKED_SHAREDCACHE),
SQLITE_LOCKED_VTAB(CApi.SQLITE_LOCKED_VTAB),
SQLITE_BUSY_RECOVERY(CApi.SQLITE_BUSY_RECOVERY),
SQLITE_BUSY_SNAPSHOT(CApi.SQLITE_BUSY_SNAPSHOT),
SQLITE_BUSY_TIMEOUT(CApi.SQLITE_BUSY_TIMEOUT),
SQLITE_CANTOPEN_NOTEMPDIR(CApi.SQLITE_CANTOPEN_NOTEMPDIR),
SQLITE_CANTOPEN_ISDIR(CApi.SQLITE_CANTOPEN_ISDIR),
SQLITE_CANTOPEN_FULLPATH(CApi.SQLITE_CANTOPEN_FULLPATH),
SQLITE_CANTOPEN_CONVPATH(CApi.SQLITE_CANTOPEN_CONVPATH),
SQLITE_CANTOPEN_SYMLINK(CApi.SQLITE_CANTOPEN_SYMLINK),
SQLITE_CORRUPT_VTAB(CApi.SQLITE_CORRUPT_VTAB),
SQLITE_CORRUPT_SEQUENCE(CApi.SQLITE_CORRUPT_SEQUENCE),
SQLITE_CORRUPT_INDEX(CApi.SQLITE_CORRUPT_INDEX),
SQLITE_READONLY_RECOVERY(CApi.SQLITE_READONLY_RECOVERY),
SQLITE_READONLY_CANTLOCK(CApi.SQLITE_READONLY_CANTLOCK),
SQLITE_READONLY_ROLLBACK(CApi.SQLITE_READONLY_ROLLBACK),
SQLITE_READONLY_DBMOVED(CApi.SQLITE_READONLY_DBMOVED),
SQLITE_READONLY_CANTINIT(CApi.SQLITE_READONLY_CANTINIT),
SQLITE_READONLY_DIRECTORY(CApi.SQLITE_READONLY_DIRECTORY),
SQLITE_ABORT_ROLLBACK(CApi.SQLITE_ABORT_ROLLBACK),
SQLITE_CONSTRAINT_CHECK(CApi.SQLITE_CONSTRAINT_CHECK),
SQLITE_CONSTRAINT_COMMITHOOK(CApi.SQLITE_CONSTRAINT_COMMITHOOK),
SQLITE_CONSTRAINT_FOREIGNKEY(CApi.SQLITE_CONSTRAINT_FOREIGNKEY),
SQLITE_CONSTRAINT_FUNCTION(CApi.SQLITE_CONSTRAINT_FUNCTION),
SQLITE_CONSTRAINT_NOTNULL(CApi.SQLITE_CONSTRAINT_NOTNULL),
SQLITE_CONSTRAINT_PRIMARYKEY(CApi.SQLITE_CONSTRAINT_PRIMARYKEY),
SQLITE_CONSTRAINT_TRIGGER(CApi.SQLITE_CONSTRAINT_TRIGGER),
SQLITE_CONSTRAINT_UNIQUE(CApi.SQLITE_CONSTRAINT_UNIQUE),
SQLITE_CONSTRAINT_VTAB(CApi.SQLITE_CONSTRAINT_VTAB),
SQLITE_CONSTRAINT_ROWID(CApi.SQLITE_CONSTRAINT_ROWID),
SQLITE_CONSTRAINT_PINNED(CApi.SQLITE_CONSTRAINT_PINNED),
SQLITE_CONSTRAINT_DATATYPE(CApi.SQLITE_CONSTRAINT_DATATYPE),
SQLITE_NOTICE_RECOVER_WAL(CApi.SQLITE_NOTICE_RECOVER_WAL),
SQLITE_NOTICE_RECOVER_ROLLBACK(CApi.SQLITE_NOTICE_RECOVER_ROLLBACK),
SQLITE_WARNING_AUTOINDEX(CApi.SQLITE_WARNING_AUTOINDEX),
SQLITE_AUTH_USER(CApi.SQLITE_AUTH_USER),
SQLITE_OK_LOAD_PERMANENTLY(CApi.SQLITE_OK_LOAD_PERMANENTLY);
public final int value;
ResultCode(int rc){
value = rc;
ResultCodeMap.set(rc, this);
}
/**
Returns the entry from this enum for the given result code, or
null if no match is found.
*/
public static ResultCode getEntryForInt(int rc){
return ResultCodeMap.get(rc);
}
/**
Internal level of indirection required because we cannot initialize
static enum members in an enum before the enum constructor is
invoked.
*/
private static final class ResultCodeMap {
private static final java.util.Map<Integer,ResultCode> i2e
= new java.util.HashMap<>();
private static void set(int rc, ResultCode e){ i2e.put(rc, e); }
private static ResultCode get(int rc){ return i2e.get(rc); }
}
}
ext/jni/src/org/sqlite/jni/capi/RollbackHookCallback.java
+26
View File
@@ -0,0 +1,26 @@
/*
** 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.capi;
/**
Callback for use with {@link CApi#sqlite3_rollback_hook}.
*/
public interface RollbackHookCallback extends CallbackProxy {
/**
Must function as documented for the C-level sqlite3_rollback_hook()
callback. If it throws, the exception is translated into
a db-level error.
*/
void call();
}
ext/jni/src/org/sqlite/jni/capi/SQLFunction.java
+36
View File
@@ -0,0 +1,36 @@
/*
** 2023-07-22
**
** 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.capi;
/**
SQLFunction is used in conjunction with the
sqlite3_create_function() JNI-bound API to give that native code
access to the callback functions needed in order to implement SQL
functions in Java.
<p>
This class is not used by itself, but is a marker base class. The
three UDF types are modelled by the inner classes Scalar,
Aggregate<T>, and Window<T>. Most simply, clients may subclass
those, or create anonymous classes from them, to implement
UDFs. Clients are free to create their own classes for use with
UDFs, so long as they conform to the public interfaces defined by
those three classes. The JNI layer only actively relies on the
SQLFunction base class and the method names and signatures used by
the UDF callback interfaces.
*/
public interface SQLFunction {
}
ext/jni/src/org/sqlite/jni/capi/SQLTester.java
+1449
View File
File diff suppressed because it is too large. Load diff
ext/jni/src/org/sqlite/jni/capi/ScalarFunction.java
+33
View File
@@ -0,0 +1,33 @@
/*
** 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.capi;
/**
A SQLFunction implementation for scalar functions.
*/
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
translated into an sqlite3_result_error().
*/
public abstract void xFunc(sqlite3_context cx, sqlite3_value[] args);
/**
Optionally override to be notified when the UDF is finalized by
SQLite. This default implementation does nothing.
*/
public void xDestroy() {}
}
ext/jni/src/org/sqlite/jni/capi/TableColumnMetadata.java
+35
View File
@@ -0,0 +1,35 @@
/*
** 2023-07-21
**
** 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.capi;
/**
A wrapper object for use with sqlite3_table_column_metadata().
They are populated only via that interface.
*/
public final class TableColumnMetadata {
final OutputPointer.Bool pNotNull = new OutputPointer.Bool();
final OutputPointer.Bool pPrimaryKey = new OutputPointer.Bool();
final OutputPointer.Bool pAutoinc = new OutputPointer.Bool();
final OutputPointer.String pzCollSeq = new OutputPointer.String();
final OutputPointer.String pzDataType = new OutputPointer.String();
public TableColumnMetadata(){
}
public String getDataType(){ return pzDataType.value; }
public String getCollation(){ return pzCollSeq.value; }
public boolean isNotNull(){ return pNotNull.value; }
public boolean isPrimaryKey(){ return pPrimaryKey.value; }
public boolean isAutoincrement(){ return pAutoinc.value; }
}
ext/jni/src/org/sqlite/jni/capi/Tester1.java
+2193
View File
File diff suppressed because it is too large. Load diff
ext/jni/src/org/sqlite/jni/capi/TraceV2Callback.java
+50
View File
@@ -0,0 +1,50 @@
/*
** 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.capi;
import org.sqlite.jni.annotation.Nullable;
/**
Callback for use with {@link CApi#sqlite3_trace_v2}.
*/
public interface TraceV2Callback extends CallbackProxy {
/**
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
sqlite3 or sqlite3_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 sqlite3_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.
*/
int call(int traceFlag, Object pNative, @Nullable Object pX);
}
ext/jni/src/org/sqlite/jni/capi/UpdateHookCallback.java
+26
View File
@@ -0,0 +1,26 @@
/*
** 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.capi;
/**
Callback for use with {@link CApi#sqlite3_update_hook}.
*/
public interface UpdateHookCallback extends CallbackProxy {
/**
Must function as described for the C-level sqlite3_update_hook()
callback. If it throws, the exception is translated into
a db-level error.
*/
void call(int opId, String dbName, String tableName, long rowId);
}
ext/jni/src/org/sqlite/jni/capi/ValueHolder.java
+27
View File
@@ -0,0 +1,27 @@
/*
** 2023-10-16
**
** 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 contains the ValueHolder utility class for the sqlite3
** JNI bindings.
*/
package org.sqlite.jni.capi;
/**
A helper class which simply holds a single value. Its primary use
is for communicating values out of anonymous classes, as doing so
requires a "final" reference, as well as communicating aggregate
SQL function state across calls to such functions.
*/
public class ValueHolder<T> {
public T value;
public ValueHolder(){}
public ValueHolder(T v){value = v;}
}
ext/jni/src/org/sqlite/jni/capi/WindowFunction.java
+39
View File
@@ -0,0 +1,39 @@
/*
** 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.capi;
/**
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> {
/**
As for the xInverse() argument of the C API's
sqlite3_create_window_function(). If this function throws, the
exception is not propagated and a warning might be emitted
to a debugging channel.
*/
public abstract void xInverse(sqlite3_context cx, sqlite3_value[] args);
/**
As for the xValue() argument of the C API's sqlite3_create_window_function().
See xInverse() for the fate of any exceptions this throws.
*/
public abstract void xValue(sqlite3_context cx);
}
ext/jni/src/org/sqlite/jni/capi/XDestroyCallback.java
+37
View File
@@ -0,0 +1,37 @@
/*
** 2023-07-21
**
** 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 declares JNI bindings for the sqlite3 C API.
*/
package org.sqlite.jni.capi;
/**
Callback for a hook called by SQLite when certain client-provided
state are destroyed. It gets its name from the pervasive use of
the symbol name xDestroy() for this purpose in the C API
documentation.
*/
public interface XDestroyCallback {
/**
Must perform any cleanup required by this object. Must not
throw. Must not call back into the sqlite3 API, else it might
invoke a deadlock.
WARNING: as a rule, it is never safe to register individual
instances with this interface multiple times in the
library. e.g., do not register the same CollationCallback with
multiple arities or names using sqlite3_create_collation(). If
this rule is violated, the library will eventually try to free
each individual reference, leading to memory corruption or a
crash via duplicate free().
*/
void xDestroy();
}
ext/jni/src/org/sqlite/jni/capi/package-info.java
+89
View File
@@ -0,0 +1,89 @@
/**
This package houses a JNI binding to the SQLite3 C API.
<p>The primary interfaces are in {@link
org.sqlite.jni.capi.CApi}.</p>
<h1>API Goals and Requirements</h1>
<ul>
<li>A 1-to-1(-ish) mapping of the C API to Java via JNI, insofar
as cross-language semantics allow for. A closely-related goal is
that <a href='https://sqlite.org/c3ref/intro.html'>the C
documentation</a> should be usable as-is, insofar as possible,
for most of the JNI binding. As a rule, undocumented symbols in
the Java interface behave as documented for their C API
counterpart. Only semantic differences and Java-specific features
are documented here.</li>
<li>Support Java as far back as version 8 (2014).</li>
<li>Environment-independent. Should work everywhere both Java and
SQLite3 do.</li>
<li>No 3rd-party dependencies beyond the JDK. That includes no
build-level dependencies for specific IDEs and toolchains. We
welcome the addition of build files for arbitrary environments
insofar as they neither interfere with each other nor become a
maintenance burden for the sqlite developers.</li>
</ul>
<h2>Non-Goals</h2>
<ul>
<li>Creation of high-level OO wrapper APIs. Clients are free to
create them off of the C-style API.</li>
<li>Support for mixed-mode operation, where client code accesses
SQLite both via the Java-side API and the C API via their own
native code. In such cases, proxy functionalities (primarily
callback handler wrappers of all sorts) may fail because the
C-side use of the SQLite APIs will bypass those proxies.</li>
</ul>
<h1>State of this API</h1>
<p>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.</p>
<h1>Threading Considerations</h1>
<p>This API is, if built with SQLITE_THREADSAFE set to 1 or 2,
thread-safe, insofar as the C API guarantees, with some addenda:</p>
<ul>
<li>It is not legal to use Java-facing SQLite3 resource handles
(sqlite3, sqlite3_stmt, etc) from multiple threads concurrently,
nor to use any database-specific resources concurrently in a
thread separate from the one the database is currently in use
in. i.e. do not use a sqlite3_stmt in thread #2 when thread #1 is
using the database which prepared that handle.
<br>Violating this will eventually corrupt the JNI-level bindings
between Java's and C's view of the database. This is a limitation
of the JNI bindings, not the lower-level library.
</li>
<li>It is legal to use a given handle, and database-specific
resources, across threads, so long as no two threads pass
resources owned by the same database into the library
concurrently.
</li>
</ul>
<p>Any number of threads may, of course, create and use any number
of database handles they wish. Care only needs to be taken when
those handles or their associated resources cross threads, or...</p>
<p>When built with SQLITE_THREADSAFE=0 then no threading guarantees
are provided and multi-threaded use of the library will provoke
undefined behavior.</p>
*/
package org.sqlite.jni.capi;
ext/jni/src/org/sqlite/jni/capi/sqlite3.java
+43
View File
@@ -0,0 +1,43 @@
/*
** 2023-07-21
**
** 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.capi;
/**
A wrapper for communicating C-level (sqlite3*) instances with
Java. These wrappers do not own their associated pointer, they
simply provide a type-safe way to communicate it between Java
and C via JNI.
*/
public final class sqlite3 extends NativePointerHolder<sqlite3>
implements AutoCloseable {
// Only invoked from JNI
private sqlite3(){}
public String toString(){
final long ptr = getNativePointer();
if( 0==ptr ){
return sqlite3.class.getSimpleName()+"@null";
}
final String fn = CApi.sqlite3_db_filename(this, "main");
return sqlite3.class.getSimpleName()
+"@"+String.format("0x%08x",ptr)
+"["+((null == fn) ? "<unnamed>" : fn)+"]"
;
}
@Override public void close(){
CApi.sqlite3_close_v2(this);
}
}
ext/jni/src/org/sqlite/jni/capi/sqlite3_backup.java
+31
View File
@@ -0,0 +1,31 @@
/*
** 2023-09-03
**
** 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.capi;
/**
A wrapper for passing C-level (sqlite3_backup*) instances around in
Java. These wrappers do not own their associated pointer, they
simply provide a type-safe way to communicate it between Java and C
via JNI.
*/
public final class sqlite3_backup extends NativePointerHolder<sqlite3_backup>
implements AutoCloseable {
// Only invoked from JNI.
private sqlite3_backup(){}
@Override public void close(){
CApi.sqlite3_backup_finish(this);
}
}
ext/jni/src/org/sqlite/jni/capi/sqlite3_blob.java
+30
View File
@@ -0,0 +1,30 @@
/*
** 2023-09-03
**
** 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.capi;
/**
A wrapper for passing C-level (sqlite3_blob*) instances around in
Java. These wrappers do not own their associated pointer, they
simply provide a type-safe way to communicate it between Java and C
via JNI.
*/
public final class sqlite3_blob extends NativePointerHolder<sqlite3_blob>
implements AutoCloseable {
// Only invoked from JNI.
private sqlite3_blob(){}
@Override public void close(){
CApi.sqlite3_blob_close(this);
}
}
ext/jni/src/org/sqlite/jni/capi/sqlite3_context.java
+79
View File
@@ -0,0 +1,79 @@
/*
** 2023-07-21
**
** 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.capi;
/**
sqlite3_context instances are used in conjunction with user-defined
SQL functions (a.k.a. UDFs).
*/
public final class sqlite3_context extends NativePointerHolder<sqlite3_context> {
private Long aggregateContext = null;
/**
getAggregateContext() corresponds to C's
sqlite3_aggregate_context(), with a slightly different interface
to account for cross-language differences. It serves the same
purposes in a slightly different way: it provides a key which is
stable across invocations of a UDF's callbacks, such that all
calls into those callbacks can determine which "set" of those
calls they belong to.
<p>Note that use of this method is not a requirement for proper use
of this class. sqlite3_aggregate_context() can also be used.
<p>If the argument is true and the aggregate context has not yet
been set up, it will be initialized and fetched on demand, else it
won't. The intent is that xStep(), xValue(), and xInverse()
methods pass true and xFinal() methods pass false.
<p>This function treats numeric 0 as null, always returning null instead
of 0.
<p>If this object is being used in the context of an aggregate or
window UDF, this function returns a non-0 value which is distinct
for each set of UDF callbacks from a single invocation of the
UDF, otherwise it returns 0. The returned value is only only
valid within the context of execution of a single SQL statement,
and must not be re-used by future invocations of the UDF in
different SQL statements.
<p>Consider this SQL, where MYFUNC is a user-defined aggregate function:
<pre>{@code
SELECT MYFUNC(A), MYFUNC(B) FROM T;
}</pre>
<p>The xStep() and xFinal() methods of the callback need to be able
to differentiate between those two invocations in order to
perform their work properly. The value returned by
getAggregateContext() will be distinct for each of those
invocations of MYFUNC() and is intended to be used as a lookup
key for mapping callback invocations to whatever client-defined
state is needed by the UDF.
<p>There is one case where this will return null in the context
of an aggregate or window function: if the result set has no
rows, the UDF's xFinal() will be called without any other x...()
members having been called. In that one case, no aggregate
context key will have been generated. xFinal() implementations
need to be prepared to accept that condition as legal.
*/
public synchronized Long getAggregateContext(boolean initIfNeeded){
if( aggregateContext==null ){
aggregateContext = CApi.sqlite3_aggregate_context(this, initIfNeeded);
if( !initIfNeeded && null==aggregateContext ) aggregateContext = 0L;
}
return (null==aggregateContext || 0!=aggregateContext) ? aggregateContext : null;
}
}
ext/jni/src/org/sqlite/jni/capi/sqlite3_stmt.java
+30
View File
@@ -0,0 +1,30 @@
/*
** 2023-07-21
**
** 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.capi;
/**
A wrapper for communicating C-level (sqlite3_stmt*) instances with
Java. These wrappers do not own their associated pointer, they
simply provide a type-safe way to communicate it between Java and C
via JNI.
*/
public final class sqlite3_stmt extends NativePointerHolder<sqlite3_stmt>
implements AutoCloseable {
// Only invoked from JNI.
private sqlite3_stmt(){}
@Override public void close(){
CApi.sqlite3_finalize(this);
}
}
ext/jni/src/org/sqlite/jni/capi/sqlite3_value.java
+19
View File
@@ -0,0 +1,19 @@
/*
** 2023-07-21
**
** 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.capi;
public final class sqlite3_value extends NativePointerHolder<sqlite3_value> {
//! Invoked only from JNI.
private sqlite3_value(){}
}
ext/jni/src/org/sqlite/jni/fts5/Fts5.java
+32
View File
@@ -0,0 +1,32 @@
/*
** 2023-08-05
**
** 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.fts5;
/**
INCOMPLETE AND COMPLETELY UNTESTED.
A utility object for holding FTS5-specific types and constants
which are used by multiple FTS5 classes.
*/
public final class Fts5 {
/* Not used */
private Fts5(){}
public static final int FTS5_TOKENIZE_QUERY = 0x0001;
public static final int FTS5_TOKENIZE_PREFIX = 0x0002;
public static final int FTS5_TOKENIZE_DOCUMENT = 0x0004;
public static final int FTS5_TOKENIZE_AUX = 0x0008;
public static final int FTS5_TOKEN_COLOCATED = 0x0001;
}
ext/jni/src/org/sqlite/jni/fts5/Fts5Context.java
+24
View File
@@ -0,0 +1,24 @@
/*
** 2023-08-04
**
** 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.fts5;
import org.sqlite.jni.capi.*;
/**
A wrapper for communicating C-level (Fts5Context*) instances with
Java. These wrappers do not own their associated pointer, they
simply provide a type-safe way to communicate it between Java and C
via JNI.
*/
public final class Fts5Context extends NativePointerHolder<Fts5Context> {
}
ext/jni/src/org/sqlite/jni/fts5/Fts5ExtensionApi.java
+96
View File
@@ -0,0 +1,96 @@
/*
** 2023-08-04
**
** 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.fts5;
import org.sqlite.jni.capi.*;
import org.sqlite.jni.annotation.*;
/**
*/
public final class Fts5ExtensionApi extends NativePointerHolder<Fts5ExtensionApi> {
//! Only called from JNI
private Fts5ExtensionApi(){}
private final int iVersion = 2;
/* Callback type for used by xQueryPhrase(). */
public interface XQueryPhraseCallback {
int call(Fts5ExtensionApi fapi, Fts5Context cx);
}
/**
Returns the singleton instance of this class.
*/
public static native Fts5ExtensionApi getInstance();
public native int xColumnCount(@NotNull Fts5Context fcx);
public native int xColumnSize(@NotNull Fts5Context cx, int iCol,
@NotNull OutputPointer.Int32 pnToken);
public native int xColumnText(@NotNull Fts5Context cx, int iCol,
@NotNull OutputPointer.String txt);
public native int xColumnTotalSize(@NotNull Fts5Context fcx, int iCol,
@NotNull OutputPointer.Int64 pnToken);
public native Object xGetAuxdata(@NotNull Fts5Context cx, boolean clearIt);
public native int xInst(@NotNull Fts5Context cx, int iIdx,
@NotNull OutputPointer.Int32 piPhrase,
@NotNull OutputPointer.Int32 piCol,
@NotNull OutputPointer.Int32 piOff);
public native int xInstCount(@NotNull Fts5Context fcx,
@NotNull OutputPointer.Int32 pnInst);
public native int xPhraseCount(@NotNull Fts5Context fcx);
public native int xPhraseFirst(@NotNull Fts5Context cx, int iPhrase,
@NotNull Fts5PhraseIter iter,
@NotNull OutputPointer.Int32 iCol,
@NotNull OutputPointer.Int32 iOff);
public native int xPhraseFirstColumn(@NotNull Fts5Context cx, int iPhrase,
@NotNull Fts5PhraseIter iter,
@NotNull OutputPointer.Int32 iCol);
public native void xPhraseNext(@NotNull Fts5Context cx,
@NotNull Fts5PhraseIter iter,
@NotNull OutputPointer.Int32 iCol,
@NotNull OutputPointer.Int32 iOff);
public native void xPhraseNextColumn(@NotNull Fts5Context cx,
@NotNull Fts5PhraseIter iter,
@NotNull OutputPointer.Int32 iCol);
public native int xPhraseSize(@NotNull Fts5Context fcx, int iPhrase);
public native int xQueryPhrase(@NotNull Fts5Context cx, int iPhrase,
@NotNull XQueryPhraseCallback callback);
public native int xRowCount(@NotNull Fts5Context fcx,
@NotNull OutputPointer.Int64 nRow);
public native long xRowid(@NotNull Fts5Context cx);
/* Note that the JNI binding lacks the C version's xDelete()
callback argument. Instead, if pAux has an xDestroy() method, it
is called if the FTS5 API finalizes the aux state (including if
allocation of storage for the auxdata fails). Any reference to
pAux held by the JNI layer will be relinquished regardless of
whether pAux has an xDestroy() method. */
public native int xSetAuxdata(@NotNull Fts5Context cx, @Nullable Object pAux);
public native int xTokenize(@NotNull Fts5Context cx, @NotNull byte[] pText,
@NotNull XTokenizeCallback callback);
public native Object xUserData(Fts5Context cx);
//^^^ returns the pointer passed as the 3rd arg to the C-level
// fts5_api::xCreateFunction().
}
ext/jni/src/org/sqlite/jni/fts5/Fts5PhraseIter.java
+25
View File
@@ -0,0 +1,25 @@
/*
** 2023-08-04
**
** 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.fts5;
import org.sqlite.jni.capi.NativePointerHolder;
/**
A wrapper for C-level Fts5PhraseIter. They are only modified and
inspected by native-level code.
*/
public final class Fts5PhraseIter extends NativePointerHolder<Fts5PhraseIter> {
//! Updated and used only by native code.
private long a;
private long b;
}
ext/jni/src/org/sqlite/jni/fts5/Fts5Tokenizer.java
+31
View File
@@ -0,0 +1,31 @@
/*
** 2023-08-05x
**
** 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.fts5;
import org.sqlite.jni.capi.NativePointerHolder;
/**
INCOMPLETE AND COMPLETELY UNTESTED.
A wrapper for communicating C-level (Fts5Tokenizer*) instances with
Java. These wrappers do not own their associated pointer, they
simply provide a type-safe way to communicate it between Java and C
via JNI.
At the C level, the Fts5Tokenizer type is essentially a void
pointer used specifically for tokenizers.
*/
public final class Fts5Tokenizer extends NativePointerHolder<Fts5Tokenizer> {
//! Only called from JNI.
private Fts5Tokenizer(){}
}
ext/jni/src/org/sqlite/jni/fts5/TesterFts5.java
+841
View File
@@ -0,0 +1,841 @@
/*
** 2023-08-04
**
** 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 contains a set of tests for the sqlite3 JNI bindings.
*/
package org.sqlite.jni.fts5;
import java.util.*;
import static org.sqlite.jni.capi.CApi.*;
import static org.sqlite.jni.capi.Tester1.*;
import org.sqlite.jni.capi.*;
import java.nio.charset.StandardCharsets;
public class TesterFts5 {
private static void test1(){
final Fts5ExtensionApi fea = Fts5ExtensionApi.getInstance();
affirm( null != fea );
affirm( fea.getNativePointer() != 0 );
affirm( fea == Fts5ExtensionApi.getInstance() )/*singleton*/;
sqlite3 db = createNewDb();
fts5_api fApi = fts5_api.getInstanceForDb(db);
affirm( fApi != null );
affirm( fApi == fts5_api.getInstanceForDb(db) /* singleton per db */ );
execSql(db, new String[] {
"CREATE VIRTUAL TABLE ft USING fts5(a, b);",
"INSERT INTO ft(rowid, a, b) VALUES(1, 'X Y', 'Y Z');",
"INSERT INTO ft(rowid, a, b) VALUES(2, 'A Z', 'Y Y');"
});
final String pUserData = "This is pUserData";
final int outputs[] = {0, 0};
final fts5_extension_function func = new fts5_extension_function(){
@Override public void call(Fts5ExtensionApi ext, Fts5Context fCx,
sqlite3_context pCx, sqlite3_value argv[]){
final int nCols = ext.xColumnCount(fCx);
affirm( 2 == nCols );
affirm( nCols == argv.length );
affirm( ext.xUserData(fCx) == pUserData );
final OutputPointer.String op = new OutputPointer.String();
final OutputPointer.Int32 colsz = new OutputPointer.Int32();
final OutputPointer.Int64 colTotalSz = new OutputPointer.Int64();
for(int i = 0; i < nCols; ++i ){
int rc = ext.xColumnText(fCx, i, op);
affirm( 0 == rc );
final String val = op.value;
affirm( val.equals(sqlite3_value_text16(argv[i])) );
rc = ext.xColumnSize(fCx, i, colsz);
affirm( 0==rc );
affirm( 3==sqlite3_value_bytes(argv[i]) );
rc = ext.xColumnTotalSize(fCx, i, colTotalSz);
affirm( 0==rc );
}
++outputs[0];
}
public void xDestroy(){
outputs[1] = 1;
}
};
int rc = fApi.xCreateFunction("myaux", pUserData, func);
affirm( 0==rc );
affirm( 0==outputs[0] );
execSql(db, "select myaux(ft,a,b) from ft;");
affirm( 2==outputs[0] );
affirm( 0==outputs[1] );
sqlite3_close_v2(db);
affirm( 1==outputs[1] );
}
/*
** Argument sql is a string containing one or more SQL statements
** separated by ";" characters. This function executes each of these
** statements against the database passed as the first argument. If
** no error occurs, the results of the SQL script are returned as
** an array of strings. If an error does occur, a RuntimeException is
** thrown.
*/
private static String[] sqlite3_exec(sqlite3 db, String sql) {
List<String> aOut = new ArrayList<>();
/* Iterate through the list of SQL statements. For each, step through
** it and add any results to the aOut[] array. */
int rc = sqlite3_prepare_multi(db, sql, new PrepareMultiCallback() {
@Override public int call(sqlite3_stmt pStmt){
while( SQLITE_ROW==sqlite3_step(pStmt) ){
int ii;
for(ii=0; ii<sqlite3_column_count(pStmt); ii++){
aOut.add( sqlite3_column_text16(pStmt, ii) );
}
}
return sqlite3_finalize(pStmt);
}
});
if( rc!=SQLITE_OK ){
throw new RuntimeException(sqlite3_errmsg(db));
}
/* Convert to array and return */
String[] arr = new String[aOut.size()];
return aOut.toArray(arr);
}
/*
** Execute the SQL script passed as the second parameter via
** sqlite3_exec(). Then affirm() that the results, when converted to
** a string, match the value of the 3rd parameter. Example:
**
** do_execsql_test(db, "SELECT 'abc'", "[abc]");
**
*/
private static void do_execsql_test(sqlite3 db, String sql, String expect) {
String res = Arrays.toString( sqlite3_exec(db, sql) );
affirm( res.equals(expect),
"got {" + res + "} expected {" + expect + "}"
);
}
private static void do_execsql_test(sqlite3 db, String sql){
do_execsql_test(db, sql, "[]");
}
/*
** Create the following custom SQL functions:
**
** fts5_rowid()
** fts5_columncount()
*/
private static void create_test_functions(sqlite3 db){
/*
** A user-defined-function fts5_rowid() that uses xRowid()
*/
fts5_extension_function fts5_rowid = new fts5_extension_function(){
@Override public void call(
Fts5ExtensionApi ext,
Fts5Context fCx,
sqlite3_context pCx,
sqlite3_value argv[]
){
long rowid = ext.xRowid(fCx);
sqlite3_result_int64(pCx, rowid);
}
public void xDestroy(){ }
};
/*
** fts5_columncount() - xColumnCount()
*/
fts5_extension_function fts5_columncount = new fts5_extension_function(){
@Override public void call(
Fts5ExtensionApi ext,
Fts5Context fCx,
sqlite3_context pCx,
sqlite3_value argv[]
){
int nCol = ext.xColumnCount(fCx);
sqlite3_result_int(pCx, nCol);
}
public void xDestroy(){ }
};
/*
** fts5_columnsize() - xColumnSize()
*/
fts5_extension_function fts5_columnsize = new fts5_extension_function(){
@Override public void call(
Fts5ExtensionApi ext,
Fts5Context fCx,
sqlite3_context pCx,
sqlite3_value argv[]
){
if( argv.length!=1 ){
throw new RuntimeException("fts5_columncount: wrong number of args");
}
int iCol = sqlite3_value_int(argv[0]);
OutputPointer.Int32 piSz = new OutputPointer.Int32();
int rc = ext.xColumnSize(fCx, iCol, piSz);
if( rc!=SQLITE_OK ){
throw new RuntimeException( sqlite3_errstr(rc) );
}
sqlite3_result_int(pCx, piSz.get());
}
public void xDestroy(){ }
};
/*
** fts5_columntext() - xColumnText()
*/
fts5_extension_function fts5_columntext = new fts5_extension_function(){
@Override public void call(
Fts5ExtensionApi ext,
Fts5Context fCx,
sqlite3_context pCx,
sqlite3_value argv[]
){
if( argv.length!=1 ){
throw new RuntimeException("fts5_columntext: wrong number of args");
}
int iCol = sqlite3_value_int(argv[0]);
OutputPointer.String pzText = new OutputPointer.String();
int rc = ext.xColumnText(fCx, iCol, pzText);
if( rc!=SQLITE_OK ){
throw new RuntimeException( sqlite3_errstr(rc) );
}
sqlite3_result_text16(pCx, pzText.get());
}
public void xDestroy(){ }
};
/*
** fts5_columntotalsize() - xColumnTotalSize()
*/
fts5_extension_function fts5_columntsize = new fts5_extension_function(){
@Override public void call(
Fts5ExtensionApi ext,
Fts5Context fCx,
sqlite3_context pCx,
sqlite3_value argv[]
){
if( argv.length!=1 ){
throw new RuntimeException(
"fts5_columntotalsize: wrong number of args"
);
}
int iCol = sqlite3_value_int(argv[0]);
OutputPointer.Int64 piSz = new OutputPointer.Int64();
int rc = ext.xColumnTotalSize(fCx, iCol, piSz);
if( rc!=SQLITE_OK ){
throw new RuntimeException( sqlite3_errstr(rc) );
}
sqlite3_result_int64(pCx, piSz.get());
}
public void xDestroy(){ }
};
/*
** fts5_aux(<fts>, <value>);
*/
class fts5_aux implements fts5_extension_function {
@Override public void call(
Fts5ExtensionApi ext,
Fts5Context fCx,
sqlite3_context pCx,
sqlite3_value argv[]
){
if( argv.length>1 ){
throw new RuntimeException("fts5_aux: wrong number of args");
}
boolean bClear = (argv.length==1);
Object obj = ext.xGetAuxdata(fCx, bClear);
if( obj instanceof String ){
sqlite3_result_text16(pCx, (String)obj);
}
if( argv.length==1 ){
String val = sqlite3_value_text16(argv[0]);
if( !val.isEmpty() ){
ext.xSetAuxdata(fCx, val);
}
}
}
public void xDestroy(){ }
}
/*
** fts5_inst(<fts>);
**
** This is used to test the xInstCount() and xInst() APIs. It returns a
** text value containing a Tcl list with xInstCount() elements. Each
** element is itself a list of 3 integers - the phrase number, column
** number and token offset returned by each call to xInst().
*/
fts5_extension_function fts5_inst = new fts5_extension_function(){
@Override public void call(
Fts5ExtensionApi ext,
Fts5Context fCx,
sqlite3_context pCx,
sqlite3_value argv[]
){
if( argv.length!=0 ){
throw new RuntimeException("fts5_inst: wrong number of args");
}
OutputPointer.Int32 pnInst = new OutputPointer.Int32();
OutputPointer.Int32 piPhrase = new OutputPointer.Int32();
OutputPointer.Int32 piCol = new OutputPointer.Int32();
OutputPointer.Int32 piOff = new OutputPointer.Int32();
String ret = "";
int rc = ext.xInstCount(fCx, pnInst);
int nInst = pnInst.get();
int ii;
for(ii=0; rc==SQLITE_OK && ii<nInst; ii++){
ext.xInst(fCx, ii, piPhrase, piCol, piOff);
if( ii>0 ) ret += " ";
ret += "{"+piPhrase.get()+" "+piCol.get()+" "+piOff.get()+"}";
}
sqlite3_result_text(pCx, ret);
}
public void xDestroy(){ }
};
/*
** fts5_pinst(<fts>);
**
** Like SQL function fts5_inst(), except using the following
**
** xPhraseCount
** xPhraseFirst
** xPhraseNext
*/
fts5_extension_function fts5_pinst = new fts5_extension_function(){
@Override public void call(
Fts5ExtensionApi ext,
Fts5Context fCx,
sqlite3_context pCx,
sqlite3_value argv[]
){
if( argv.length!=0 ){
throw new RuntimeException("fts5_pinst: wrong number of args");
}
OutputPointer.Int32 piCol = new OutputPointer.Int32();
OutputPointer.Int32 piOff = new OutputPointer.Int32();
String ret = "";
int rc = SQLITE_OK;
int nPhrase = ext.xPhraseCount(fCx);
int ii;
for(ii=0; rc==SQLITE_OK && ii<nPhrase; ii++){
Fts5PhraseIter pIter = new Fts5PhraseIter();
for(rc = ext.xPhraseFirst(fCx, ii, pIter, piCol, piOff);
rc==SQLITE_OK && piCol.get()>=0;
ext.xPhraseNext(fCx, pIter, piCol, piOff)
){
if( !ret.isEmpty() ) ret += " ";
ret += "{"+ii+" "+piCol.get()+" "+piOff.get()+"}";
}
}
if( rc!=SQLITE_OK ){
throw new RuntimeException("fts5_pinst: rc=" + rc);
}else{
sqlite3_result_text(pCx, ret);
}
}
public void xDestroy(){ }
};
/*
** fts5_pcolinst(<fts>);
**
** Like SQL function fts5_pinst(), except using the following
**
** xPhraseFirstColumn
** xPhraseNextColumn
*/
fts5_extension_function fts5_pcolinst = new fts5_extension_function(){
@Override public void call(
Fts5ExtensionApi ext,
Fts5Context fCx,
sqlite3_context pCx,
sqlite3_value argv[]
){
if( argv.length!=0 ){
throw new RuntimeException("fts5_pcolinst: wrong number of args");
}
OutputPointer.Int32 piCol = new OutputPointer.Int32();
String ret = "";
int rc = SQLITE_OK;
int nPhrase = ext.xPhraseCount(fCx);
int ii;
for(ii=0; rc==SQLITE_OK && ii<nPhrase; ii++){
Fts5PhraseIter pIter = new Fts5PhraseIter();
for(rc = ext.xPhraseFirstColumn(fCx, ii, pIter, piCol);
rc==SQLITE_OK && piCol.get()>=0;
ext.xPhraseNextColumn(fCx, pIter, piCol)
){
if( !ret.isEmpty() ) ret += " ";
ret += "{"+ii+" "+piCol.get()+"}";
}
}
if( rc!=SQLITE_OK ){
throw new RuntimeException("fts5_pcolinst: rc=" + rc);
}else{
sqlite3_result_text(pCx, ret);
}
}
public void xDestroy(){ }
};
/*
** fts5_rowcount(<fts>);
*/
fts5_extension_function fts5_rowcount = new fts5_extension_function(){
@Override public void call(
Fts5ExtensionApi ext,
Fts5Context fCx,
sqlite3_context pCx,
sqlite3_value argv[]
){
if( argv.length!=0 ){
throw new RuntimeException("fts5_rowcount: wrong number of args");
}
OutputPointer.Int64 pnRow = new OutputPointer.Int64();
int rc = ext.xRowCount(fCx, pnRow);
if( rc==SQLITE_OK ){
sqlite3_result_int64(pCx, pnRow.get());
}else{
throw new RuntimeException("fts5_rowcount: rc=" + rc);
}
}
public void xDestroy(){ }
};
/*
** fts5_phrasesize(<fts>);
*/
fts5_extension_function fts5_phrasesize = new fts5_extension_function(){
@Override public void call(
Fts5ExtensionApi ext,
Fts5Context fCx,
sqlite3_context pCx,
sqlite3_value argv[]
){
if( argv.length!=1 ){
throw new RuntimeException("fts5_phrasesize: wrong number of args");
}
int iPhrase = sqlite3_value_int(argv[0]);
int sz = ext.xPhraseSize(fCx, iPhrase);
sqlite3_result_int(pCx, sz);
}
public void xDestroy(){ }
};
/*
** fts5_phrasehits(<fts>, <phrase-number>);
**
** Use the xQueryPhrase() API to determine how many hits, in total,
** there are for phrase <phrase-number> in the database.
*/
fts5_extension_function fts5_phrasehits = new fts5_extension_function(){
@Override public void call(
Fts5ExtensionApi ext,
Fts5Context fCx,
sqlite3_context pCx,
sqlite3_value argv[]
){
if( argv.length!=1 ){
throw new RuntimeException("fts5_phrasesize: wrong number of args");
}
int iPhrase = sqlite3_value_int(argv[0]);
int rc = SQLITE_OK;
class MyCallback implements Fts5ExtensionApi.XQueryPhraseCallback {
public int nRet = 0;
public int getRet() { return nRet; }
@Override
public int call(Fts5ExtensionApi fapi, Fts5Context cx){
OutputPointer.Int32 pnInst = new OutputPointer.Int32();
int rc = fapi.xInstCount(cx, pnInst);
nRet += pnInst.get();
return rc;
}
};
MyCallback xCall = new MyCallback();
rc = ext.xQueryPhrase(fCx, iPhrase, xCall);
if( rc!=SQLITE_OK ){
throw new RuntimeException("fts5_phrasehits: rc=" + rc);
}
sqlite3_result_int(pCx, xCall.getRet());
}
public void xDestroy(){ }
};
/*
** fts5_tokenize(<fts>, <text>)
*/
fts5_extension_function fts5_tokenize = new fts5_extension_function(){
@Override public void call(
Fts5ExtensionApi ext,
Fts5Context fCx,
sqlite3_context pCx,
sqlite3_value argv[]
){
if( argv.length!=1 ){
throw new RuntimeException("fts5_tokenize: wrong number of args");
}
byte[] utf8 = sqlite3_value_text(argv[0]);
int rc = SQLITE_OK;
class MyCallback implements XTokenizeCallback {
private List<String> myList = new ArrayList<>();
public String getval() {
return String.join("+", myList);
}
@Override
public int call(int tFlags, byte[] txt, int iStart, int iEnd){
try {
String str = new String(txt, StandardCharsets.UTF_8);
myList.add(str);
} catch (Exception e) {
}
return SQLITE_OK;
}
};
MyCallback xCall = new MyCallback();
ext.xTokenize(fCx, utf8, xCall);
sqlite3_result_text16(pCx, xCall.getval());
if( rc!=SQLITE_OK ){
throw new RuntimeException("fts5_tokenize: rc=" + rc);
}
}
public void xDestroy(){ }
};
fts5_api api = fts5_api.getInstanceForDb(db);
api.xCreateFunction("fts5_rowid", fts5_rowid);
api.xCreateFunction("fts5_columncount", fts5_columncount);
api.xCreateFunction("fts5_columnsize", fts5_columnsize);
api.xCreateFunction("fts5_columntext", fts5_columntext);
api.xCreateFunction("fts5_columntotalsize", fts5_columntsize);
api.xCreateFunction("fts5_aux1", new fts5_aux());
api.xCreateFunction("fts5_aux2", new fts5_aux());
api.xCreateFunction("fts5_inst", fts5_inst);
api.xCreateFunction("fts5_pinst", fts5_pinst);
api.xCreateFunction("fts5_pcolinst", fts5_pcolinst);
api.xCreateFunction("fts5_rowcount", fts5_rowcount);
api.xCreateFunction("fts5_phrasesize", fts5_phrasesize);
api.xCreateFunction("fts5_phrasehits", fts5_phrasehits);
api.xCreateFunction("fts5_tokenize", fts5_tokenize);
}
/*
** Test of various Fts5ExtensionApi methods
*/
private static void test2(){
/* Open db and populate an fts5 table */
sqlite3 db = createNewDb();
do_execsql_test(db,
"CREATE VIRTUAL TABLE ft USING fts5(a, b);" +
"INSERT INTO ft(rowid, a, b) VALUES(-9223372036854775808, 'x', 'x');" +
"INSERT INTO ft(rowid, a, b) VALUES(0, 'x', 'x');" +
"INSERT INTO ft(rowid, a, b) VALUES(1, 'x y z', 'x y z');" +
"INSERT INTO ft(rowid, a, b) VALUES(2, 'x y z', 'x z');" +
"INSERT INTO ft(rowid, a, b) VALUES(3, 'x y z', 'x y z');" +
"INSERT INTO ft(rowid, a, b) VALUES(9223372036854775807, 'x', 'x');"
);
create_test_functions(db);
/* Test that fts5_rowid() seems to work */
do_execsql_test(db,
"SELECT rowid==fts5_rowid(ft) FROM ft('x')",
"[1, 1, 1, 1, 1, 1]"
);
/* Test fts5_columncount() */
do_execsql_test(db,
"SELECT fts5_columncount(ft) FROM ft('x')",
"[2, 2, 2, 2, 2, 2]"
);
/* Test fts5_columnsize() */
do_execsql_test(db,
"SELECT fts5_columnsize(ft, 0) FROM ft('x') ORDER BY rowid",
"[1, 1, 3, 3, 3, 1]"
);
do_execsql_test(db,
"SELECT fts5_columnsize(ft, 1) FROM ft('x') ORDER BY rowid",
"[1, 1, 3, 2, 3, 1]"
);
do_execsql_test(db,
"SELECT fts5_columnsize(ft, -1) FROM ft('x') ORDER BY rowid",
"[2, 2, 6, 5, 6, 2]"
);
/* Test that xColumnSize() returns SQLITE_RANGE if the column number
** is out-of range */
try {
do_execsql_test(db,
"SELECT fts5_columnsize(ft, 2) FROM ft('x') ORDER BY rowid"
);
} catch( RuntimeException e ){
affirm( e.getMessage().matches(".*column index out of range") );
}
/* Test fts5_columntext() */
do_execsql_test(db,
"SELECT fts5_columntext(ft, 0) FROM ft('x') ORDER BY rowid",
"[x, x, x y z, x y z, x y z, x]"
);
do_execsql_test(db,
"SELECT fts5_columntext(ft, 1) FROM ft('x') ORDER BY rowid",
"[x, x, x y z, x z, x y z, x]"
);
boolean threw = false;
try{
/* columntext() used to return NULLs when given an out-of bounds column
but now results in a range error. */
do_execsql_test(db,
"SELECT fts5_columntext(ft, 2) FROM ft('x') ORDER BY rowid",
"[null, null, null, null, null, null]"
);
}catch(Exception e){
threw = true;
affirm( e.getMessage().matches(".*column index out of range") );
}
affirm( threw );
threw = false;
/* Test fts5_columntotalsize() */
do_execsql_test(db,
"SELECT fts5_columntotalsize(ft, 0) FROM ft('x') ORDER BY rowid",
"[12, 12, 12, 12, 12, 12]"
);
do_execsql_test(db,
"SELECT fts5_columntotalsize(ft, 1) FROM ft('x') ORDER BY rowid",
"[11, 11, 11, 11, 11, 11]"
);
do_execsql_test(db,
"SELECT fts5_columntotalsize(ft, -1) FROM ft('x') ORDER BY rowid",
"[23, 23, 23, 23, 23, 23]"
);
/* Test that xColumnTotalSize() returns SQLITE_RANGE if the column
** number is out-of range */
try {
do_execsql_test(db,
"SELECT fts5_columntotalsize(ft, 2) FROM ft('x') ORDER BY rowid"
);
} catch( RuntimeException e ){
affirm( e.getMessage().matches(".*column index out of range") );
}
do_execsql_test(db,
"SELECT rowid, fts5_rowcount(ft) FROM ft('z')",
"[1, 6, 2, 6, 3, 6]"
);
sqlite3_close_v2(db);
}
/*
** Test of various Fts5ExtensionApi methods
*/
private static void test3(){
/* Open db and populate an fts5 table */
sqlite3 db = createNewDb();
do_execsql_test(db,
"CREATE VIRTUAL TABLE ft USING fts5(a, b);" +
"INSERT INTO ft(a, b) VALUES('the one', 1);" +
"INSERT INTO ft(a, b) VALUES('the two', 2);" +
"INSERT INTO ft(a, b) VALUES('the three', 3);" +
"INSERT INTO ft(a, b) VALUES('the four', '');"
);
create_test_functions(db);
/* Test fts5_aux1() + fts5_aux2() - users of xGetAuxdata and xSetAuxdata */
do_execsql_test(db,
"SELECT fts5_aux1(ft, a) FROM ft('the')",
"[null, the one, the two, the three]"
);
do_execsql_test(db,
"SELECT fts5_aux2(ft, b) FROM ft('the')",
"[null, 1, 2, 3]"
);
do_execsql_test(db,
"SELECT fts5_aux1(ft, a), fts5_aux2(ft, b) FROM ft('the')",
"[null, null, the one, 1, the two, 2, the three, 3]"
);
do_execsql_test(db,
"SELECT fts5_aux1(ft, b), fts5_aux1(ft) FROM ft('the')",
"[null, 1, 1, 2, 2, 3, 3, null]"
);
}
/*
** Test of various Fts5ExtensionApi methods
*/
private static void test4(){
/* Open db and populate an fts5 table */
sqlite3 db = createNewDb();
create_test_functions(db);
do_execsql_test(db,
"CREATE VIRTUAL TABLE ft USING fts5(a, b);" +
"INSERT INTO ft(a, b) VALUES('one two three', 'two three four');" +
"INSERT INTO ft(a, b) VALUES('two three four', 'three four five');" +
"INSERT INTO ft(a, b) VALUES('three four five', 'four five six');"
);
do_execsql_test(db,
"SELECT fts5_inst(ft) FROM ft('two')",
"[{0 0 1} {0 1 0}, {0 0 0}]"
);
do_execsql_test(db,
"SELECT fts5_inst(ft) FROM ft('four')",
"[{0 1 2}, {0 0 2} {0 1 1}, {0 0 1} {0 1 0}]"
);
do_execsql_test(db,
"SELECT fts5_inst(ft) FROM ft('a OR b OR four')",
"[{2 1 2}, {2 0 2} {2 1 1}, {2 0 1} {2 1 0}]"
);
do_execsql_test(db,
"SELECT fts5_inst(ft) FROM ft('two four')",
"[{0 0 1} {0 1 0} {1 1 2}, {0 0 0} {1 0 2} {1 1 1}]"
);
do_execsql_test(db,
"SELECT fts5_pinst(ft) FROM ft('two')",
"[{0 0 1} {0 1 0}, {0 0 0}]"
);
do_execsql_test(db,
"SELECT fts5_pinst(ft) FROM ft('four')",
"[{0 1 2}, {0 0 2} {0 1 1}, {0 0 1} {0 1 0}]"
);
do_execsql_test(db,
"SELECT fts5_pinst(ft) FROM ft('a OR b OR four')",
"[{2 1 2}, {2 0 2} {2 1 1}, {2 0 1} {2 1 0}]"
);
do_execsql_test(db,
"SELECT fts5_pinst(ft) FROM ft('two four')",
"[{0 0 1} {0 1 0} {1 1 2}, {0 0 0} {1 0 2} {1 1 1}]"
);
do_execsql_test(db,
"SELECT fts5_pcolinst(ft) FROM ft('two')",
"[{0 0} {0 1}, {0 0}]"
);
do_execsql_test(db,
"SELECT fts5_pcolinst(ft) FROM ft('four')",
"[{0 1}, {0 0} {0 1}, {0 0} {0 1}]"
);
do_execsql_test(db,
"SELECT fts5_pcolinst(ft) FROM ft('a OR b OR four')",
"[{2 1}, {2 0} {2 1}, {2 0} {2 1}]"
);
do_execsql_test(db,
"SELECT fts5_pcolinst(ft) FROM ft('two four')",
"[{0 0} {0 1} {1 1}, {0 0} {1 0} {1 1}]"
);
do_execsql_test(db,
"SELECT fts5_phrasesize(ft, 0) FROM ft('four five six') LIMIT 1;",
"[1]"
);
do_execsql_test(db,
"SELECT fts5_phrasesize(ft, 0) FROM ft('four + five + six') LIMIT 1;",
"[3]"
);
sqlite3_close_v2(db);
}
private static void test5(){
/* Open db and populate an fts5 table */
sqlite3 db = createNewDb();
create_test_functions(db);
do_execsql_test(db,
"CREATE VIRTUAL TABLE ft USING fts5(x, b);" +
"INSERT INTO ft(x) VALUES('one two three four five six seven eight');" +
"INSERT INTO ft(x) VALUES('one two one four one six one eight');" +
"INSERT INTO ft(x) VALUES('one two three four five six seven eight');"
);
do_execsql_test(db,
"SELECT fts5_phrasehits(ft, 0) FROM ft('one') LIMIT 1",
"[6]"
);
sqlite3_close_v2(db);
}
private static void test6(){
sqlite3 db = createNewDb();
create_test_functions(db);
do_execsql_test(db,
"CREATE VIRTUAL TABLE ft USING fts5(x, b);" +
"INSERT INTO ft(x) VALUES('one two three four five six seven eight');"
);
do_execsql_test(db,
"SELECT fts5_tokenize(ft, 'abc def ghi') FROM ft('one')",
"[abc+def+ghi]"
);
do_execsql_test(db,
"SELECT fts5_tokenize(ft, 'it''s BEEN a...') FROM ft('one')",
"[it+s+been+a]"
);
sqlite3_close_v2(db);
}
private static synchronized void runTests(){
test1();
test2();
test3();
test4();
test5();
test6();
}
public TesterFts5(){
runTests();
}
}
ext/jni/src/org/sqlite/jni/fts5/XTokenizeCallback.java
+22
View File
@@ -0,0 +1,22 @@
/*
** 2023-08-04
**
** 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.fts5;
/**
Callback type for use with xTokenize() variants.
*/
public interface XTokenizeCallback {
int call(int tFlags, byte[] txt, int iStart, int iEnd);
}
ext/jni/src/org/sqlite/jni/fts5/fts5_api.java
+76
View File
@@ -0,0 +1,76 @@
/*
** 2023-08-05
**
** 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.fts5;
import org.sqlite.jni.annotation.*;
import org.sqlite.jni.capi.*;
/**
A wrapper for communicating C-level (fts5_api*) instances with
Java. These wrappers do not own their associated pointer, they
simply provide a type-safe way to communicate it between Java and C
via JNI.
*/
public final class fts5_api extends NativePointerHolder<fts5_api> {
/* Only invoked from JNI */
private fts5_api(){}
public static final int iVersion = 2;
/**
Returns the fts5_api instance associated with the given db, or
null if something goes horribly wrong.
*/
public static synchronized native fts5_api getInstanceForDb(@NotNull sqlite3 db);
public synchronized native int xCreateFunction(@NotNull String name,
@Nullable Object userData,
@NotNull fts5_extension_function xFunction);
/**
Convenience overload which passes null as the 2nd argument to the
3-parameter form.
*/
public int xCreateFunction(@NotNull String name,
@NotNull fts5_extension_function xFunction){
return xCreateFunction(name, null, xFunction);
}
// /* Create a new auxiliary function */
// int (*xCreateFunction)(
// fts5_api *pApi,
// const char *zName,
// void *pContext,
// fts5_extension_function xFunction,
// void (*xDestroy)(void*)
// );
// Still potentially todo:
// int (*xCreateTokenizer)(
// fts5_api *pApi,
// const char *zName,
// void *pContext,
// fts5_tokenizer *pTokenizer,
// void (*xDestroy)(void*)
// );
// /* Find an existing tokenizer */
// int (*xFindTokenizer)(
// fts5_api *pApi,
// const char *zName,
// void **ppContext,
// fts5_tokenizer *pTokenizer
// );
}
ext/jni/src/org/sqlite/jni/fts5/fts5_extension_function.java
+51
View File
@@ -0,0 +1,51 @@
/*
** 2023-08-05
**
** 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.fts5;
import org.sqlite.jni.capi.sqlite3_context;
import org.sqlite.jni.capi.sqlite3_value;
/**
JNI-level wrapper for C's fts5_extension_function type.
*/
public interface fts5_extension_function {
// typedef void (*fts5_extension_function)(
// const Fts5ExtensionApi *pApi, /* API offered by current FTS version */
// Fts5Context *pFts, /* First arg to pass to pApi functions */
// sqlite3_context *pCtx, /* Context for returning result/error */
// int nVal, /* Number of values in apVal[] array */
// sqlite3_value **apVal /* Array of trailing arguments */
// );
/**
The callback implementation, corresponding to the xFunction
argument of C's fts5_api::xCreateFunction().
*/
void call(Fts5ExtensionApi ext, Fts5Context fCx,
sqlite3_context pCx, sqlite3_value argv[]);
/**
Is called when this function is destroyed by sqlite3. Typically
this function will be empty.
*/
void xDestroy();
/**
A base implementation of fts5_extension_function() which has a
no-op xDestroy() method.
*/
abstract class Abstract implements fts5_extension_function {
@Override public abstract void call(Fts5ExtensionApi ext, Fts5Context fCx,
sqlite3_context pCx, sqlite3_value argv[]);
@Override public void xDestroy(){}
}
}
ext/jni/src/org/sqlite/jni/fts5/fts5_tokenizer.java
+49
View File
@@ -0,0 +1,49 @@
/*
** 2023-08-05
**
** 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.fts5;
import org.sqlite.jni.capi.NativePointerHolder;
import org.sqlite.jni.annotation.NotNull;
/**
A wrapper for communicating C-level (fts5_tokenizer*) instances with
Java. These wrappers do not own their associated pointer, they
simply provide a type-safe way to communicate it between Java and C
via JNI.
*/
public final class fts5_tokenizer extends NativePointerHolder<fts5_tokenizer> {
/* Only invoked by JNI */
private fts5_tokenizer(){}
// int (*xCreate)(void*, const char **azArg, int nArg, Fts5Tokenizer **ppOut);
// void (*xDelete)(Fts5Tokenizer*);
public native int xTokenize(@NotNull Fts5Tokenizer t, int tokFlags,
@NotNull byte pText[],
@NotNull XTokenizeCallback callback);
// int (*xTokenize)(Fts5Tokenizer*,
// void *pCtx,
// int flags, /* Mask of FTS5_TOKENIZE_* flags */
// const char *pText, int nText,
// int (*xToken)(
// void *pCtx, /* Copy of 2nd argument to xTokenize() */
// int tflags, /* Mask of FTS5_TOKEN_* flags */
// const char *pToken, /* Pointer to buffer containing token */
// int nToken, /* Size of token in bytes */
// int iStart, /* Byte offset of token within input text */
// int iEnd /* Byte offset of end of token within input text */
// )
// );
}
ext/jni/src/org/sqlite/jni/test-script-interpreter.md
+270
View File
@@ -0,0 +1,270 @@
# Specifications For A Rudimentary SQLite Test Script Interpreter
## Overview
The purpose of the Test Script Interpreter is to read and interpret
script files that contain SQL commands and desired results. The
interpreter will check results and report any discrepancies found.
The test script files are ASCII text files. The filename always ends with
".test". Each script is evaluated independently; context does not carry
forward from one script to the next. So, for example, the --null command
run in one test script does not cause any changes in the behavior of
subsequent test scripts. All open database connections are closed
at the end of each test script. All database files created by a test
script are deleted when the script finishes.
## Parsing Rules:
1. The test script is read line by line, where a line is a sequence of
characters that runs up to the next '\\n' (0x0a) character or until
the end of the file. There is never a need to read ahead past the
end of the current line.
2. If any line contains the string " MODULE_NAME:" (with a space before
the initial "M") or "MIXED_MODULE_NAME:" then that test script is
incompatible with this spec. Processing of the test script should
end immediately. There is no need to read any more of the file.
In verbose mode, the interpreter might choose to emit an informational
messages saying that the test script was abandoned due to an
incompatible module type.
3. If any line contains the string "SCRIPT_MODULE_NAME:" then the input
script is known to be of the correct type for this specification and
processing may continue. The "MODULE_NAME" checking in steps 2 and 3
may optionally be discontinued after sighting a "SCRIPT_MODULE_NAME".
4. If any line contains "REQUIRED_PROPERTIES:" and that substring is followed
by any non-whitespace text, then the script is not compatible with this
spec. Processing should stop immediately. In verbose mode, the
interpreter might choose to emit an information message saying that the
test script was abandoned due to unsupported requirement properties.
5. If any line begins with the "\|" (0x7c) character, that indicates that
the input script is not compatible with this specification. Processing
of the script should stop immediately. In verbose mode, the interpreter
might choose to emit an informational message indicating that the
test script was abandoned because it contained "a dbtotxt format database
specification".
6. Any line that begins with "#" is a C-preprocessor line. The interpreter
described by this spec does not know how to deal with C-preprocessor lines.
Hence, processing should be abandoned. In verbose mode, the interpreter
might emit an informational message similar to
"script NAME abandoned due to C-preprocessor line: ..."
7. If a line begins with exactly two minus signs followed by a
lowercase letter, that is a command. Process commands as described
below.
8. All other lines should be accumulated into the "input buffer".
The various commands will have access to this input buffer.
Some commands will reset the buffer.
## Initialization
The initial state of the interpreter at the start of processing each script
is as if the following command sequence had been run:
> ~~~
--close all
--db 0
--new test.db
--null nil
~~~
In words, all database connections are closed except for connection 0 (the
default) which is open on an empty database named "test.db". The string
"nil" is displayed for NULL column values.
The only context carried forward after the evaluation of one test script
into the evaluation of the next test script is the count of the number of
tests run and the number of failures seen.
## Commands:
Each command looks like an SQL comment. The command begins at the left
margin (no leading space) and starts with exactly 2 minus signs ("-").
The command name consists of lowercase letters and maybe a "-" or two.
Some commands have arguments.
The arguments are separated from the command name by one or more spaces.
Commands have access to the input buffer and might reset the input buffer.
The command can also optionally read (and consume) additional text from
script that comes after the command.
Unknown or unrecognized commands indicate that the script contains features
that are not (yet) supported by this specification. Processing of the
script should terminate immediately. When this happens and when the
interpreter is in a "verbose" mode, the interpreter might choose to emit
an informational message along the lines of "test script NAME abandoned
due to unsupported command: --whatever".
The initial implementation will only recognize a few commands. Other
commands may be added later. The following is the initial set of
commands:
### The --testcase command
Every test case starts with a --testcase command. The --testcase
command resets both the "input buffer" and the "result buffer". The
argument to the --testcase command is the name of the test case. That
test case name is used for logging and debugging and when printing
errors. The input buffer is set to the body of the test case.
### The --result command
The --result command tries to execute the text in the input buffer as SQL.
For each row of result coming out of this SQL, the text of that result is
appended to the "result buffer". If a result row contains multiple columns,
the columns are processed from left to right. For each column, text is
appended to the result buffer according to the following rules:
* If the result buffer already contains some text, append a space.
(In this way, all column values and all row values are separated from
each other by a single space.)
* If sqlite3_column_text() returns NULL, then append "nil" - or
some other text that is specified by the --null command - and skip
all subsequent rules.
* If sqlite3_column_text() is an empty string, append `{}` to the
result buffer and skip all subsequent rules.
* If sqlite3_column_text() does not contain any special
characters, append it to the result buffer without any
formatting and skip all subsequent rules. Special characters are:
0x00 to 0x20 (inclusive), double-quote (0x22), backslash (0x5c),
curly braces (0x7b and 0x7d).
* If sqlite3_column_text() does not contains curly braces, then put
the text inside of `{...}` and append it and skip all subsequent rules.
* Append the text within double-quotes (`"..."`) and within the text
escape '"' and '\\' by prepending a single '\\' and escape any
control characters (characters less than 0x20) using octal notation:
'\\NNN'.
If an error is encountered while running the SQL, then append the
symbolic C-preprocessor name for the error
code (ex: "SQLITE_CONSTRAINT") as if it were a column value. Then append
the error message text as if it where a column value. Then stop processing.
After the SQL text has been run, compare the content of the result buffer
against the argument to the --result command and report a testing error if
there are any differences.
The --result command resets the input buffer, but it does not reset
the result buffer. This distinction does not matter for the --result
command itself, but it is important for related commands like --glob
and --notglob. Sometimes test cases will contains a bunch of SQL
followed by multiple --glob and/or --notglob statements. All of the
globs should be evaluated against the result buffer, but the SQL should
only be run once. This is accomplished by resetting the input buffer
but not the result buffer.
### The --glob command
The --glob command works just like --result except that the argument to
--glob is interpreted as a TEST-GLOB pattern and the results are compared
using that glob pattern rather than using strcmp(). Other than that,
the two operate the same.
The TEST-GLOB pattern is slightly different for a standard GLOB:
* The '*' character matches zero or more characters.
* The '?' character matches any single character
* The '[...]' character sequence machines a single character
in between the brackets.
* The '#' character matches one or more digits (This is the main
difference between standard unix-glob and TEST-GLOB. unix-glob
does not have this feature. It was added to because it comes
up a lot during SQLite testing.)
### The --notglob command
The --notglob command works just like --glob except that it reports an
error if the GLOB does match, rather than if the GLOB does not match.
### The --oom command
This command is to be used for out-of-memory testing. It means that
OOM errors should be simulated to ensure that SQLite is able to deal with
them. This command can be silently ignored for now. We might add support
for this later.
### The --tableresult command
The --tableresult command works like --glob except that the GLOB pattern
to be matched is taken from subsequent lines of the input script up to
the next --end. Every span of one or more whitespace characters in this
pattern text is collapsed into a single space (0x20).
Leading and trailing whitespace are removed from the pattern.
The --end that ends the GLOB pattern is not part of the GLOB pattern, but
the --end is consumed from the script input.
### The --new and --open commands
The --new and --open commands cause a database file to be opened.
The name of the file is the argument to the command. The --new command
opens an initially empty database (it deletes the file before opening it)
whereas the --open command opens an existing database if it already
exists.
### The --db command
The script interpreter can have up to 7 different SQLite database
connections open at a time. The --db command is used to switch between
them. The argument to --db is an integer between 0 and 6 that selects
which database connection to use moving forward.
### The --close command
The --close command causes an existing database connection to close.
This command is a no-op if the database connection is not currently
open. There can be up to 7 different database connections, numbered 0
through 6. The number of the database connection to close is an
argument to the --close command, which will fail if an out-of-range
value is provided. Or if the argument to --close is "all" then all
open database connections are closed. If passed no argument, the
currently-active database is assumed.
### The --null command
The NULL command changes the text that is used to represent SQL NULL
values in the result buffer.
### The --run command
The --run command executes text in the input buffer as if it where SQL.
However, nothing is added to the result buffer. Any output from the SQL
is silently ignored. Errors in the SQL are silently ignored.
The --run command normally executes the SQL in the current database
connection. However, if --run has an argument that is an integer between
0 and 6 then the SQL is run in the alternative database connection specified
by that argument.
### The --json and --json-block commands
The --json and --json-block commands work like --result and --tableresult,
respectively. The difference is that column values are appended to the
result buffer literally, without ever enclosing the values in `{...}` or
`"..."` and without escaping any characters in the column value and comparison
is always an exact strcmp() not a GLOB.
### The --print command
The --print command emits both its arguments and its body (if any) to
stdout, indenting each line of output.
### The --column-names command
The --column-names command requires 0 or 1 as an argument, to disable
resp. enable it, and modifies SQL execution to include column names
in output. When this option is on, each column value emitted gets
prefixed by its column name, with a single space between them.
ext/jni/src/org/sqlite/jni/wrapper1/AggregateFunction.java
+144
View File
@@ -0,0 +1,144 @@
/*
** 2023-10-16
**
** 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;
/**
EXPERIMENTAL/INCOMPLETE/UNTESTED
A SqlFunction implementation for aggregate functions. The T type
represents the type of data accumulated by this aggregate while it
works. e.g. a SUM()-like UDF might use Integer or Long and a
CONCAT()-like UDF might use a StringBuilder or a List<String>.
*/
public abstract class AggregateFunction<T> implements SqlFunction {
/**
As for the xStep() argument of the C API's
sqlite3_create_function(). If this function throws, the
exception is reported via sqlite3_result_error().
*/
public abstract void xStep(SqlFunction.Arguments args);
/**
As for the xFinal() argument of the C API's
sqlite3_create_function(). If this function throws, it is
translated into sqlite3_result_error().
Note that the passed-in object will not actually contain any
arguments for xFinal() but will contain the context object needed
for setting the call's result or error state.
*/
public abstract void xFinal(SqlFunction.Arguments args);
/**
Optionally override to be notified when the UDF is finalized by
SQLite.
*/
public void xDestroy() {}
/**
PerContextState assists aggregate and window functions in
managing their accumulator state across calls to the UDF's
callbacks.
<p>T must be of a type which can be legally stored as a value in
java.util.HashMap<KeyType,T>.
<p>If a given aggregate or window function is called multiple times
in a single SQL statement, e.g. SELECT MYFUNC(A), MYFUNC(B)...,
then the clients need some way of knowing which call is which so
that they can map their state between their various UDF callbacks
and reset it via xFinal(). This class takes care of such
mappings.
<p>This class works by mapping
sqlite3_context.getAggregateContext() to a single piece of
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.
Client UDFs are free to perform such mappings using custom
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
= new java.util.HashMap<>();
/**
Should be called from a UDF's xStep(), xValue(), and xInverse()
methods, passing it that method's first argument and an initial
value for the persistent state. If there is currently no
mapping for the given context within the map, one is created
using the given initial value, else the existing one is used
and the 2nd argument is ignored. It returns a ValueHolder<T>
which can be used to modify that state directly without
requiring that the client update the underlying map's entry.
<p>The caller is obligated to eventually call
takeAggregateState() to clear the mapping.
*/
public ValueHolder<T> getAggregateState(SqlFunction.Arguments args, T initialValue){
final Long key = args.getContext().getAggregateContext(true);
ValueHolder<T> rc = null==key ? null : map.get(key);
if( null==rc ){
map.put(key, rc = new ValueHolder<>(initialValue));
}
return rc;
}
/**
Should be called from a UDF's xFinal() method and passed that
method's first argument. This function removes the value
associated with with the arguments' aggregate context from the
map and returns it, returning null if no other UDF method has
been called to set up such a mapping. The latter condition will
be the case if a UDF is used in a statement which has no result
rows.
*/
public T takeAggregateState(SqlFunction.Arguments args){
final ValueHolder<T> h = map.remove(args.getContext().getAggregateContext(false));
return null==h ? null : h.value;
}
}
/** Per-invocation state for the UDF. */
private final PerContextState<T> map = new PerContextState<>();
/**
To be called from the implementation's xStep() method, as well
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
calls, the 2nd argument is ignored.
@see SQLFunction.PerContextState#getAggregateState
*/
protected final ValueHolder<T> getAggregateState(SqlFunction.Arguments args, T initialValue){
return map.getAggregateState(args, initialValue);
}
/**
To be called from the implementation's xFinal() method to fetch
the final state of the UDF and remove its mapping.
see SQLFunction.PerContextState#takeAggregateState
*/
protected final T takeAggregateState(SqlFunction.Arguments args){
return map.takeAggregateState(args);
}
}
ext/jni/src/org/sqlite/jni/wrapper1/ScalarFunction.java
+33
View File
@@ -0,0 +1,33 @@
/*
** 2023-10-16
**
** 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;
/**
The SqlFunction type for scalar SQL functions.
*/
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
translated into an sqlite3_result_error().
*/
public abstract void xFunc(SqlFunction.Arguments args);
/**
Optionally override to be notified when the UDF is finalized by
SQLite. This default implementation does nothing.
*/
public void xDestroy() {}
}
ext/jni/src/org/sqlite/jni/wrapper1/SqlFunction.java
+318
View File
@@ -0,0 +1,318 @@
/*
** 2023-10-16
**
** 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 org.sqlite.jni.capi.CApi;
import org.sqlite.jni.capi.sqlite3_context;
import org.sqlite.jni.capi.sqlite3_value;
/**
Base marker interface for SQLite's three types of User-Defined SQL
Functions (UDFs): Scalar, Aggregate, and Window functions.
*/
public interface SqlFunction {
int DETERMINISTIC = CApi.SQLITE_DETERMINISTIC;
int INNOCUOUS = CApi.SQLITE_INNOCUOUS;
int DIRECTONLY = CApi.SQLITE_DIRECTONLY;
int SUBTYPE = CApi.SQLITE_SUBTYPE;
int RESULT_SUBTYPE = CApi.SQLITE_RESULT_SUBTYPE;
int UTF8 = CApi.SQLITE_UTF8;
int UTF16 = CApi.SQLITE_UTF16;
/**
The Arguments type is an abstraction on top of the lower-level
UDF function argument types. It provides _most_ of the functionality
of the lower-level interface, insofar as possible without "leaking"
those types into this API.
*/
final class Arguments implements Iterable<SqlFunction.Arguments.Arg>{
private final sqlite3_context cx;
private final sqlite3_value args[];
public final int length;
/**
Must be passed the context and arguments for the UDF call this
object is wrapping. Intended to be used by internal proxy
classes which "convert" the lower-level interface into this
package's higher-level interface, e.g. ScalarAdapter and
AggregateAdapter.
Passing null for the args is equivalent to passing a length-0
array.
*/
Arguments(sqlite3_context cx, sqlite3_value args[]){
this.cx = cx;
this.args = args==null ? new sqlite3_value[0] : args;
this.length = this.args.length;
}
/**
Returns the sqlite3_value at the given argument index or throws
an IllegalArgumentException exception if ndx is out of range.
*/
private sqlite3_value valueAt(int ndx){
if(ndx<0 || ndx>=args.length){
throw new IllegalArgumentException(
"SQL function argument index "+ndx+" is out of range."
);
}
return args[ndx];
}
//! Returns the underlying sqlite3_context for these arguments.
sqlite3_context getContext(){return cx;}
/**
Returns the Sqlite (db) object associated with this UDF call,
or null if the UDF is somehow called without such an object or
the db has been closed in an untimely manner (e.g. closed by a
UDF call).
*/
public Sqlite getDb(){
return Sqlite.fromNative( CApi.sqlite3_context_db_handle(cx) );
}
public int getArgCount(){ return args.length; }
public int getInt(int argNdx){return CApi.sqlite3_value_int(valueAt(argNdx));}
public long getInt64(int argNdx){return CApi.sqlite3_value_int64(valueAt(argNdx));}
public double getDouble(int argNdx){return CApi.sqlite3_value_double(valueAt(argNdx));}
public byte[] getBlob(int argNdx){return CApi.sqlite3_value_blob(valueAt(argNdx));}
public byte[] getText(int argNdx){return CApi.sqlite3_value_text(valueAt(argNdx));}
public String getText16(int argNdx){return CApi.sqlite3_value_text16(valueAt(argNdx));}
public int getBytes(int argNdx){return CApi.sqlite3_value_bytes(valueAt(argNdx));}
public int getBytes16(int argNdx){return CApi.sqlite3_value_bytes16(valueAt(argNdx));}
public Object getObject(int argNdx){return CApi.sqlite3_value_java_object(valueAt(argNdx));}
public <T> T getObject(int argNdx, Class<T> type){
return CApi.sqlite3_value_java_object(valueAt(argNdx), type);
}
public int getType(int argNdx){return CApi.sqlite3_value_type(valueAt(argNdx));}
public int getSubtype(int argNdx){return CApi.sqlite3_value_subtype(valueAt(argNdx));}
public int getNumericType(int argNdx){return CApi.sqlite3_value_numeric_type(valueAt(argNdx));}
public int getNoChange(int argNdx){return CApi.sqlite3_value_nochange(valueAt(argNdx));}
public boolean getFromBind(int argNdx){return CApi.sqlite3_value_frombind(valueAt(argNdx));}
public int getEncoding(int argNdx){return CApi.sqlite3_value_encoding(valueAt(argNdx));}
public void resultInt(int v){ CApi.sqlite3_result_int(cx, v); }
public void resultInt64(long v){ CApi.sqlite3_result_int64(cx, v); }
public void resultDouble(double v){ CApi.sqlite3_result_double(cx, v); }
public void resultError(String msg){CApi.sqlite3_result_error(cx, msg);}
public void resultError(Exception e){CApi.sqlite3_result_error(cx, e);}
public void resultErrorTooBig(){CApi.sqlite3_result_error_toobig(cx);}
public void resultErrorCode(int rc){CApi.sqlite3_result_error_code(cx, rc);}
public void resultObject(Object o){CApi.sqlite3_result_java_object(cx, o);}
public void resultNull(){CApi.sqlite3_result_null(cx);}
/**
Analog to sqlite3_result_value(), using the Value object at the
given argument index.
*/
public void resultArg(int argNdx){CApi.sqlite3_result_value(cx, valueAt(argNdx));}
public void resultSubtype(int subtype){CApi.sqlite3_result_subtype(cx, subtype);}
public void resultZeroBlob(long n){
// Throw on error? If n is too big,
// sqlite3_result_error_toobig() is automatically called.
CApi.sqlite3_result_zeroblob64(cx, n);
}
public void resultBlob(byte[] blob){CApi.sqlite3_result_blob(cx, blob);}
public void resultText(byte[] utf8){CApi.sqlite3_result_text(cx, utf8);}
public void resultText(String txt){CApi.sqlite3_result_text(cx, txt);}
public void resultText16(byte[] utf16){CApi.sqlite3_result_text16(cx, utf16);}
public void resultText16(String txt){CApi.sqlite3_result_text16(cx, txt);}
/**
Callbacks should invoke this on OOM errors, instead of throwing
OutOfMemoryError, because the latter cannot be propagated
through the C API.
*/
public void resultNoMem(){CApi.sqlite3_result_error_nomem(cx);}
/**
Analog to sqlite3_set_auxdata() but throws if argNdx is out of
range.
*/
public void setAuxData(int argNdx, Object o){
/* From the API docs: https://sqlite.org/c3ref/get_auxdata.html
The value of the N parameter to these interfaces should be
non-negative. Future enhancements may make use of negative N
values to define new kinds of function caching behavior.
*/
valueAt(argNdx);
CApi.sqlite3_set_auxdata(cx, argNdx, o);
}
/**
Analog to sqlite3_get_auxdata() but throws if argNdx is out of
range.
*/
public Object getAuxData(int argNdx){
valueAt(argNdx);
return CApi.sqlite3_get_auxdata(cx, argNdx);
}
/**
Represents a single SqlFunction argument. Primarily intended
for use with the Arguments class's Iterable interface.
*/
public final static class Arg {
private final Arguments a;
private final int ndx;
/* Only for use by the Arguments class. */
private Arg(Arguments a, int ndx){
this.a = a;
this.ndx = ndx;
}
/** Returns this argument's index in its parent argument list. */
public int getIndex(){return ndx;}
public int getInt(){return a.getInt(ndx);}
public long getInt64(){return a.getInt64(ndx);}
public double getDouble(){return a.getDouble(ndx);}
public byte[] getBlob(){return a.getBlob(ndx);}
public byte[] getText(){return a.getText(ndx);}
public String getText16(){return a.getText16(ndx);}
public int getBytes(){return a.getBytes(ndx);}
public int getBytes16(){return a.getBytes16(ndx);}
public Object getObject(){return a.getObject(ndx);}
public <T> T getObject(Class<T> type){ return a.getObject(ndx, type); }
public int getType(){return a.getType(ndx);}
public Object getAuxData(){return a.getAuxData(ndx);}
public void setAuxData(Object o){a.setAuxData(ndx, o);}
}
@Override
public java.util.Iterator<SqlFunction.Arguments.Arg> iterator(){
final Arg[] proxies = new Arg[args.length];
for( int i = 0; i < args.length; ++i ){
proxies[i] = new Arg(this, i);
}
return java.util.Arrays.stream(proxies).iterator();
}
}
/**
Internal-use adapter for wrapping this package's ScalarFunction
for use with the org.sqlite.jni.capi.ScalarFunction interface.
*/
final class ScalarAdapter extends org.sqlite.jni.capi.ScalarFunction {
private final ScalarFunction impl;
ScalarAdapter(ScalarFunction impl){
this.impl = impl;
}
/**
Proxies this.impl.xFunc(), adapting the call arguments to that
function's signature. If the proxy throws, it's translated to
sqlite_result_error() with the exception's message.
*/
public void xFunc(sqlite3_context cx, sqlite3_value[] args){
try{
impl.xFunc( new SqlFunction.Arguments(cx, args) );
}catch(Exception e){
CApi.sqlite3_result_error(cx, e);
}
}
public void xDestroy(){
impl.xDestroy();
}
}
/**
Internal-use adapter for wrapping this package's AggregateFunction
for use with the org.sqlite.jni.capi.AggregateFunction interface.
*/
class AggregateAdapter extends org.sqlite.jni.capi.AggregateFunction {
/*cannot be final without duplicating the whole body in WindowAdapter*/
private final AggregateFunction impl;
AggregateAdapter(AggregateFunction impl){
this.impl = impl;
}
/**
Proxies this.impl.xStep(), adapting the call arguments to that
function's signature. If the proxied function throws, it is
translated to sqlite_result_error() with the exception's
message.
*/
public void xStep(sqlite3_context cx, sqlite3_value[] args){
try{
impl.xStep( new SqlFunction.Arguments(cx, args) );
}catch(Exception e){
CApi.sqlite3_result_error(cx, e);
}
}
/**
As for the xFinal() argument of the C API's
sqlite3_create_function(). If the proxied function throws, it
is translated into a sqlite3_result_error().
*/
public void xFinal(sqlite3_context cx){
try{
impl.xFinal( new SqlFunction.Arguments(cx, null) );
}catch(Exception e){
CApi.sqlite3_result_error(cx, e);
}
}
public void xDestroy(){
impl.xDestroy();
}
}
/**
Internal-use adapter for wrapping this package's WindowFunction
for use with the org.sqlite.jni.capi.WindowFunction interface.
*/
final class WindowAdapter extends AggregateAdapter {
private final WindowFunction impl;
WindowAdapter(WindowFunction impl){
super(impl);
this.impl = impl;
}
/**
Proxies this.impl.xInverse(), adapting the call arguments to that
function's signature. If the proxied function throws, it is
translated to sqlite_result_error() with the exception's
message.
*/
public void xInverse(sqlite3_context cx, sqlite3_value[] args){
try{
impl.xInverse( new SqlFunction.Arguments(cx, args) );
}catch(Exception e){
CApi.sqlite3_result_error(cx, e);
}
}
/**
As for the xValue() argument of the C API's sqlite3_create_window_function().
If the proxied function throws, it is translated into a sqlite3_result_error().
*/
public void xValue(sqlite3_context cx){
try{
impl.xValue( new SqlFunction.Arguments(cx, null) );
}catch(Exception e){
CApi.sqlite3_result_error(cx, e);
}
}
public void xDestroy(){
impl.xDestroy();
}
}
}
ext/jni/src/org/sqlite/jni/wrapper1/Sqlite.java
+1994
View File
File diff suppressed because it is too large. Load diff
ext/jni/src/org/sqlite/jni/wrapper1/SqliteException.java
+85
View File
@@ -0,0 +1,85 @@
/*
** 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 org.sqlite.jni.capi.CApi;
import org.sqlite.jni.capi.sqlite3;
/**
A wrapper for communicating C-level (sqlite3*) instances with
Java. These wrappers do not own their associated pointer, they
simply provide a type-safe way to communicate it between Java
and C via JNI.
*/
public final class SqliteException extends java.lang.RuntimeException {
private int errCode = CApi.SQLITE_ERROR;
private int xerrCode = CApi.SQLITE_ERROR;
private int errOffset = -1;
private int sysErrno = 0;
/**
Records the given error string and uses SQLITE_ERROR for both the
error code and extended error code.
*/
public SqliteException(String msg){
super(msg);
}
/**
Uses sqlite3_errstr(sqlite3ResultCode) for the error string and
sets both the error code and extended error code to the given
value. This approach includes no database-level information and
systemErrno() will be 0, so is intended only for use with sqlite3
APIs for which a result code is not an error but which the
higher-level wrapper should treat as one.
*/
public SqliteException(int sqlite3ResultCode){
super(CApi.sqlite3_errstr(sqlite3ResultCode));
errCode = xerrCode = sqlite3ResultCode;
}
/**
Records the current error state of db (which must not be null and
must refer to an opened db object). Note that this does not close
the db.
Design note: closing the db on error is really only useful during
a failed db-open operation, and the place(s) where that can
happen are inside this library, not client-level code.
*/
SqliteException(sqlite3 db){
super(CApi.sqlite3_errmsg(db));
errCode = CApi.sqlite3_errcode(db);
xerrCode = CApi.sqlite3_extended_errcode(db);
errOffset = CApi.sqlite3_error_offset(db);
sysErrno = CApi.sqlite3_system_errno(db);
}
/**
Records the current error state of db (which must not be null and
must refer to an open database).
*/
public SqliteException(Sqlite db){
this(db.nativeHandle());
}
public SqliteException(Sqlite.Stmt stmt){
this(stmt.getDb());
}
public int errcode(){ return errCode; }
public int extendedErrcode(){ return xerrCode; }
public int errorOffset(){ return errOffset; }
public int systemErrno(){ return sysErrno; }
}
ext/jni/src/org/sqlite/jni/wrapper1/Tester2.java
+1212
View File
File diff suppressed because it is too large. Load diff
ext/jni/src/org/sqlite/jni/wrapper1/ValueHolder.java
+25
View File
@@ -0,0 +1,25 @@
/*
** 2023-10-16
**
** 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 contains the ValueHolder utility class.
*/
package org.sqlite.jni.wrapper1;
/**
A helper class which simply holds a single value. Its primary use
is for communicating values out of anonymous callbacks, as doing so
requires a "final" reference.
*/
public class ValueHolder<T> {
public T value;
public ValueHolder(){}
public ValueHolder(T v){value = v;}
}
ext/jni/src/org/sqlite/jni/wrapper1/WindowFunction.java
+42
View File
@@ -0,0 +1,42 @@
/*
** 2023-10-16
**
** 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;
/**
A SqlFunction implementation for window functions. The T type
represents the type of data accumulated by this function while it
works. e.g. a SUM()-like UDF might use Integer or Long and a
CONCAT()-like UDF might use a StringBuilder or a List<String>.
*/
public abstract class WindowFunction<T> extends AggregateFunction<T> {
/**
As for the xInverse() argument of the C API's
sqlite3_create_window_function(). If this function throws, the
exception is reported via sqlite3_result_error().
*/
public abstract void xInverse(SqlFunction.Arguments args);
/**
As for the xValue() argument of the C API's
sqlite3_create_window_function(). If this function throws, it is
translated into sqlite3_result_error().
Note that the passed-in object will not actually contain any
arguments for xValue() but will contain the context object needed
for setting the call's result or error state.
*/
public abstract void xValue(SqlFunction.Arguments args);
}
ext/jni/src/tests/000-000-sanity.test
+53
View File
@@ -0,0 +1,53 @@
/*
** This is a comment. There are many like it but this one is mine.
**
** SCRIPT_MODULE_NAME: sanity-check
** xMIXED_MODULE_NAME: mixed-module
** xMODULE_NAME: module-name
** xREQUIRED_PROPERTIES: small fast reliable
** xREQUIRED_PROPERTIES: RECURSIVE_TRIGGERS
** xREQUIRED_PROPERTIES: TEMPSTORE_FILE TEMPSTORE_MEM
** xREQUIRED_PROPERTIES: AUTOVACUUM INCRVACUUM
**
*/
--print starting up 😃
--close all
--oom
--db 0
--new my.db
--null zilch
--testcase 1.0
SELECT 1, null;
--result 1 zilch
--glob *zil*
--notglob *ZIL*
SELECT 1, 2;
intentional error;
--run
--testcase json-1
SELECT json_array(1,2,3)
--json [1,2,3]
--testcase tableresult-1
select 1, 'a';
select 2, 'b';
--tableresult
# [a-z]
2 b
--end
--testcase json-block-1
select json_array(1,2,3);
select json_object('a',1,'b',2);
--json-block
[1,2,3]
{"a":1,"b":2}
--end
--testcase col-names-on
--column-names 1
select 1 as 'a', 2 as 'b';
--result a 1 b 2
--testcase col-names-off
--column-names 0
select 1 as 'a', 2 as 'b';
--result 1 2
--close
--print reached the end 😃
ext/jni/src/tests/000-001-ignored.test
+9
View File
@@ -0,0 +1,9 @@
/*
** This script must be marked as ignored because it contains
** content which triggers that condition.
**
** SCRIPT_MODULE_NAME: ignored
**
*/
|
ext/jni/src/tests/900-001-fts.test
+12
View File
@@ -0,0 +1,12 @@
/*
** SCRIPT_MODULE_NAME: fts5-sanity-checks
** xREQUIRED_PROPERTIES: FTS5
**
*/
--testcase 1.0
CREATE VIRTUAL TABLE email USING fts5(sender, title, body);
insert into email values('fred','Help!','Dear Sir...');
insert into email values('barney','Assistance','Dear Madam...');
select * from email where email match 'assistance';
--result barney Assistance {Dear Madam...}