Merge branch '69-switch-boxstorebuilder-to-flatstoreoptions' into dev

# Conflicts:
#	tests/objectbox-java-test/src/test/java/io/objectbox/BoxStoreTest.java

Author: greenrobot

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2019 ObjectBox Ltd. All rights reserved.
+ * Copyright 2017-2020 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.
@@ -66,7 +66,7 @@ public class BoxStore implements Closeable {
     /** Change so ReLinker will update native library when using workaround loading. */
     public static final String JNI_VERSION = "2.6.0";
 
-    private static final String VERSION = "2.6.1-2020-06-09";
+    private static final String VERSION = "2.7.0-2020-07-30";
     private static BoxStore defaultStore;
 
     /** Currently used DB dirs with values from {@link #getCanonicalPath(File)}. */
@@ -136,7 +136,13 @@ public static String getVersionNative() {
      */
     public static native void testUnalignedMemoryAccess();
 
-    static native long nativeCreate(String directory, long maxDbSizeInKByte, int maxReaders, byte[] model);
+    /**
+     * Creates a native BoxStore instance with FlatBuffer {@link io.objectbox.model.FlatStoreOptions} {@code options}
+     * and a {@link ModelBuilder} {@code model}. Returns the handle of the native store instance.
+     */
+    static native long nativeCreateWithFlatOptions(byte[] options, byte[] model);
+
+    static native boolean nativeIsReadOnly(long store);
 
     static native void nativeDelete(long store);
 
@@ -166,6 +172,10 @@ static native void nativeRegisterCustomType(long store, int entityId, int proper
 
     static native boolean nativeIsObjectBrowserAvailable();
 
+    native long nativeSizeOnDisk(long store);
+
+    native long nativeValidate(long store, long pageLimit, boolean checkLeafLevel);
+
     public static boolean isObjectBrowserAvailable() {
         NativeLibraryLoader.ensureLoaded();
         return nativeIsObjectBrowserAvailable();
@@ -214,10 +224,9 @@ public static boolean isObjectBrowserAvailable() {
         canonicalPath = getCanonicalPath(directory);
         verifyNotAlreadyOpen(canonicalPath);
 
-        handle = nativeCreate(canonicalPath, builder.maxSizeInKByte, builder.maxReaders, builder.model);
+        handle = nativeCreateWithFlatOptions(builder.buildFlatStoreOptions(canonicalPath), builder.model);
         int debugFlags = builder.debugFlags;
         if (debugFlags != 0) {
-            nativeSetDebugFlags(handle, debugFlags);
             debugTxRead = (debugFlags & DebugFlags.LOG_TRANSACTIONS_READ) != 0;
             debugTxWrite = (debugFlags & DebugFlags.LOG_TRANSACTIONS_WRITE) != 0;
         } else {
@@ -446,6 +455,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;
@@ -900,6 +917,19 @@ public String diagnose() {
         return nativeDiagnose(handle);
     }
 
+    /**
+     * Validates up to {@code pageLimit} pages of the store. Set {@code checkLeafLevel} to check leafs, too.
+     * Returns the number of pages validated.
+     * Throws StorageException if validation fails.
+     * Throws DbFileCorruptException or DbPagesCorruptException if the DB is actually inconsistent (corrupt).
+     */
+    public long validate(long pageLimit, boolean checkLeafLevel) {
+        if (pageLimit < 0) {
+            throw new IllegalArgumentException("pageLimit must be zero or positive");
+        }
+        return nativeValidate(handle, pageLimit, checkLeafLevel);
+    }
+
     public int cleanStaleReadTransactions() {
         return nativeCleanStaleReadTransactions(handle);
     }

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

@@ -16,6 +16,8 @@
 
 package io.objectbox;
 
+import com.google.flatbuffers.FlatBufferBuilder;
+import io.objectbox.model.FlatStoreOptions;
 import org.greenrobot.essentials.io.IoUtils;
 
 import java.io.BufferedInputStream;
@@ -37,6 +39,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
@@ -87,18 +90,32 @@ public class BoxStoreBuilder {
 
     boolean debugRelations;
 
+    long fileMode;
+
     int maxReaders;
 
     int queryAttempts;
 
+    /** For DebugCursor. */
+    boolean skipReadSchema;
+
+    boolean readOnly;
+    boolean usePreviousCommit;
+
+    short validateOnOpenMode;
+    long validateOnOpenPageLimit;
+
     TxCallback<?> failedReadTxAttemptCallback;
 
     final List<EntityInfo<?>> entityInfoList = new ArrayList<>();
     private Factory<InputStream> initialDbFileFactory;
 
-    /** Not for application use. */
+    /** Not for application use, for DebugCursor. */
+    @Internal
     public static BoxStoreBuilder createDebugWithoutModel() {
-        return new BoxStoreBuilder();
+        BoxStoreBuilder builder = new BoxStoreBuilder();
+        builder.skipReadSchema = true;
+        return builder;
     }
 
     private BoxStoreBuilder() {
@@ -259,6 +276,17 @@ private static File getAndroidFilesDir(Object context) {
         return filesDir;
     }
 
+    /**
+     * Specify
+     * <a href="https://en.wikipedia.org/wiki/File_system_permissions#Numeric_notation">unix-style file permissions</a>
+     * to use for the database directory and files.
+     * E.g. for {@code rw-rw-rw-} (owner, group, other) pass the octal code {@code 666}.
+     */
+    public BoxStoreBuilder fileMode(long mode) {
+        this.fileMode = mode;
+        return this;
+    }
+
     /**
      * Sets the maximum number of concurrent readers. For most applications, the default is fine (&gt; 100 readers).
      * <p>
@@ -269,7 +297,6 @@ private static File getAndroidFilesDir(Object context) {
      * For highly concurrent setups (e.g. you are using ObjectBox on the server side) it may make sense to increase the
      * number.
      */
-
     public BoxStoreBuilder maxReaders(int maxReaders) {
         this.maxReaders = maxReaders;
         return this;
@@ -299,6 +326,63 @@ 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() {
+        this.usePreviousCommit = 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(short 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(short)}, 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.
      */
@@ -370,6 +454,39 @@ public BoxStoreBuilder initialDbFile(Factory<InputStream> initialDbFileFactory)
         return this;
     }
 
+    byte[] buildFlatStoreOptions(String canonicalPath) {
+        FlatBufferBuilder fbb = new FlatBufferBuilder();
+        // FlatBuffer default values are set in generated code, e.g. may be different from here, so always store value.
+        fbb.forceDefaults(true);
+
+        // Add non-integer values first...
+        int directoryPathOffset = fbb.createString(canonicalPath);
+
+        FlatStoreOptions.startFlatStoreOptions(fbb);
+
+        // ...then build options.
+        FlatStoreOptions.addDirectoryPath(fbb, directoryPathOffset);
+        FlatStoreOptions.addMaxDbSizeInKByte(fbb, maxSizeInKByte);
+        FlatStoreOptions.addFileMode(fbb, fileMode);
+        FlatStoreOptions.addMaxReaders(fbb, maxReaders);
+        if (validateOnOpenMode != 0) {
+            FlatStoreOptions.addValidateOnOpen(fbb, validateOnOpenMode);
+            if (validateOnOpenPageLimit != 0) {
+                FlatStoreOptions.addValidateOnOpenPageLimit(fbb, validateOnOpenPageLimit);
+            }
+        }
+        if(skipReadSchema) FlatStoreOptions.addSkipReadSchema(fbb, skipReadSchema);
+        if(usePreviousCommit) FlatStoreOptions.addUsePreviousCommit(fbb, usePreviousCommit);
+        if(readOnly) FlatStoreOptions.addReadOnly(fbb, readOnly);
+        if (debugFlags != 0) {
+            FlatStoreOptions.addDebugFlags(fbb, debugFlags);
+        }
+
+        int offset = FlatStoreOptions.endFlatStoreOptions(fbb);
+        fbb.finish(offset);
+        return fbb.sizedByteArray();
+    }    
+
     /**
      * Builds a {@link BoxStore} using any given configuration.
      */

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

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2020 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;
+
+/** Errors were detected in a file, e.g. illegal values or structural inconsistencies. */
+public class FileCorruptException extends DbException {
+    public FileCorruptException(String message) {
+        super(message);
+    }
+
+    public FileCorruptException(String message, int errorCode) {
+        super(message, errorCode);
+    }
+}