JNI: add the @Experimental annotation and mark all java.nio.ByteBuffer-related methods with it.

FossilOrigin-Name: 0f4b223102e5dc9142c9d2cb8892b8d3cc476e579420028b93d4e12f4cf94d3e
2023-11-15 06:10:37 +00:00 · 2023-11-15 06:10:37 +00:00 · 6b36312e8a
commit 6b36312e8a
parent 973011432b
7 changed files with 74 additions and 19 deletions
--- a/ext/jni/GNUmakefile
+++ b/ext/jni/GNUmakefile
@ -81,6 +81,7 @@ $(bin.version-info): $(dir.tool)/version-info.c $(sqlite3.h) $(dir.top)/Makefile
 # 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 statae.
 JAVA_FILES.main := $(patsubst %,$(dir.src.jni)/annotation/%,\
+  Experimental.java \
  NotNull.java \
  Nullable.java \
 ) $(patsubst %,$(dir.src.capi)/%,\
--- a/ext/jni/src/org/sqlite/jni/annotation/Experimental.java
+++ b/ext/jni/src/org/sqlite/jni/annotation/Experimental.java
@ -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{}
--- a/ext/jni/src/org/sqlite/jni/annotation/NotNull.java
+++ b/ext/jni/src/org/sqlite/jni/annotation/NotNull.java
@ -9,9 +9,10 @@
 **    May you share freely, never taking more than you give.
 **
 *************************************************************************
-** This file houses the NotNull annotaion for the sqlite3 C API.
+** 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
@ -64,7 +65,7 @@ package org.sqlite.jni.annotation;
   part of the public API and client-level code must not rely on
   it.</p>
 */
-@java.lang.annotation.Documented
-@java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.SOURCE)
-@java.lang.annotation.Target(java.lang.annotation.ElementType.PARAMETER)
+@Documented
+@Retention(RetentionPolicy.SOURCE)
+@Target(ElementType.PARAMETER)
 public @interface NotNull{}
--- a/ext/jni/src/org/sqlite/jni/annotation/Nullable.java
+++ b/ext/jni/src/org/sqlite/jni/annotation/Nullable.java
@ -9,9 +9,10 @@
 **    May you share freely, never taking more than you give.
 **
 *************************************************************************
-** This file houses the Nullable annotaion for the sqlite3 C API.
+** 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
@ -26,7 +27,7 @@ package org.sqlite.jni.annotation;
   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)
+@Documented
+@Retention(RetentionPolicy.SOURCE)
+@Target(ElementType.PARAMETER)
 public @interface Nullable{}
--- a/ext/jni/src/org/sqlite/jni/capi/CApi.java
+++ b/ext/jni/src/org/sqlite/jni/capi/CApi.java
@ -9,7 +9,7 @@
 **    May you share freely, never taking more than you give.
 **
 *************************************************************************
-** This file declares JNI bindings for the sqlite3 C API.
+** This file declares the main JNI bindings for the sqlite3 C API.
 */
 package org.sqlite.jni.capi;
 import java.nio.charset.StandardCharsets;
