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

FossilOrigin-Name: 0f4b223102e5dc9142c9d2cb8892b8d3cc476e579420028b93d4e12f4cf94d3e

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)/%,\

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{}

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
+@Documented
-@java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.SOURCE)
+@Retention(RetentionPolicy.SOURCE)
-@java.lang.annotation.Target(java.lang.annotation.ElementType.PARAMETER)
+@Target(ElementType.PARAMETER)
 public @interface NotNull{}

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
+@Documented
-@java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.SOURCE)
+@Retention(RetentionPolicy.SOURCE)
-@java.lang.annotation.Target(java.lang.annotation.ElementType.PARAMETER)
+@Target(ElementType.PARAMETER)
 public @interface Nullable{}

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
   );

manifest

@@ -1,5 +1,5 @@
-C JNI\stest\scode\scleanups.
+C JNI:\sadd\sthe\s@Experimental\sannotation\sand\smark\sall\sjava.nio.ByteBuffer-related\smethods\swith\sit.
-D 2023-11-15T05:08:39.794
+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/Experimental.java 8603498634e41d0f7c70f661f64e05df64376562ea8f126829fd1e0cdd47e82b
-F ext/jni/src/org/sqlite/jni/annotation/Nullable.java 0b1879852707f752512d4db9d7edd0d8db2f0c2612316ce1c832715e012ff6ba
+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
+P 09142ac14347e6f41bbe50bc835920e271713452733a478ede547816cc291ace
-R 11f7f6d131495fb464d838c1bb741013
+R cfcc320e0959e3a4de2a4fc818c2a559
 U stephan
-Z c06836e611da7dd2a6fb9a46b70f157f
+Z c96b2596adaae992941a9453741b8e02
 # Remove this line to create a well-formed Fossil manifest.

manifest.uuid

@@ -1 +1 @@
-09142ac14347e6f41bbe50bc835920e271713452733a478ede547816cc291ace
+0f4b223102e5dc9142c9d2cb8892b8d3cc476e579420028b93d4e12f4cf94d3e