Query: add findFirstId and findUniqueId (#149)

Author: greenrobot-team

objectbox-java/src/main/java/io/objectbox/exception/NonUniqueResultException.java

@@ -16,7 +16,11 @@
 
 package io.objectbox.exception;
 
-/** Throw if {@link io.objectbox.query.Query#findUnique()} returns more than one result. */
+/**
+ * Thrown if {@link io.objectbox.query.Query#findUnique() Query.findUnique()} or
+ * {@link io.objectbox.query.Query#findUniqueId() Query.findUniqueId()} is called,
+ * but the query matches more than one object.
+ */
 public class NonUniqueResultException extends DbException {
     public NonUniqueResultException(String message) {
         super(message);

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

@@ -61,6 +61,10 @@ public class Query<T> implements Closeable {
 
     native List<T> nativeFind(long handle, long cursorHandle, long offset, long limit) throws Exception;
 
+    native long nativeFindFirstId(long handle, long cursorHandle);
+
+    native long nativeFindUniqueId(long handle, long cursorHandle);
+
     native long[] nativeFindIds(long handle, long cursorHandle, long offset, long limit);
 
     native long nativeCount(long handle, long cursorHandle);
@@ -191,9 +195,9 @@ private void ensureNoComparator() {
     }
 
     /**
-     * Find the unique Object matching the query.
-     *
-     * @throws io.objectbox.exception.NonUniqueResultException if result was not unique
+     * If there is a single matching object, returns it. If there is more than one matching object,
+     * throws {@link io.objectbox.exception.NonUniqueResultException NonUniqueResultException}.
+     * If there are no matches returns null.
      */
     @Nullable
     public T findUnique() {
@@ -244,6 +248,32 @@ public List<T> find(final long offset, final long limit) {
         });
     }
 
+    /**
+     * Returns the ID of the first matching object. If there are no results returns 0.
+     * <p>
+     * Like {@link #findFirst()}, but more efficient as no object is created.
+     * <p>
+     * Ignores any {@link QueryBuilder#filter(QueryFilter) query filter}.
+     */
+    public long findFirstId() {
+        checkOpen();
+        return box.internalCallWithReaderHandle(cursorHandle -> nativeFindFirstId(handle, cursorHandle));
+    }
+
+    /**
+     * If there is a single matching object, returns its ID. If there is more than one matching object,
+     * throws {@link io.objectbox.exception.NonUniqueResultException NonUniqueResultException}.
+     * If there are no matches returns 0.
+     * <p>
+     * Like {@link #findUnique()}, but more efficient as no object is created.
+     * <p>
+     * Ignores any {@link QueryBuilder#filter(QueryFilter) query filter}.
+     */
+    public long findUniqueId() {
+        checkOpen();
+        return box.internalCallWithReaderHandle(cursorHandle -> nativeFindUniqueId(handle, cursorHandle));
+    }
+
     /**
      * Very efficient way to get just the IDs without creating any objects. IDs can later be used to lookup objects
      * (lookups by ID are also very efficient in ObjectBox).

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

@@ -104,14 +104,16 @@ public void useAfterQueryClose_fails() {
         assertThrowsQueryIsClosed(query::count);
         assertThrowsQueryIsClosed(query::describe);
         assertThrowsQueryIsClosed(query::describeParameters);
+        assertThrowsQueryIsClosed(query::findFirst);
+        assertThrowsQueryIsClosed(query::findUnique);
         assertThrowsQueryIsClosed(query::find);
         assertThrowsQueryIsClosed(() -> query.find(0, 1));
-        assertThrowsQueryIsClosed(query::findFirst);
+        assertThrowsQueryIsClosed(query::findFirstId);
+        assertThrowsQueryIsClosed(query::findUniqueId);
         assertThrowsQueryIsClosed(query::findIds);
         assertThrowsQueryIsClosed(() -> query.findIds(0, 1));
         assertThrowsQueryIsClosed(query::findLazy);
         assertThrowsQueryIsClosed(query::findLazyCached);
-        assertThrowsQueryIsClosed(query::findUnique);
         assertThrowsQueryIsClosed(query::remove);
 
         // For setParameter(s) the native method is not actually called, so fine to use incorrect alias and property.
@@ -162,14 +164,16 @@ public void useAfterStoreClose_failsIfUsingStore() {
 
         // All methods accessing the store throw.
         assertThrowsStoreIsClosed(query::count);
+        assertThrowsStoreIsClosed(query::findFirst);
+        assertThrowsStoreIsClosed(query::findUnique);
         assertThrowsStoreIsClosed(query::find);
         assertThrowsStoreIsClosed(() -> query.find(0, 1));
-        assertThrowsStoreIsClosed(query::findFirst);
+        assertThrowsStoreIsClosed(query::findFirstId);
+        assertThrowsStoreIsClosed(query::findUniqueId);
         assertThrowsStoreIsClosed(query::findIds);
         assertThrowsStoreIsClosed(() -> query.findIds(0, 1));
         assertThrowsStoreIsClosed(query::findLazy);
         assertThrowsStoreIsClosed(query::findLazyCached);
-        assertThrowsStoreIsClosed(query::findUnique);
         assertThrowsStoreIsClosed(query::remove);
         assertThrowsStoreIsClosed(() -> query.subscribe().observer(data -> {
         }));
@@ -915,6 +919,35 @@ public void testRemove() {
         assertEquals(4, box.count());
     }
 
+    @Test
+    public void findFirstId() {
+        putTestEntitiesScalars();
+        try (Query<TestEntity> query = box.query(simpleInt.greater(2006)).build()) {
+            assertEquals(8, query.findFirstId());
+        }
+        // No result.
+        try (Query<TestEntity> query = box.query(simpleInt.equal(-1)).build()) {
+            assertEquals(0, query.findFirstId());
+        }
+    }
+
+    @Test
+    public void findUniqueId() {
+        putTestEntitiesScalars();
+        try (Query<TestEntity> query = box.query(simpleInt.equal(2006)).build()) {
+            assertEquals(7, query.findUniqueId());
+        }
+        // No result.
+        try (Query<TestEntity> query = box.query(simpleInt.equal(-1)).build()) {
+            assertEquals(0, query.findUniqueId());
+        }
+        // More than one result.
+        try (Query<TestEntity> query = box.query(simpleInt.greater(2006)).build()) {
+            NonUniqueResultException e = assertThrows(NonUniqueResultException.class, query::findUniqueId);
+            assertEquals("Query does not have a unique result (more than one result): 3", e.getMessage());
+        }
+    }
+
     @Test
     public void testFindIds() {
         putTestEntitiesScalars();