Merge branch '149-new-jni-apis' into dev

Author: greenrobot-team

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

@@ -77,6 +77,8 @@ public class BoxStoreBuilder {
     /** Defaults to {@link #DEFAULT_MAX_DB_SIZE_KBYTE}. */
     long maxSizeInKByte = DEFAULT_MAX_DB_SIZE_KBYTE;
 
+    long maxDataSizeInKByte;
+
     /** On Android used for native library loading. */
     @Nullable Object context;
     @Nullable Object relinker;
@@ -339,10 +341,34 @@ BoxStoreBuilder modelUpdate(ModelUpdate modelUpdate) {
      * (for example you insert data in an infinite loop).
      */
     public BoxStoreBuilder maxSizeInKByte(long maxSizeInKByte) {
+        if (maxSizeInKByte <= maxDataSizeInKByte) {
+            throw new IllegalArgumentException("maxSizeInKByte must be larger than maxDataSizeInKByte.");
+        }
         this.maxSizeInKByte = maxSizeInKByte;
         return this;
     }
 
+    /**
+     * This API is experimental and may change or be removed in future releases.
+     * <p>
+     * Sets the maximum size the data stored in the database can grow to. Must be below {@link #maxSizeInKByte(long)}.
+     * <p>
+     * Different from {@link #maxSizeInKByte(long)} this only counts bytes stored in objects, excluding system and
+     * metadata. However, it is more involved than database size tracking, e.g. it stores an internal counter.
+     * Only use this if a stricter, more accurate limit is required.
+     * <p>
+     * When the data limit is reached data can be removed to get below the limit again (assuming the database size limit
+     * is not also reached).
+     */
+    @Experimental
+    public BoxStoreBuilder maxDataSizeInKByte(long maxDataSizeInKByte) {
+        if (maxDataSizeInKByte >= maxSizeInKByte) {
+            throw new IllegalArgumentException("maxDataSizeInKByte must be smaller than maxSizeInKByte.");
+        }
+        this.maxDataSizeInKByte = maxDataSizeInKByte;
+        return this;
+    }
+
     /**
      * Open the store in read-only mode: no schema update, no write transactions are allowed (would throw).
      */
@@ -491,13 +517,12 @@ byte[] buildFlatStoreOptions(String canonicalPath) {
                 FlatStoreOptions.addValidateOnOpenPageLimit(fbb, validateOnOpenPageLimit);
             }
         }
-        if(skipReadSchema) FlatStoreOptions.addSkipReadSchema(fbb, skipReadSchema);
-        if(usePreviousCommit) FlatStoreOptions.addUsePreviousCommit(fbb, usePreviousCommit);
-        if(readOnly) FlatStoreOptions.addReadOnly(fbb, readOnly);
-        if(noReaderThreadLocals) FlatStoreOptions.addNoReaderThreadLocals(fbb, noReaderThreadLocals);
-        if (debugFlags != 0) {
-            FlatStoreOptions.addDebugFlags(fbb, debugFlags);
-        }
+        if (skipReadSchema) FlatStoreOptions.addSkipReadSchema(fbb, true);
+        if (usePreviousCommit) FlatStoreOptions.addUsePreviousCommit(fbb, true);
+        if (readOnly) FlatStoreOptions.addReadOnly(fbb, true);
+        if (noReaderThreadLocals) FlatStoreOptions.addNoReaderThreadLocals(fbb, true);
+        if (debugFlags != 0) FlatStoreOptions.addDebugFlags(fbb, debugFlags);
+        if (maxDataSizeInKByte > 0) FlatStoreOptions.addMaxDataSizeInKbyte(fbb, maxDataSizeInKByte);
 
         int offset = FlatStoreOptions.endFlatStoreOptions(fbb);
         fbb.finish(offset);

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

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2022 ObjectBox Ltd. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.objectbox.exception;
+
+/**
+ * Thrown when applying a transaction would exceed the {@link io.objectbox.BoxStoreBuilder#maxDataSizeInKByte(long) maxDataSizeInKByte}
+ * configured for the store.
+ */
+public class DbMaxDataSizeExceededException extends DbException {
+    public DbMaxDataSizeExceededException(String message) {
+        super(message);
+    }
+}

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/BoxStoreBuilderTest.java

@@ -16,6 +16,8 @@
 
 package io.objectbox;
 
+import io.objectbox.exception.DbFullException;
+import io.objectbox.exception.DbMaxDataSizeExceededException;
 import io.objectbox.exception.PagesCorruptException;
 import io.objectbox.model.ValidateOnOpenMode;
 import org.greenrobot.essentials.io.IoUtils;
@@ -28,7 +30,6 @@
 import java.io.InputStream;
 import java.nio.file.Files;
 import java.nio.file.Path;
-import java.util.Collections;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
@@ -38,13 +39,16 @@
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
 import static org.junit.Assert.assertTrue;
 import static org.junit.Assert.fail;
 
 public class BoxStoreBuilderTest extends AbstractObjectBoxTest {
 
     private BoxStoreBuilder builder;
 
+    private static final String LONG_STRING = "Lorem ipsum dolor sit amet, consectetur adipiscing elit.";
+
     @Override
     protected BoxStore createBoxStore() {
         // Standard setup of store not required
@@ -167,6 +171,73 @@ public void readOnly() {
         assertTrue(store.isReadOnly());
     }
 
+    @Test
+    public void maxSize_invalidValues_throw() {
+        // Max data larger than max database size throws.
+        builder.maxSizeInKByte(10);
+        IllegalArgumentException exSmaller = assertThrows(
+                IllegalArgumentException.class,
+                () -> builder.maxDataSizeInKByte(11)
+        );
+        assertEquals("maxDataSizeInKByte must be smaller than maxSizeInKByte.", exSmaller.getMessage());
+
+        // Max database size smaller than max data size throws.
+        builder.maxDataSizeInKByte(9);
+        IllegalArgumentException exLarger = assertThrows(
+                IllegalArgumentException.class,
+                () -> builder.maxSizeInKByte(8)
+        );
+        assertEquals("maxSizeInKByte must be larger than maxDataSizeInKByte.", exLarger.getMessage());
+    }
+
+    @Test
+    public void maxFileSize() {
+        builder = createBoxStoreBuilder(null);
+        builder.maxSizeInKByte(30); // Empty file is around 12 KB, object below adds about 8 KB each.
+        store = builder.build();
+        putTestEntity(LONG_STRING, 1);
+        TestEntity testEntity2 = createTestEntity(LONG_STRING, 2);
+        DbFullException dbFullException = assertThrows(
+                DbFullException.class,
+                () -> getTestEntityBox().put(testEntity2)
+        );
+        assertEquals("Could not commit tx", dbFullException.getMessage());
+
+        // Re-open with larger size.
+        store.close();
+        builder.maxSizeInKByte(40);
+        store = builder.build();
+        testEntity2.setId(0); // Clear ID of object that failed to put.
+        getTestEntityBox().put(testEntity2);
+    }
+
+    @Test
+    public void maxDataSize() {
+        // Put until max data size is reached, but still below max database size.
+        builder = createBoxStoreBuilder(null);
+        builder.maxSizeInKByte(50); // Empty file is around 12 KB, each put adds about 8 KB.
+        builder.maxDataSizeInKByte(1);
+        store = builder.build();
+
+        TestEntity testEntity1 = putTestEntity(LONG_STRING, 1);
+        TestEntity testEntity2 = createTestEntity(LONG_STRING, 2);
+        DbMaxDataSizeExceededException maxDataExc = assertThrows(
+                DbMaxDataSizeExceededException.class,
+                () -> getTestEntityBox().put(testEntity2)
+        );
+        assertEquals("Exceeded user-set maximum by [bytes]: 64", maxDataExc.getMessage());
+
+        // Remove to get below max data size, then put again.
+        getTestEntityBox().remove(testEntity1);
+        getTestEntityBox().put(testEntity2);
+
+        // Alternatively, re-open with larger max data size.
+        store.close();
+        builder.maxDataSizeInKByte(2);
+        store = builder.build();
+        putTestEntity(LONG_STRING, 3);
+    }
+
     @Test
     public void validateOnOpen() {
         // Create a database first; we must create the model only once (ID/UID sequences would be different 2nd time)

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();