Tweaks and docs for the OutputPointer family of Java classes.

FossilOrigin-Name: 265c8fd0d4d425054f6bf7e9cb607ad2e0e46189f16c3014f7fdf9b650085497

ext/jni/src/org/sqlite/jni/OutputPointer.java

@@ -21,21 +21,54 @@ package org.sqlite.jni;
    autoboxing at that level.
 */
 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.sqlite3 value;
     public sqlite3(){value = null;}
     public void clear(){value = null;}
     public final org.sqlite.jni.sqlite3 getValue(){return value;}
+    /** Equivalent to calling getValue() then clear(). */
+    public final org.sqlite.jni.sqlite3 takeValue(){
+      final org.sqlite.jni.sqlite3 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.sqlite3_stmt value;
     public sqlite3_stmt(){value = null;}
     public void clear(){value = null;}
     public final org.sqlite.jni.sqlite3_stmt getValue(){return value;}
+    /** Equivalent to calling getValue() then clear(). */
+    public final org.sqlite.jni.sqlite3_stmt takeValue(){
+      final org.sqlite.jni.sqlite3_stmt v = value;
+      value = null;
+      return 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;
     public Int32(){this(0);}
     public Int32(int v){value = v;}
@@ -43,7 +76,15 @@ public final class OutputPointer {
     public final void setValue(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;
     public Int64(){this(0);}
     public Int64(long v){value = v;}
@@ -51,7 +92,15 @@ public final class OutputPointer {
     public final void setValue(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;
     public String(){this(null);}
     public String(java.lang.String v){value = v;}
@@ -59,7 +108,15 @@ public final class OutputPointer {
     public final void setValue(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;
     public ByteArray(){this(null);}
     public ByteArray(byte[] v){value = v;}

ext/jni/src/org/sqlite/jni/Tester1.java

@@ -69,14 +69,15 @@ public class Tester1 {
     final OutputPointer.sqlite3 out = new OutputPointer.sqlite3();
     int rc = sqlite3_open(":memory:", out);
     ++metrics.dbOpen;
-    sqlite3 db = out.getValue();
+    sqlite3 db = out.takeValue();
     if( 0!=rc ){
       final String msg = db.getNativePointer()==0
         ? sqlite3_errstr(rc)
         : sqlite3_errmsg(db);
       throw new RuntimeException("Opening db failed: "+msg);
     }
-    affirm(0 != db.getNativePointer());
+    affirm( null == out.getValue() );
+    affirm( 0 != db.getNativePointer() );
     rc = sqlite3_busy_timeout(db, 2000);
     affirm( 0 == rc );
     return db;
@@ -102,8 +103,8 @@ public class Tester1 {
       rc = sqlite3_prepare_v2(db, sqlChunk, outStmt, oTail);
       if(throwOnError) affirm(0 == rc);
       else if( 0!=rc ) break;
-      pos = oTail.getValue();
-      stmt = outStmt.getValue();
+      pos = oTail.value;
+      stmt = outStmt.takeValue();
       if( null == stmt ){
         // empty statement was parsed.
         continue;
@@ -134,8 +135,8 @@ public class Tester1 {
     outStmt.clear();
     int rc = sqlite3_prepare(db, sql, outStmt);
     affirm( 0 == rc );
-    final sqlite3_stmt rv = outStmt.getValue();
-    outStmt.clear();
+    final sqlite3_stmt rv = outStmt.takeValue();
+    affirm( null == outStmt.getValue() );
     affirm( 0 != rv.getNativePointer() );
     return rv;
   }
@@ -208,7 +209,7 @@ public class Tester1 {
         rc = sqlite3_prepare_v2(db, sqlChunk, outStmt, oTail);
         affirm(0 == rc);
         stmt = outStmt.getValue();
-        pos = oTail.getValue();
+        pos = oTail.value;
         /*outln("SQL tail pos = "+pos+". Chunk = "+
               (new String(Arrays.copyOfRange(sqlChunk,0,pos),
               StandardCharsets.UTF_8)));*/

ext/jni/src/org/sqlite/jni/TesterFts5.java

@@ -49,7 +49,7 @@ public class TesterFts5 {
             for(int i = 0; i < nCols; ++i ){
               int rc = ext.xColumnText(fCx, i, op);
               affirm( 0 == rc );
-              final String val = op.getValue();
+              final String val = op.value;
               affirm( val.equals(sqlite3_value_text(argv[i])) );
               //outln("xFunction col "+i+": "+val);
             }

ext/jni/src/org/sqlite/jni/tester/SQLTester.java

@@ -368,7 +368,7 @@ public class SQLTester {
     if( createIfNeeded ) flags |= SQLITE_OPEN_CREATE;
     final OutputPointer.sqlite3 out = new OutputPointer.sqlite3();
     int rc = sqlite3_open_v2(name, out, flags, null);
-    final sqlite3 db = out.getValue();
+    final sqlite3 db = out.takeValue();
     if( 0==rc && dbInitSql.length() > 0){
       //outln("RUNNING DB INIT CODE: ",dbInitSql.toString());
       rc = execSql(db, false, ResultBufferMode.NONE,
@@ -518,8 +518,8 @@ public class SQLTester {
           }
           break;
         }
-        pos = oTail.getValue();
-        stmt = outStmt.getValue();
+        pos = oTail.value;
+        stmt = outStmt.takeValue();
         if( null == stmt ){
           // empty statement was parsed.
           continue;