Query(Builder): implement Closeable. Document finalize methods.

Author: greenrobot-team

objectbox-java/src/main/java/io/objectbox/BoxStore.java

@@ -320,6 +320,10 @@ static boolean isFileOpenSync(String canonicalPath, boolean runFinalization) {
         }
     }
 
+    /**
+     * Explicitly call {@link #close()} instead to avoid expensive finalization.
+     */
+    @SuppressWarnings("deprecation") // finalize()
     @Override
     protected void finalize() throws Throwable {
         close();
@@ -433,6 +437,7 @@ public void close() {
         synchronized (this) {
             oldClosedState = closed;
             if (!closed) {
+                // Closeable recommendation: mark as closed before any code that might throw.
                 closed = true;
                 List<Transaction> transactionsToClose;
                 synchronized (transactions) {

objectbox-java/src/main/java/io/objectbox/Cursor.java

@@ -156,6 +156,10 @@ protected Cursor(Transaction tx, long cursor, EntityInfo entityInfo, BoxStore bo
         nativeSetBoxStoreForEntities(cursor, boxStore);
     }
 
+    /**
+     * Explicitly call {@link #close()} instead to avoid expensive finalization.
+     */
+    @SuppressWarnings("deprecation") // finalize()
     @Override
     protected void finalize() throws Throwable {
         if (!closed) {
@@ -217,6 +221,7 @@ public long count(long maxCountOrZero) {
     @Override
     public synchronized void close() {
         if (!closed) {
+            // Closeable recommendation: mark as closed before nativeDestroy could throw.
             closed = true;
             // tx is null despite check in constructor in some tests (called by finalizer):
             // Null check avoids NPE in finalizer and seems to stabilize Android instrumentation perf tests.

objectbox-java/src/main/java/io/objectbox/Transaction.java

@@ -77,6 +77,10 @@ public Transaction(BoxStore store, long transaction, int initialCommitCount) {
         creationThrowable = TRACK_CREATION_STACK ? new Throwable() : null;
     }
 
+    /**
+     * Explicitly call {@link #close()} instead to avoid expensive finalization.
+     */
+    @SuppressWarnings("deprecation") // finalize()
     @Override
     protected void finalize() throws Throwable {
         close();
@@ -92,6 +96,7 @@ private void checkOpen() {
     @Override
     public synchronized void close() {
         if (!closed) {
+            // Closeable recommendation: mark as closed before any code that might throw.
             closed = true;
             store.unregisterTransaction(this);
 

objectbox-java/src/main/java/io/objectbox/internal/DebugCursor.java

@@ -51,6 +51,7 @@ public DebugCursor(Transaction tx, long handle) {
     @Override
     public synchronized void close() {
         if (!closed) {
+            // Closeable recommendation: mark as closed before any code that might throw.
             closed = true;
             // tx is null despite check in constructor in some tests (called by finalizer):
             // Null check avoids NPE in finalizer and seems to stabilize Android instrumentation perf tests.
@@ -60,6 +61,10 @@ public synchronized void close() {
         }
     }
 
+    /**
+     * Explicitly call {@link #close()} instead to avoid expensive finalization.
+     */
+    @SuppressWarnings("deprecation") // finalize()
     @Override
     protected void finalize() throws Throwable {
         if (!closed) {

objectbox-java/src/main/java/io/objectbox/query/Query.java

@@ -16,6 +16,7 @@
 
 package io.objectbox.query;
 
+import java.io.Closeable;
 import java.util.Collections;
 import java.util.Comparator;
 import java.util.Date;
@@ -45,7 +46,7 @@
  * @see QueryBuilder
  */
 @SuppressWarnings({"SameParameterValue", "UnusedReturnValue", "WeakerAccess"})
-public class Query<T> {
+public class Query<T> implements Closeable {
 
     native void nativeDestroy(long handle);
 
@@ -112,7 +113,7 @@ native void nativeSetParameter(long handle, int entityId, int propertyId, @Nulla
     }
 
     /**
-     * Explicitly call {@link #close()} instead.
+     * Explicitly call {@link #close()} instead to avoid expensive finalization.
      */
     @SuppressWarnings("deprecation") // finalize()
     @Override
@@ -126,8 +127,10 @@ protected void finalize() throws Throwable {
      */
     public synchronized void close() {
         if (handle != 0) {
-            nativeDestroy(handle);
+            // Closeable recommendation: mark as "closed" before nativeDestroy could throw.
+            long handleCopy = handle;
             handle = 0;
+            nativeDestroy(handleCopy);
         }
     }
 

objectbox-java/src/main/java/io/objectbox/query/QueryBuilder.java

@@ -16,6 +16,7 @@
 
 package io.objectbox.query;
 
+import java.io.Closeable;
 import java.util.ArrayList;
 import java.util.Comparator;
 import java.util.Date;
@@ -46,7 +47,7 @@
  */
 @SuppressWarnings({"WeakerAccess", "UnusedReturnValue", "unused"})
 @Experimental
-public class QueryBuilder<T> {
+public class QueryBuilder<T> implements Closeable {
 
     public enum StringOrder {
         /** The default: case insensitive ASCII characters */
@@ -191,7 +192,7 @@ private QueryBuilder(long storeHandle, long subQueryBuilderHandle) {
     }
 
     /**
-     * Explicitly call {@link #close()} instead.
+     * Explicitly call {@link #close()} instead to avoid expensive finalization.
      */
     @SuppressWarnings("deprecation") // finalize()
     @Override
@@ -202,10 +203,12 @@ protected void finalize() throws Throwable {
 
     public synchronized void close() {
         if (handle != 0) {
+            // Closeable recommendation: mark as "closed" before nativeDestroy could throw.
+            long handleCopy = handle;
+            handle = 0;
             if (!isSubQuery) {
-                nativeDestroy(handle);
+                nativeDestroy(handleCopy);
             }
-            handle = 0;
         }
     }