From: stephan Date: Mon, 9 Oct 2023 10:44:10 +0000 (+0000) Subject: Minor JNI doc and public/private cleanups. X-Git-Tag: version-3.44.0~144 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=fd013682d66673602318e2520de94b21196c37fc;p=thirdparty%2Fsqlite.git Minor JNI doc and public/private cleanups. FossilOrigin-Name: c49d36ece283274963ce2e5a4db1e8f586dffa22e47f4adb93c625f918c3fd5d --- diff --git a/ext/jni/src/org/sqlite/jni/CApi.java b/ext/jni/src/org/sqlite/jni/CApi.java index 26b83d1971..8149d624ad 100644 --- a/ext/jni/src/org/sqlite/jni/CApi.java +++ b/ext/jni/src/org/sqlite/jni/CApi.java @@ -35,10 +35,11 @@ import java.util.Arrays;

This class is package-private in order to keep Java clients from having direct access to the low-level C-style APIs, a design decision made by Java developers based on the C-style API being - riddled with opportunities for other Java to proverbially shoot + riddled with opportunities for Java developers to proverbially shoot themselves in the foot with. Third-party copies of this code may eliminate that guard by simply changing this class from - package-private to public. + package-private to public. Its methods which are intended to be + exposed that way are all public.

Only functions which materially differ from their C counterparts are documented here, and only those material differences are @@ -100,8 +101,8 @@ final class CApi { private static native void init(); /** - Returns a nul-terminated copy of s as a byte array, or null if s - is null. + Returns a nul-terminated copy of s as a UTF-8-encoded byte array, + or null if s is null. */ private static byte[] nulTerminateUtf8(String s){ return null==s ? null : (s+"\0").getBytes(StandardCharsets.UTF_8); @@ -127,8 +128,7 @@ final class CApi {

This routine returns false without side effects if the current JNIEnv is not cached, else returns true, but this information is primarily for testing of the JNI bindings and is not information - which client-level code should use to make any informed - decisions. + which client-level code can use to make any informed decisions. */ public static native boolean sqlite3_java_uncache_thread(); @@ -159,15 +159,15 @@ final class CApi { Functions almost as documented for the C API, with these exceptions: -

- The callback interface is is shorter because of +

- The callback interface is shorter because of cross-language differences. Specifically, 3rd argument to the C auto-extension callback interface is unnecessary here. -

The C API docs do not specifically say so, but if the list of auto-extensions is manipulated from an auto-extension, it is undefined which, if any, auto-extensions will subsequently - execute for the current database. + execute for the current database. That is, doing so will result + in unpredictable, but not undefined, behavior.

See the AutoExtension class docs for more information. */ @@ -297,7 +297,7 @@ final class CApi { overload than to do that in C, so that signature is the public-facing one. */ - static native int sqlite3_bind_parameter_index( + private static native int sqlite3_bind_parameter_index( @NotNull long ptrToStmt, @NotNull byte[] paramName ); @@ -701,7 +701,7 @@ final class CApi { This implementation is private because it's too easy to pass it non-NUL-terminated byte arrays from client code. */ - public static native int sqlite3_complete( + private static native int sqlite3_complete( @NotNull byte[] nulTerminatedUtf8Sql ); @@ -709,7 +709,7 @@ final class CApi { Unlike the C API, this returns SQLITE_MISUSE if its argument is null (as opposed to invoking UB). */ - static int sqlite3_complete(@NotNull String sql){ + public static int sqlite3_complete(@NotNull String sql){ return sqlite3_complete( nulTerminateUtf8(sql) ); } @@ -970,7 +970,7 @@ final class CApi { more ways to shoot themselves in the foot without providing any real utility. */ - static native int sqlite3_prepare( + private static native int sqlite3_prepare( @NotNull long ptrToDb, @NotNull byte[] sqlUtf8, int maxBytes, @NotNull OutputPointer.sqlite3_stmt outStmt, @Nullable OutputPointer.Int32 pTailOffset @@ -1028,7 +1028,7 @@ final class CApi { /** @see #sqlite3_prepare */ - static native int sqlite3_prepare_v2( + private static native int sqlite3_prepare_v2( @NotNull long ptrToDb, @NotNull byte[] sqlUtf8, int maxBytes, @NotNull OutputPointer.sqlite3_stmt outStmt, @Nullable OutputPointer.Int32 pTailOffset @@ -1080,7 +1080,7 @@ final class CApi { /** @see #sqlite3_prepare */ - static native int sqlite3_prepare_v3( + private static native int sqlite3_prepare_v3( @NotNull long ptrToDb, @NotNull byte[] sqlUtf8, int maxBytes, int prepFlags, @NotNull OutputPointer.sqlite3_stmt outStmt, @Nullable OutputPointer.Int32 pTailOffset @@ -1518,7 +1518,7 @@ final class CApi { This overload is private because its final parameter is arguably unnecessary in Java. */ - public static native void sqlite3_result_blob( + private static native void sqlite3_result_blob( @NotNull sqlite3_context cx, @Nullable byte[] blob, int maxLen ); @@ -1546,7 +1546,7 @@ final class CApi {

This overload is private because its final parameter is arguably unnecessary in Java.

*/ - public static native void sqlite3_result_blob64( + private static native void sqlite3_result_blob64( @NotNull sqlite3_context cx, @Nullable byte[] blob, long maxLen ); @@ -1560,7 +1560,7 @@ final class CApi { This overload is private because its final parameter is arguably unnecessary in Java. */ - public static native void sqlite3_result_text( + private static native void sqlite3_result_text( @NotNull sqlite3_context cx, @Nullable byte[] utf8, int maxLen ); @@ -1603,7 +1603,7 @@ final class CApi { This overload is private because its maxLength parameter is arguably unnecessary in Java. */ - public static native void sqlite3_result_text64( + private static native void sqlite3_result_text64( @NotNull sqlite3_context cx, @Nullable byte[] text, long maxLength, int encoding ); @@ -1713,7 +1713,7 @@ final class CApi { (sqlite3_strglob(String,String)) than to do that in C, so that signature is the public-facing one. */ - public static native int sqlite3_strglob( + private static native int sqlite3_strglob( @NotNull byte[] glob, @NotNull byte[] nullTerminatedUtf8 ); @@ -1727,7 +1727,7 @@ final class CApi { /** The LIKE counterpart of the private sqlite3_strglob() method. */ - public static native int sqlite3_strlike( + private static native int sqlite3_strlike( @NotNull byte[] glob, @NotNull byte[] nullTerminatedUtf8, int escChar ); diff --git a/manifest b/manifest index dfdd2ee2fd..cc9a595b87 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Rename\sSQLite3Jni\sto\sCApi\sto\s(A)\sreduce\sname\sprefix\scollisions\swith\sincoming\sclasses\sand\s(B)\salign\swith\sits\scounterpart\sin\sthe\sJS\sbuild.\sRemove\sthe\sCanonical\sannotation\sbecause\s(A)\sthe\snew\scode\sseparation\swill\sinherently\smake\sthat\sdistinction\sand\s(B)\sthe\sline\sbetween\struly\scanonical\sand\ssemi-canonical\s(e.g.\sdiffering\sin\ssignature\soverloads)\sis\sblurry\senough\sthat\sconsistent\suse\sof\sthat\sannocation\sis\sbecoming\san\sunnecessary\sburden. -D 2023-10-09T10:30:54.032 +C Minor\sJNI\sdoc\sand\spublic/private\scleanups. +D 2023-10-09T10:44:10.717 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724 @@ -245,7 +245,7 @@ F ext/jni/src/org/sqlite/jni/AggregateFunction.java 7312486bc65fecdb91753c0a4515 F ext/jni/src/org/sqlite/jni/AuthorizerCallback.java fde5f758ad170ca45ae00b12194c8ba8d8f3090bd64cc3e002dd9c5e7dff8568 F ext/jni/src/org/sqlite/jni/AutoExtensionCallback.java c0fbfd3779fc92982c7935325a7484dee43eeb80d716989ed31218f453addb94 F ext/jni/src/org/sqlite/jni/BusyHandlerCallback.java 4cb7fc70efd55583fed6033c34a8719da42975ca97ef4781dda0b9f6cc8ec2e8 -F ext/jni/src/org/sqlite/jni/CApi.java 573a700536f8ed91584041894b35087d7183e10005b19d3e4cbb2c7f4147358d w ext/jni/src/org/sqlite/jni/SQLite3Jni.java +F ext/jni/src/org/sqlite/jni/CApi.java c1dde485a3a3f43c46c8d9c527f9ba5bf303fe0409b2c0de253fb7b6e1055f7e F ext/jni/src/org/sqlite/jni/CallbackProxy.java 064a8a00e4c63cc501c30504f93ca996d422c5f010067f969b2d0a10f0868153 F ext/jni/src/org/sqlite/jni/CollationCallback.java 8cf57cb014a645ecc12609eed17308852a597bc5e83d82a4fdb90f7fadc25f9d F ext/jni/src/org/sqlite/jni/CollationNeededCallback.java 0c62245e000d5db52576c728cac20f6a31f31f5cf40ca4cbcd64b22964e82ae5 @@ -2124,8 +2124,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 c4ab4200dc2538e1132d87d70fd309b26b0da8a918fede1cb09b567ea40ec889 -R 9e5ca9b62d5fe5ed2cf201efbae39e9e +P ca216b4486aff7d206ebfc3a5e84d48919c282425d4313396bc19313ffca8a0e +R af6221100b1b0f5eb240f10a6b3978ab U stephan -Z 5086984ef977bc443ff4f93b9408b66c +Z ff4bc4025115006080a68d26c19680b4 # Remove this line to create a well-formed Fossil manifest. diff --git a/manifest.uuid b/manifest.uuid index 550c5267f1..6ee1c62b7d 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -ca216b4486aff7d206ebfc3a5e84d48919c282425d4313396bc19313ffca8a0e \ No newline at end of file +c49d36ece283274963ce2e5a4db1e8f586dffa22e47f4adb93c625f918c3fd5d \ No newline at end of file