Add read-only, previous commit, validate on open options.

Author: greenrobot-team

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

@@ -151,10 +151,6 @@ public static String getVersionNative() {
      */
     static native long nativeCreateWithFlatOptions(byte[] options, byte[] model);
 
-    /**
-     * Returns whether the store was created using read-only mode.
-     * If true the schema is not updated and write transactions are not possible.
-     */
     static native boolean nativeIsReadOnly(long store);
 
     static native void nativeDelete(long store);
@@ -286,6 +282,8 @@ public static boolean isObjectBrowserAvailable() {
 
     private byte[] buildFlatStoreOptions(BoxStoreBuilder builder, String canonicalPath) {
         FlatBufferBuilder fbb = new FlatBufferBuilder();
+        // TODO Is forceDefaults required by JNI or not?
+        fbb.forceDefaults(true);
 
         // Add non-integer values first...
         int directoryPathOffset = fbb.createString(canonicalPath);
@@ -294,11 +292,19 @@ private byte[] buildFlatStoreOptions(BoxStoreBuilder builder, String canonicalPa
 
         // ...then build options.
         FlatStoreOptions.addDirectoryPath(fbb, directoryPathOffset);
-        // FlatStoreOptions.addModelBytes(fbb, modelBytesOffset); // TODO Use this instead of model param on JNI method?
         FlatStoreOptions.addMaxDbSizeInKByte(fbb, builder.maxSizeInKByte);
         FlatStoreOptions.addMaxReaders(fbb, builder.maxReaders);
         // FlatStoreOptions.addDebugFlags(fbb, builder.debugFlags); // TODO Use this instead of nativeSetDebugFlags?
         // TODO Add new values.
+        FlatStoreOptions.addReadOnly(fbb, builder.readOnly);
+        FlatStoreOptions.addUsePreviousCommit(fbb, builder.usePreviousCommit);
+        FlatStoreOptions.addUsePreviousCommitOnValidationFailure(fbb, builder.usePreviousCommitOnValidationFailure);
+        if (builder.validateOnOpenMode != 0) {
+            FlatStoreOptions.addValidateOnOpen(fbb, builder.validateOnOpenMode);
+            if (builder.validateOnOpenPageLimit != 0) {
+                FlatStoreOptions.addValidateOnOpenPageLimit(fbb, builder.validateOnOpenPageLimit);
+            }
+        }
 
         int offset = FlatStoreOptions.endFlatStoreOptions(fbb);
         fbb.finish(offset);
@@ -483,6 +489,14 @@ public boolean isClosed() {
         return closed;
     }
 
+    /**
+     * Whether the store was created using read-only mode.
+     * If true the schema is not updated and write transactions are not possible.
+     */
+    public boolean isReadOnly() {
+        return nativeIsReadOnly(handle);
+    }
+
     /**
      * Closes the BoxStore and frees associated resources.
      * This method is useful for unit tests;

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

@@ -37,6 +37,7 @@
 import io.objectbox.annotation.apihint.Internal;
 import io.objectbox.exception.DbException;
 import io.objectbox.ideasonly.ModelUpdate;
+import io.objectbox.model.ValidateOnOpenMode;
 
 /**
  * Builds a {@link BoxStore} with optional configurations. The class is not initiated directly; use
@@ -91,6 +92,13 @@ public class BoxStoreBuilder {
 
     int queryAttempts;
 
+    boolean readOnly;
+    boolean usePreviousCommit;
+    boolean usePreviousCommitOnValidationFailure;
+
+    int validateOnOpenMode;
+    long validateOnOpenPageLimit;
+
     TxCallback<?> failedReadTxAttemptCallback;
 
     final List<EntityInfo<?>> entityInfoList = new ArrayList<>();
@@ -299,6 +307,85 @@ public BoxStoreBuilder maxSizeInKByte(long maxSizeInKByte) {
         return this;
     }
 
+    /**
+     * Open the store in read-only mode: no schema update, no write transactions.
+     * <p>
+     * It is recommended to use this with {@link #usePreviousCommit()} to ensure no data is lost.
+     */
+    public BoxStoreBuilder readOnly() {
+        this.readOnly = true;
+        return this;
+    }
+
+    /**
+     * Ignores the latest data snapshot (committed transaction state) and uses the previous snapshot instead.
+     * When used with care (e.g. backup the DB files first), this option may also recover data removed by the latest
+     * transaction.
+     * <p>
+     * It is recommended to use this with {@link #readOnly()} to ensure no data is lost.
+     */
+    public BoxStoreBuilder usePreviousCommit() {
+        if (usePreviousCommitOnValidationFailure) {
+            throw new IllegalStateException("Can not use together with usePreviousCommitOnValidationFailure()");
+        }
+        this.usePreviousCommit = true;
+        return this;
+    }
+
+    /**
+     * If consistency checks fail during opening the DB, ObjectBox
+     * automatically switches to the previous commit. This way, this constitutes
+     * an auto-recover mode from severe failures.
+     * <p>
+     * However, keep in mind that any consistency failure
+     * is an indication that something is very wrong with OS/hardware and thus you may possibly alert your users.
+     *
+     * @see #usePreviousCommit()
+     * @see #validateOnOpen(int)
+     */
+    public BoxStoreBuilder usePreviousCommitOnValidationFailure() {
+        if (usePreviousCommit) {
+            throw new IllegalStateException("Can not use together with usePreviousCommit()");
+        }
+        this.usePreviousCommitOnValidationFailure = true;
+        return this;
+    }
+
+    /**
+     * When a database is opened, ObjectBox can perform additional consistency checks on its database structure.
+     * Reliable file systems already guarantee consistency, so this is primarily meant to deal with unreliable
+     * OSes, file systems, or hardware.
+     * <p>
+     * Note: ObjectBox builds upon ACID storage, which already has strong consistency mechanisms in place.
+     *
+     * @param validateOnOpenMode One of {@link ValidateOnOpenMode}.
+     */
+    public BoxStoreBuilder validateOnOpen(int validateOnOpenMode) {
+        if (validateOnOpenMode < ValidateOnOpenMode.None || validateOnOpenMode > ValidateOnOpenMode.Full) {
+            throw new IllegalArgumentException("Must be one of ValidateOnOpenMode");
+        }
+        this.validateOnOpenMode = validateOnOpenMode;
+        return this;
+    }
+
+    /**
+     * To fine-tune {@link #validateOnOpen(int)}, you can specify a limit on how much data is looked at.
+     * This is measured in "pages" with a page typically holding 4000.
+     * Usually a low number (e.g. 1-20) is sufficient and does not impact startup performance significantly.
+     * <p>
+     * This can only be used with {@link ValidateOnOpenMode#Regular} and {@link ValidateOnOpenMode#WithLeaves}.
+     */
+    public BoxStoreBuilder validateOnOpenPageLimit(long limit) {
+        if (validateOnOpenMode != ValidateOnOpenMode.Regular && validateOnOpenMode != ValidateOnOpenMode.WithLeaves) {
+            throw new IllegalStateException("Must call validateOnOpen(mode) with mode Regular or WithLeaves first");
+        }
+        if (limit < 1) {
+            throw new IllegalArgumentException("limit must be positive");
+        }
+        this.validateOnOpenPageLimit = limit;
+        return this;
+    }
+
     /**
      * @deprecated Use {@link #debugFlags} instead.
      */

tests/objectbox-java-test/src/test/java/io/objectbox/BoxStoreBuilderTest.java

@@ -19,12 +19,9 @@
 import org.junit.Before;
 import org.junit.Test;
 
-import io.objectbox.exception.DbMaxReadersExceededException;
 
-
-import static org.junit.Assert.assertEquals;
-import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
 import static org.junit.Assert.fail;
 
 public class BoxStoreBuilderTest extends AbstractObjectBoxTest {
@@ -107,4 +104,18 @@ public void testMaxReaders() {
 //        assertEquals(DbMaxReadersExceededException.class, exHolder[0].getClass());
     }
 
+    @Test
+    public void readOnly() {
+        // Create a database first.
+        builder = createBoxStoreBuilder(false);
+        store = builder.build();
+        store.close();
+
+        // Then open existing database as read-only.
+        builder = createBoxStoreBuilder(false);
+        builder.readOnly();
+        store = builder.build();
+
+        assertTrue(store.isReadOnly());
+    }
 }