@ -129,6 +129,7 @@ public final class CApi {
     Returns true if this JVM has JNI-level support for C-level direct
     memory access using java.nio.ByteBuffer, else returns false.
  */
+  @Experimental
  public static native boolean sqlite3_jni_supports_nio();

  /**
@ -254,6 +255,7 @@ public final class CApi {
     Convenience overload which is a simple proxy for
     sqlite3_bind_nio_buffer().
  */
+  @Experimental
  public static int sqlite3_bind_blob(
    @NotNull sqlite3_stmt stmt, int ndx, @Nullable java.nio.ByteBuffer data,
    int begin, int n
@ -266,6 +268,7 @@ public final class CApi {
     to sqlite3_bind_nio_buffer() with the values 0 and -1 for the
     final two arguments.
  */
+  @Experimental
  public static int sqlite3_bind_blob(
    @NotNull sqlite3_stmt stmt, int ndx, @Nullable java.nio.ByteBuffer data
  ){
@ -342,6 +345,7 @@ public final class CApi {

     @see https://docs.oracle.com/javase/8/docs/api/java/nio/Buffer.html
  */
+  @Experimental
  public static native int sqlite3_bind_nio_buffer(
    @NotNull sqlite3_stmt stmt, int ndx, @Nullable java.nio.ByteBuffer data,
    int beginPos, int howMany
@ -351,6 +355,7 @@ public final class CApi {
     Convenience overload which binds the given buffer's entire
     contents, up to its limit() (as opposed to its capacity()).
  */
+  @Experimental
  public static int sqlite3_bind_nio_buffer(
    @NotNull sqlite3_stmt stmt, int ndx, @Nullable java.nio.ByteBuffer data
  ){
@ -578,6 +583,7 @@ public final class CApi {
  /**
     An internal level of indirection.
  */
+  @Experimental
  private static native int sqlite3_blob_read_nio_buffer(
    @NotNull long ptrToBlob, int srcOffset,
    @NotNull java.nio.ByteBuffer tgt, int tgtOffset, int howMany
@ -593,6 +599,7 @@ public final class CApi {
     succeeds, it returns the result of the underlying call to
     sqlite3_blob_read() (0 on success).
  */
+  @Experimental
  public static int sqlite3_blob_read_nio_buffer(
    @NotNull sqlite3_blob src, int srcOffset,
    @NotNull java.nio.ByteBuffer tgt, int tgtOffset, int howMany
@ -616,6 +623,7 @@ public final class CApi {
     the src blob, or the underlying call to sqlite3_blob_read() fails
     for any reason.
  */
+  @Experimental
  public static java.nio.ByteBuffer sqlite3_blob_read_nio_buffer(
    @NotNull sqlite3_blob src, int srcOffset, int howMany
  ){
@ -636,6 +644,7 @@ public final class CApi {
  /**
     Overload alias for sqlite3_blob_read_nio_buffer().
  */
+  @Experimental
  public static int sqlite3_blob_read(
    @NotNull sqlite3_blob src, int srcOffset,
    @NotNull java.nio.ByteBuffer tgt,
@ -658,6 +667,7 @@ public final class CApi {
     null or sqlite3_jni_supports_nio() returns false. Else it returns
     the result of the underlying call to sqlite3_blob_read().
  */
+  @Experimental
  public static int sqlite3_blob_read(
    @NotNull sqlite3_blob src,
    @NotNull java.nio.ByteBuffer tgt
@ -694,6 +704,7 @@ public final class CApi {
  /**
     An internal level of indirection.
  */
+  @Experimental
  private static native int sqlite3_blob_write_nio_buffer(
    @NotNull long ptrToBlob, int tgtOffset,
    @NotNull java.nio.ByteBuffer src,
@ -715,6 +726,7 @@ public final class CApi {
     either offset is negative.  If argument validation succeeds, it
     returns the result of the underlying call to sqlite3_blob_read().
  */
+  @Experimental
  public static int sqlite3_blob_write_nio_buffer(
    @NotNull sqlite3_blob tgt, int tgtOffset,
    @NotNull java.nio.ByteBuffer src,
@ -728,6 +740,7 @@ public final class CApi {
  /**
     Overload alias for sqlite3_blob_write_nio_buffer().
  */
+  @Experimental
  public static int sqlite3_blob_write(
    @NotNull sqlite3_blob tgt, int tgtOffset,
    @NotNull java.nio.ByteBuffer src,
@ -742,6 +755,7 @@ public final class CApi {
     Convenience overload which writes all of src to the given offset
     of b.
  */
+  @Experimental
  public static int sqlite3_blob_write(
    @NotNull sqlite3_blob tgt, int tgtOffset,
    @NotNull java.nio.ByteBuffer src
@ -755,6 +769,7 @@ public final class CApi {
     Convenience overload which writes all of src to offset 0
     of tgt.
   */
+  @Experimental
  public static int sqlite3_blob_write(
    @NotNull sqlite3_blob tgt,
    @NotNull java.nio.ByteBuffer src
@ -910,6 +925,7 @@ public final class CApi {
     sqlite3_jni_supports_nio() is false, or if sqlite3_column_blob()
     would return null for the same inputs.
  */
+  @Experimental
  public static native java.nio.ByteBuffer sqlite3_column_nio_buffer(
    @NotNull sqlite3_stmt stmt, int ndx
  );
@ -1831,6 +1847,7 @@ public final class CApi {
     If the resulting slice of the buffer exceeds SQLITE_LIMIT_LENGTH
     then this function behaves like sqlite3_result_error_toobig().
  */
+  @Experimental
  public static native void sqlite3_result_nio_buffer(
    @NotNull sqlite3_context cx, @Nullable java.nio.ByteBuffer blob,
    int begin, int n
@ -1840,6 +1857,7 @@ public final class CApi {
     Convenience overload which uses the whole input object
     as the result blob content.
  */
+  @Experimental
  public static void sqlite3_result_nio_buffer(
    @NotNull sqlite3_context cx, @Nullable java.nio.ByteBuffer blob
  ){
@ -1944,6 +1962,7 @@ public final class CApi {
     Convenience overload which behaves like
     sqlite3_result_nio_buffer().
  */
+  @Experimental
  public static void sqlite3_result_blob(
    @NotNull sqlite3_context cx, @Nullable java.nio.ByteBuffer blob,
    int begin, int n
@ -1955,6 +1974,7 @@ public final class CApi {
     Convenience overload which behaves like the two-argument overload of
     sqlite3_result_nio_buffer().
  */
+  @Experimental
  public static void sqlite3_result_blob(
    @NotNull sqlite3_context cx, @Nullable java.nio.ByteBuffer blob
  ){
@ -2366,6 +2386,7 @@ public final class CApi {
     sqlite3_jni_supports_nio() is false, or if sqlite3_value_blob()
     would return null for the same input.
  */
+  @Experimental
  public static native java.nio.ByteBuffer sqlite3_value_nio_buffer(
    @NotNull sqlite3_value v
  );
--- a/19
+++ b/19
@ -1,5 +1,5 @@
-C JNI\stest\scode\scleanups.
-D 2023-11-15T05:08:39.794
+C JNI:\sadd\sthe\s@Experimental\sannotation\sand\smark\sall\sjava.nio.ByteBuffer-related\smethods\swith\sit.
+D 2023-11-15T06:10:37.765
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@ -238,20 +238,21 @@ F ext/fts5/tool/showfts5.tcl d54da0e067306663e2d5d523965ca487698e722c
 F ext/icu/README.txt 7ab7ced8ae78e3a645b57e78570ff589d4c672b71370f5aa9e1cd7024f400fc9
 F ext/icu/icu.c c074519b46baa484bb5396c7e01e051034da8884bad1a1cb7f09bbe6be3f0282
 F ext/icu/sqliteicu.h fa373836ed5a1ee7478bdf8a1650689294e41d0c89c1daab26e9ae78a32075a8
-F ext/jni/GNUmakefile d546fd57ed9949f7e7fc48d93a9bc9fab8ce86091e995b534eb73da5defdd21a
+F ext/jni/GNUmakefile 59eb05f2a363bdfac8d15d66bed624bfe1ff289229184f3861b95f98a19cf4b2
 F ext/jni/README.md 78a0386f6813e5201142ff07f077f4dcf1bb66266c69c6bbd09edac69cadff60
 F ext/jni/jar-dist.make 030aaa4ae71dd86e4ec5e7c1e6cd86f9dfa47c4592c070d2e35157e42498e1fa
 F ext/jni/src/c/sqlite3-jni.c 4fd9906698d296d4e4e4a54c3946461f8506f5b2a13a26cd7b27e0e5c7272bd0
 F ext/jni/src/c/sqlite3-jni.h 913ab8e8fee432ae40f0e387c8231118d17053714703f5ded18202912a8a3fbf
-F ext/jni/src/org/sqlite/jni/annotation/NotNull.java 02091a8112e33389f1c160f506cd413168c8dfacbeda608a4946c6e3557b7d5a
-F ext/jni/src/org/sqlite/jni/annotation/Nullable.java 0b1879852707f752512d4db9d7edd0d8db2f0c2612316ce1c832715e012ff6ba
+F ext/jni/src/org/sqlite/jni/annotation/Experimental.java 8603498634e41d0f7c70f661f64e05df64376562ea8f126829fd1e0cdd47e82b
+F ext/jni/src/org/sqlite/jni/annotation/NotNull.java 38e7e58a69b26dc100e458b31dfa3b2a7d67bc36d051325526ef1987d5bc8a24
+F ext/jni/src/org/sqlite/jni/annotation/Nullable.java 56e3dee1f3f703a545dfdeddc1c3d64d1581172b1ad01ffcae95c18547fafd90
 F ext/jni/src/org/sqlite/jni/annotation/package-info.java 977b374aed9d5853cbf3438ba3b0940abfa2ea4574f702a2448ee143b98ac3ca
 F ext/jni/src/org/sqlite/jni/capi/AbstractCollationCallback.java 1afa90d3f236f79cc7fcd2497e111992644f7596fbc8e8bcf7f1908ae00acd6c
 F ext/jni/src/org/sqlite/jni/capi/AggregateFunction.java 0b72cdff61533b564d65b63418129656daa9a9f30e7e7be982bd5ab394b1dbd0
 F ext/jni/src/org/sqlite/jni/capi/AuthorizerCallback.java c045a5b47e02bb5f1af91973814a905f12048c428a3504fbc5266d1c1be3de5a
 F ext/jni/src/org/sqlite/jni/capi/AutoExtensionCallback.java 74cc4998a73d6563542ecb90804a3c4f4e828cb4bd69e61226d1a51f4646e759
 F ext/jni/src/org/sqlite/jni/capi/BusyHandlerCallback.java 7b8e19810c42b0ad21a04b5d8c804b32ee5905d137148703f16a75b612c380ca
-F ext/jni/src/org/sqlite/jni/capi/CApi.java f3715903053f551abe0dacf39c77e619b832cde1f33829b582d5574eb52bb9a9
+F ext/jni/src/org/sqlite/jni/capi/CApi.java d428a1fd3b827f01c55d10d21ff35e33e7dac9e8a1d92a8b5c7d7255e67407d8
 F ext/jni/src/org/sqlite/jni/capi/CallbackProxy.java 57e2d275dcebe690b1fc1f3d34eb96879b2d7039bce30b563aee547bf45d8a8b
 F ext/jni/src/org/sqlite/jni/capi/CollationCallback.java e29bcfc540fdd343e2f5cca4d27235113f2886acb13380686756d5cabdfd065a
 F ext/jni/src/org/sqlite/jni/capi/CollationNeededCallback.java 5bfa226a8e7a92e804fd52d6e42b4c7b875fa7a94f8e2c330af8cc244a8920ab
@ -2139,8 +2140,8 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 83c49b9e71e5ae8852bab60a6fa630e22164c8efbf074c85450136781d0fffd3
-R 11f7f6d131495fb464d838c1bb741013
+P 09142ac14347e6f41bbe50bc835920e271713452733a478ede547816cc291ace
+R cfcc320e0959e3a4de2a4fc818c2a559
 U stephan
-Z c06836e611da7dd2a6fb9a46b70f157f
+Z c96b2596adaae992941a9453741b8e02
 # Remove this line to create a well-formed Fossil manifest.
--- a/manifest.uuid
+++ b/manifest.uuid
@ -1 +1 @@
-09142ac14347e6f41bbe50bc835920e271713452733a478ede547816cc291ace
+0f4b223102e5dc9142c9d2cb8892b8d3cc476e579420028b93d4e12f4cf94d3e