CollationNeeded.java \
CommitHook.java \
NativePointerHolder.java \
+ NotNull.java \
+ Nullable.java \
OutputPointer.java \
+ package-info.java \
ProgressHandler.java \
ResultCode.java \
RollbackHook.java \
jar: $(package.jar)
-dir.doc := $(dir.jni)/doc
-doc: $(JAVA_FILES.main)
+dir.doc := $(dir.jni)/javadoc
+doc.index := $(dir.doc)/index.html
+$(doc.index): $(JAVA_FILES.main) $(MAKEFILE)
+ @if [ -d $(dir.doc) ]; then rm -fr $(dir.doc)/*; fi
$(bin.javadoc) -cp $(classpath) -d $(dir.doc) -quiet org.sqlite.jni
-
+ @echo "javadoc output is in $@"
+
+.PHONY: doc javadoc docserve
+.FORCE: doc
+doc: $(doc.index)
+javadoc: $(doc.index)
+docserve: $(doc.index)
+ cd $(dir.doc) && althttpd -max-age 1 -page index.html
########################################################################
# Clean up...
CLEAN_FILES += $(dir.bld.c)/* \
-rm -f $(CLEAN_FILES)
distclean: clean
-rm -f $(DISTCLEAN_FILES)
- -rm -fr $(dir.bld.c)
+ -rm -fr $(dir.bld.c) $(dir.doc)
########################################################################
# disttribution bundle rules...
*/
public interface Authorizer {
/**
- Must functions as described for the sqlite3_set_authorizer()
- callback, with one caveat: the string values passed here were
- initially (at the C level) encoded in standard UTF-8. If they
- contained any constructs which are not compatible with MUTF-8,
- these strings will not have the expected values. For further
- details, see the documentation for the SQLite3Jni class.
+ Must function as described for the sqlite3_set_authorizer()
+ callback.
Must not throw.
*/
NativePointerHolder is not inadvertently passed to an incompatible
function signature.
- These objects do not _own_ the pointer they refer to. They are
+ 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> {
--- /dev/null
+package org.sqlite.jni;
+
+/**
+ This annotation is for flagging parameters which may not legally be
+ null. Note that the C-style API does not throw any
+ NullPointerExceptions on its own because it has a no-throw policy
+ in order to retain its C-style semantics.
+
+ <p>This annotation is informational only. No policy is in place to
+ programmatically ensure that NotNull is conformed to in client
+ code.
+
+ <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.
+*/
+@java.lang.annotation.Documented
+@java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.SOURCE)
+@java.lang.annotation.Target(java.lang.annotation.ElementType.PARAMETER)
+public @interface NotNull{}
--- /dev/null
+package org.sqlite.jni;
+
+/**
+ 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.
+
+ <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.
+*/
+@java.lang.annotation.Documented
+@java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.SOURCE)
+@java.lang.annotation.Target(java.lang.annotation.ElementType.PARAMETER)
+public @interface Nullable{}
/**
Helper classes for handling JNI output pointers.
- We do not use a generic OutputPointer<T> because working with those
+ <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.
- The usage is similar for all of thes types:
+ <p>The usage is similar for all of thes types:
- ```
+ <pre>{@code
OutputPointer.sqlite3 out = new OutputPointer.sqlite3();
assert( null==out.get() );
int rc = sqlite3_open(":memory:", out);
assert( null!=out.get() );
sqlite3 db = out.take();
assert( null==out.get() );
- ```
+ }</pre>
- With the minor exception that the primitive types permit direct
+ <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.
- Warning: do not share instances of these classes across
+ <p>Warning: do not share instances of these classes across
threads. Doing so may lead to corrupting sqlite3-internal state.
*/
public final class OutputPointer {
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
-/**
- 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.
-
- This annotation is solely for the reader's information.
-*/
-@Documented
-@Retention(RetentionPolicy.SOURCE)
-@Target(ElementType.PARAMETER)
-@interface Nullable{}
-
-/**
- This annotation is for flagging parameters which may not legally be
- null. Note that the C-style API does not throw any
- NullPointerExceptions on its own because it has a no-throw policy
- in order to retain its C-style semantics.
-
- This annotation is solely for the reader's information. No policy
- is in place to programmatically ensure that NotNull is conformed to
- in client code.
-*/
-@Documented
-@Retention(RetentionPolicy.SOURCE)
-@Target(ElementType.PARAMETER)
-@interface NotNull{}
-
/**
This class contains the entire sqlite3 JNI API binding. For
client-side use, a static import is recommended:
- {@code
+ <pre>{@code
import static org.sqlite.jni.SQLite3Jni.*;
- }
+ }</pre>
- The C-side part can be found in sqlite3-jni.c.
+ <p>The C-side part can be found in sqlite3-jni.c.
<p>Only functions which materially differ from their C counterparts
- are documented here. The C documetation is otherwise applicable
- here:
+ are documented here. The C documentation is otherwise applicable
+ for these APIs:
- <p>{link https://sqlite.org/c3ref/intro.html}
+ <p><a href="https://sqlite.org/c3ref/intro.html">https://sqlite.org/c3ref/intro.html</a>
<p>A handful of Java-specific APIs have been added.
but JNI uses what its docs call modified UTF-8 (see links below)
Care must be taken when converting Java strings to or from standard
UTF-8 to ensure that the proper conversion is performed. In short,
- Java's `String.getBytes(StandardCharsets.UTF_8)` performs the proper
+ Java's {@code String.getBytes(StandardCharsets.UTF_8)} performs the proper
conversion in Java, and there are no JNI C APIs for that conversion
- (JNI's `NewStringUTF()` requires its input to be in MUTF-8).
+ (JNI's {@code NewStringUTF()} requires its input to be in MUTF-8).
<p>The known consequences and limitations this discrepancy places on
the SQLite3 JNI binding include:
<ul>
- <li>Any functions which return state from a database take extra care
- to perform proper conversion, at the cost of efficiency.</li>
-
<li>C functions which take C-style strings without a length argument
require special care when taking input from Java. In particular,
Java strings converted to byte arrays for encoding purposes are not
- NUL-terminated, and conversion to a Java byte array must be careful
- to add one. Functions which take a length do not require this so
- long as the length is provided. Search the SQLite3Jni class for "\0"
- for many examples.
-
- <li>Similarly, C-side code which deals with strings which might not
- be NUL-terminated (e.g. while tokenizing in FTS5-related code)
- cannot use JNI's new-string functions to return them to Java because
- none of those APIs take a string-length argument. Such cases must
- return byte arrays instead of strings.
+ NUL-terminated, and conversion to a Java byte array must sometimes
+ be careful to add one. Functions which take a length do not require
+ this so long as the length is provided. Search the SQLite3Jni class
+ for "\0" for many examples.
</ul>
/**
Binds the SQL result to the given object, or
- sqlite3_result_null() if o is null. Use
- sqlite3_value_java_object() or sqlite3_column_java_object() to
+ {@link #sqlite3_result_null(sqlite3_context) sqlite3_result_null()} if {@code o} is null. Use
+ {@link #sqlite3_value_java_object(sqlite3_value) sqlite3_value_java_object()} or
+ {@link #sqlite3_column_java_object(sqlite3_stmt,int) sqlite3_column_java_object()} to
fetch it.
This is implemented in terms of sqlite3_result_pointer(), but
/**
Binds the given text using C's sqlite3_result_blob64() unless:
- - blob is null ==> sqlite3_result_null()
+ - @param blob is null ==> sqlite3_result_null()
- - blob is too large ==> sqlite3_result_error_toobig()
+ - @param blob is too large ==> sqlite3_result_error_toobig()
- If maxLen is larger than blob.length, it is truncated to that
+ If @param maxLen is larger than blob.length, it is truncated to that
value. If it is negative, results are undefined.
*/
private static native void sqlite3_result_blob64(
- text is too large: translates to a call to
sqlite3_result_error_toobig()
- - The `encoding` argument has an invalid value: translates to
+ - The @param encoding argument has an invalid value: translates to
sqlite3_result_error_code() with code SQLITE_FORMAT.
If maxLength (in bytes, not characters) is larger than
This package houses a JNI binding to the SQLite3 C API.
The docs are in progress.
+
+ The primary interfaces are in {@link org.sqlite.jni.SQLite3Jni}.
*/
package org.sqlite.jni;
<p>Consider this SQL, where MYFUNC is a user-defined aggregate function:
- {code
+ <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
-C Re-frame\sthe\sincongruous\sSQLite3Jni.uncacheThread()\sAPI\sas\ssqlite3_java_uncache_thread().
-D 2023-08-24T22:28:44.239
+C javadoc\sadditions.
+D 2023-08-25T00:27:28.089
F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
F ext/icu/README.txt 7ab7ced8ae78e3a645b57e78570ff589d4c672b71370f5aa9e1cd7024f400fc9
F ext/icu/icu.c c074519b46baa484bb5396c7e01e051034da8884bad1a1cb7f09bbe6be3f0282
F ext/icu/sqliteicu.h fa373836ed5a1ee7478bdf8a1650689294e41d0c89c1daab26e9ae78a32075a8
-F ext/jni/GNUmakefile 6aeafa0ebcf0f0d834c814ae8b450b54135ea11a2a7868f90b6286ec1bf6020f
+F ext/jni/GNUmakefile 642624b421936807eeed2fe7d0f9df898837ad0e4be4d9e32af06b0e5ef2c5b6
F ext/jni/README.md 9d3caa2e038bfe5e8356a9e8ff66f93ca0647ac278339eeea296f10017f5cf35
F ext/jni/jar-dist.make 030aaa4ae71dd86e4ec5e7c1e6cd86f9dfa47c4592c070d2e35157e42498e1fa
F ext/jni/src/c/sqlite3-jni.c e4bdcd17e8f8e825f206e1c6ab5adf7f507d70b64b0f795c0cde141077fb68b2
F ext/jni/src/c/sqlite3-jni.h 91c2eeee22d3594e6652d51edcce0cd94d258a768802fcfac13a78f900127b72
-F ext/jni/src/org/sqlite/jni/Authorizer.java 1308988f7f40579ea0e4deeaec3c6be971630566bd021c31367fe3f5140db892
+F ext/jni/src/org/sqlite/jni/Authorizer.java e6cbc6605d4d254be892d5197dea6290180efb7c5dbb3060f8487563bb11bb65
F ext/jni/src/org/sqlite/jni/AutoExtension.java bcc1849b2fccbe5e2d7ac9e9ac7f8d05a6d7088a8fedbaad90e39569745a61e6
F ext/jni/src/org/sqlite/jni/BusyHandler.java 1b1d3e5c86cd796a0580c81b6af6550ad943baa25e47ada0dcca3aff3ebe978c
F ext/jni/src/org/sqlite/jni/Collation.java 8dffbb00938007ad0967b2ab424d3c908413af1bbd3d212b9c9899910f1218d1
F ext/jni/src/org/sqlite/jni/Fts5Function.java 65cde7151e441fee012250a5e03277de7babcd11a0c308a832b7940574259bcc
F ext/jni/src/org/sqlite/jni/Fts5PhraseIter.java 6642beda341c0b1b46af4e2d7f6f9ab03a7aede43277b2c92859176d6bce3be9
F ext/jni/src/org/sqlite/jni/Fts5Tokenizer.java 91489893596b6528c0df5cd7180bd5b55809c26e2b797fb321dfcdbc1298c060
-F ext/jni/src/org/sqlite/jni/NativePointerHolder.java 8110d4cfb20884e8ed241de7420c615b040a9f9c441d9cff06f34833399244a8
-F ext/jni/src/org/sqlite/jni/OutputPointer.java bb09fee5ad51d10e58075de000f8c1a3622a6c4b6a390ef134b6add1bfb32ca1
+F ext/jni/src/org/sqlite/jni/NativePointerHolder.java 564087036449a16df148dcf0a067408bd251170bf23286c655f46b5f973e8b2d
+F ext/jni/src/org/sqlite/jni/NotNull.java a4016df436f454e8d6786dd8421484edd6fc604043cf7fd8ec94cf922ba61604
+F ext/jni/src/org/sqlite/jni/Nullable.java b2f8755970e9dd0e917a505638d036ccc699c8422f1a69fe9d98c0804beaea17
+F ext/jni/src/org/sqlite/jni/OutputPointer.java 8d7b2c865217d3b7a47dccaddc4a24748463b770eecca90873402a38c0b2d819
F ext/jni/src/org/sqlite/jni/PreUpdateHook.java dec00a706b58c67989f0ff56c4f0a703821d25b45c62dd7fed1b462049f15c26
F ext/jni/src/org/sqlite/jni/ProgressHandler.java 6f62053a828a572de809828b1ee495380677e87daa29a1c57a0e2c06b0a131dc
F ext/jni/src/org/sqlite/jni/ResultCode.java ba701f20213a5f259e94cfbfdd36eb7ac7ce7797f2c6c7fca2004ff12ce20f86
F ext/jni/src/org/sqlite/jni/RollbackHook.java b04c8abcc6ade44a8a57129e33765793f69df0ba909e49ba18d73f4268d92564
F ext/jni/src/org/sqlite/jni/SQLFunction.java 4d6291fa14fcca1a040609378f9f00a193145d79c3abbda98ba32c340904cbeb
F ext/jni/src/org/sqlite/jni/SQLLog.java c60610b35208416940822e834d61f08fbbe5d6e06b374b541b49e41fd56c9798
-F ext/jni/src/org/sqlite/jni/SQLite3Jni.java 5fddc34787b26a494dc9843ea2530cd319dc7a6bd369fd4e86dc713f20640fa6
+F ext/jni/src/org/sqlite/jni/SQLite3Jni.java af2d1a673f48bed8bb39ad9f7fe79c3d904cb2c6c875254a0e8c7e7db6539725
F ext/jni/src/org/sqlite/jni/Tester1.java e9b82c561ec8771b3e4ea537ebd7c16dd096928b6b8221967a4726104c7c6cb2
F ext/jni/src/org/sqlite/jni/TesterFts5.java 6f135c60e24c89e8eecb9fe61dde0f3bb2906de668ca6c9186bcf34bdaf94629
F ext/jni/src/org/sqlite/jni/Tracer.java a5cece9f947b0af27669b8baec300b6dd7ff859c3e6a6e4a1bd8b50f9714775d
F ext/jni/src/org/sqlite/jni/fts5_api.java 5198be71c162e3e0cb1f4962a7cdf0d7596e8af53f70c4af6db24aab8d53d9ba
F ext/jni/src/org/sqlite/jni/fts5_extension_function.java ac825035d7d83fc7fd960347abfa6803e1614334a21533302041823ad5fc894c
F ext/jni/src/org/sqlite/jni/fts5_tokenizer.java e530b36e6437fcc500e95d5d75fbffe272bdea20d2fac6be2e1336c578fba98b
-F ext/jni/src/org/sqlite/jni/package-info.java 1a547913d681411d65c5fe0bca840f049abe5612740154a125545ea9e2481747
+F ext/jni/src/org/sqlite/jni/package-info.java 5652d1bcaaf3ccb06d26c174e6d0b60571a545a0a3354dd8303960677be05e14
F ext/jni/src/org/sqlite/jni/sqlite3.java 62b1b81935ccf3393472d17cb883dc5ff39c388ec3bc1de547f098a0217158fc
-F ext/jni/src/org/sqlite/jni/sqlite3_context.java 42df6769ab9c8de40d24f39f49152cdaa6e0c06d1468660a95dfee9ecaeb9a63
+F ext/jni/src/org/sqlite/jni/sqlite3_context.java dca23e54f368f8ea37c112c1d2f74dc9522d5da2fdf67d6fd6b2ec9603d8514c
F ext/jni/src/org/sqlite/jni/sqlite3_stmt.java 78e6d1b95ac600a9475e9db4623f69449322b0c93d1bd4e1616e76ed547ed9fc
F ext/jni/src/org/sqlite/jni/sqlite3_value.java 3d1d4903e267bc0bc81d57d21f5e85978eff389a1a6ed46726dbe75f85e6914a
F ext/jni/src/org/sqlite/jni/tester/SQLTester.java bc3d6797a2f6cb7d443a0b72af84e5a45e0416b96af52e432d28e123db1970c3
F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 3f684ef5018116f4be46a07779451c8983ac87a5db182477f71ee7bf28287a04
-R ce1f562cc06444ed73ad1cad9371c48a
+P 7232b033954fae40df3db43e489e0e5a703c03308f500a1ae36fd9d707632d7f
+R 2acb197dd02e88e8595f80978f7eae58
U stephan
-Z fbdf5ee5d7ecf00150898b00dcd91489
+Z c7c0446afbe0f68b470086328d8c934a
# Remove this line to create a well-formed Fossil manifest.
-7232b033954fae40df3db43e489e0e5a703c03308f500a1ae36fd9d707632d7f
\ No newline at end of file
+bedf33d403677d243a1505ce549166850ab55671700b143278db5feb84883ab3
\ No newline at end of file
projects / thirdparty / sqlite.git / commitdiff
