Merge branch '34-query-cloning' into 'dev'

Support cloning queries

Closes #34

See merge request objectbox/objectbox-java!41

Author: greenrobot-team

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

@@ -55,6 +55,9 @@ public class Query<T> implements Closeable {
 
     native void nativeDestroy(long handle);
 
+    /** Clones the native query, incl. conditions and parameters, and returns a handle to the clone. */
+    native long nativeClone(long handle);
+
     native Object nativeFindFirst(long handle, long cursorHandle);
 
     native Object nativeFindUnique(long handle, long cursorHandle);
@@ -129,6 +132,20 @@ native void nativeSetParameter(long handle, int entityId, int propertyId, @Nulla
         this.comparator = comparator;
     }
 
+    /**
+     * Creates a copy of the {@code originalQuery}, but pointing to a different native query using {@code handle}.
+     */
+    // Note: not using recommended copy constructor (just passing this) as handle needs to change.
+    private Query(Query<T> originalQuery, long handle) {
+        this(
+                originalQuery.box,
+                handle,
+                originalQuery.eagerRelations,
+                originalQuery.filter,
+                originalQuery.comparator
+        );
+    }
+
     /**
      * Explicitly call {@link #close()} instead to avoid expensive finalization.
      */
@@ -156,6 +173,22 @@ public synchronized void close() {
         }
     }
 
+    /**
+     * Creates a copy of this for use in another thread.
+     * <p>
+     * Clones the native query, keeping any previously set parameters.
+     * <p>
+     * Closing the original query does not close the copy. {@link #close()} the copy once finished using it.
+     * <p>
+     * Note: a set {@link QueryBuilder#filter(QueryFilter) filter} or {@link QueryBuilder#sort(Comparator) sort}
+     * order <b>must be thread safe</b>.
+     */
+    // Note: not overriding clone() to avoid confusion with Java's cloning mechanism.
+    public Query<T> copy() {
+        long cloneHandle = nativeClone(handle);
+        return new Query<>(this, cloneHandle);
+    }
+
     /** To be called inside a read TX */
     long cursorHandle() {
         return InternalAccess.getActiveTxCursorHandle(box);

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

@@ -0,0 +1,22 @@
+package io.objectbox.query;
+
+/**
+ * A {@link ThreadLocal} that, given an original {@link Query} object,
+ * returns a {@link Query#copy() copy}, for each thread.
+ */
+public class QueryThreadLocal<T> extends ThreadLocal<Query<T>> {
+
+    private final Query<T> original;
+
+    /**
+     * See {@link QueryThreadLocal}.
+     */
+    public QueryThreadLocal(Query<T> original) {
+        this.original = original;
+    }
+
+    @Override
+    protected Query<T> initialValue() {
+        return original.copy();
+    }
+}

tests/objectbox-java-test/src/test/java/io/objectbox/query/QueryCopyTest.java

@@ -0,0 +1,116 @@
+package io.objectbox.query;
+
+import io.objectbox.TestEntity;
+import io.objectbox.TestEntity_;
+import org.junit.Test;
+
+import java.util.Comparator;
+import java.util.List;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicReference;
+
+import static org.junit.Assert.*;
+
+public class QueryCopyTest extends AbstractQueryTest {
+
+    @Test
+    public void queryCopy_isClone() {
+        putTestEntity("orange", 1);
+        TestEntity banana = putTestEntity("banana", 2);
+        putTestEntity("apple", 3);
+        TestEntity bananaMilkShake = putTestEntity("banana milk shake", 4);
+        putTestEntity("pineapple", 5);
+        putTestEntity("papaya", 6);
+
+        // Only even nr: 2, 4, 6.
+        QueryFilter<TestEntity> filter = entity -> entity.getSimpleInt() % 2 == 0;
+        // Reverse insert order: 6, 4, 2.
+        Comparator<TestEntity> comparator = Comparator.comparingLong(testEntity -> -testEntity.getId());
+
+        Query<TestEntity> queryOriginal = box.query(TestEntity_.simpleString.contains("").alias("fruit"))
+                .filter(filter)
+                .sort(comparator)
+                .build();
+        // Only bananas: 4, 2.
+        queryOriginal.setParameter("fruit", banana.getSimpleString());
+
+        Query<TestEntity> queryCopy = queryOriginal.copy();
+
+        // Object instances and native query handle should differ.
+        assertNotEquals(queryOriginal, queryCopy);
+        assertNotEquals(queryOriginal.handle, queryCopy.handle);
+
+        // Verify results are identical.
+        List<TestEntity> resultsOriginal = queryOriginal.find();
+        queryOriginal.close();
+        List<TestEntity> resultsCopy = queryCopy.find();
+        queryCopy.close();
+        assertEquals(2, resultsOriginal.size());
+        assertEquals(2, resultsCopy.size());
+        assertTestEntityEquals(bananaMilkShake, resultsOriginal.get(0));
+        assertTestEntityEquals(bananaMilkShake, resultsCopy.get(0));
+        assertTestEntityEquals(banana, resultsOriginal.get(1));
+        assertTestEntityEquals(banana, resultsCopy.get(1));
+    }
+
+    @Test
+    public void queryCopy_setParameter_noEffectOriginal() {
+        TestEntity orange = putTestEntity("orange", 1);
+        TestEntity banana = putTestEntity("banana", 2);
+
+        Query<TestEntity> queryOriginal = box
+                .query(TestEntity_.simpleString.equal(orange.getSimpleString()).alias("fruit"))
+                .build();
+
+        // Set parameter on clone that changes result.
+        Query<TestEntity> queryCopy = queryOriginal.copy()
+                .setParameter("fruit", banana.getSimpleString());
+
+        List<TestEntity> resultsOriginal = queryOriginal.find();
+        queryOriginal.close();
+        assertEquals(1, resultsOriginal.size());
+        assertTestEntityEquals(orange, resultsOriginal.get(0));
+
+        List<TestEntity> resultsCopy = queryCopy.find();
+        queryCopy.close();
+        assertEquals(1, resultsCopy.size());
+        assertTestEntityEquals(banana, resultsCopy.get(0));
+    }
+
+    private void assertTestEntityEquals(TestEntity expected, TestEntity actual) {
+        assertEquals(expected.getId(), actual.getId());
+        assertEquals(expected.getSimpleString(), actual.getSimpleString());
+    }
+
+    @Test
+    public void queryThreadLocal() throws InterruptedException {
+        Query<TestEntity> queryOriginal = box.query().build();
+        QueryThreadLocal<TestEntity> threadLocal = new QueryThreadLocal<>(queryOriginal);
+
+        AtomicReference<Query<TestEntity>> queryThreadAtomic = new AtomicReference<>();
+        CountDownLatch latch = new CountDownLatch(1);
+        new Thread(() -> {
+            queryThreadAtomic.set(threadLocal.get());
+            latch.countDown();
+        }).start();
+
+        assertTrue(latch.await(1, TimeUnit.SECONDS));
+
+        Query<TestEntity> queryThread = queryThreadAtomic.get();
+        Query<TestEntity> queryMain = threadLocal.get();
+
+        // Assert that initialValue returns something.
+        assertNotNull(queryThread);
+        assertNotNull(queryMain);
+
+        // Assert that initialValue returns clones.
+        assertNotEquals(queryThread.handle, queryOriginal.handle);
+        assertNotEquals(queryMain.handle, queryOriginal.handle);
+        assertNotEquals(queryThread.handle, queryMain.handle);
+
+        queryOriginal.close();
+        queryMain.close();
+        queryThread.close();
+    }
+}