Merge branch '190-config-package' into 'dev'

Create config package for FlatBuffers-generated config types #190

See merge request objectbox/objectbox-java!125

Author: greenrobot-team

objectbox-java/spotbugs-exclude.xml

@@ -5,6 +5,9 @@
     <Match>
         <Class name="io.objectbox.DebugFlags" />
     </Match>
+    <Match>
+        <Package name="io.objectbox.config" />
+    </Match>
     <Match>
         <Package name="io.objectbox.model" />
     </Match>

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2021 ObjectBox Ltd. All rights reserved.
+ * Copyright 2017-2023 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.
@@ -42,6 +42,8 @@
 import io.objectbox.annotation.apihint.Beta;
 import io.objectbox.annotation.apihint.Experimental;
 import io.objectbox.annotation.apihint.Internal;
+import io.objectbox.config.DebugFlags;
+import io.objectbox.config.FlatStoreOptions;
 import io.objectbox.converter.PropertyConverter;
 import io.objectbox.exception.DbException;
 import io.objectbox.exception.DbExceptionListener;
@@ -136,7 +138,7 @@ public static String getVersionNative() {
     }
 
     /**
-     * Creates a native BoxStore instance with FlatBuffer {@link io.objectbox.model.FlatStoreOptions} {@code options}
+     * Creates a native BoxStore instance with FlatBuffer {@link 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);

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017 ObjectBox Ltd. All rights reserved.
+ * Copyright 2017-2023 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.
@@ -33,15 +33,16 @@
 
 import io.objectbox.annotation.apihint.Experimental;
 import io.objectbox.annotation.apihint.Internal;
+import io.objectbox.config.DebugFlags;
+import io.objectbox.config.FlatStoreOptions;
+import io.objectbox.config.ValidateOnOpenModeKv;
+import io.objectbox.config.ValidateOnOpenModePages;
 import io.objectbox.exception.DbException;
 import io.objectbox.exception.DbFullException;
 import io.objectbox.exception.DbMaxDataSizeExceededException;
 import io.objectbox.exception.DbMaxReadersExceededException;
 import io.objectbox.flatbuffers.FlatBufferBuilder;
 import io.objectbox.ideasonly.ModelUpdate;
-import io.objectbox.model.FlatStoreOptions;
-import io.objectbox.model.ValidateOnOpenMode;
-import io.objectbox.model.ValidateOnOpenModeKv;
 import org.greenrobot.essentials.io.IoUtils;
 
 /**
@@ -413,13 +414,14 @@ public BoxStoreBuilder usePreviousCommit() {
      * See also {@link #validateOnOpenPageLimit(long)} to fine-tune this check and {@link #validateOnOpenKv(short)} for
      * additional checks.
      *
-     * @param validateOnOpenMode One of {@link ValidateOnOpenMode}.
+     * @param validateOnOpenModePages One of {@link ValidateOnOpenModePages}.
      */
-    public BoxStoreBuilder validateOnOpen(short validateOnOpenMode) {
-        if (validateOnOpenMode < ValidateOnOpenMode.None || validateOnOpenMode > ValidateOnOpenMode.Full) {
-            throw new IllegalArgumentException("Must be one of ValidateOnOpenMode");
+    public BoxStoreBuilder validateOnOpen(short validateOnOpenModePages) {
+        if (validateOnOpenModePages < ValidateOnOpenModePages.None
+                || validateOnOpenModePages > ValidateOnOpenModePages.Full) {
+            throw new IllegalArgumentException("Must be one of ValidateOnOpenModePages");
         }
-        this.validateOnOpenModePages = validateOnOpenMode;
+        this.validateOnOpenModePages = validateOnOpenModePages;
         return this;
     }
 
@@ -428,10 +430,12 @@ public BoxStoreBuilder validateOnOpen(short validateOnOpenMode) {
      * 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}.
+     * This can only be used with {@link ValidateOnOpenModePages#Regular} and
+     * {@link ValidateOnOpenModePages#WithLeaves}.
      */
     public BoxStoreBuilder validateOnOpenPageLimit(long limit) {
-        if (validateOnOpenModePages != ValidateOnOpenMode.Regular && validateOnOpenModePages != ValidateOnOpenMode.WithLeaves) {
+        if (validateOnOpenModePages != ValidateOnOpenModePages.Regular &&
+                validateOnOpenModePages != ValidateOnOpenModePages.WithLeaves) {
             throw new IllegalStateException("Must call validateOnOpen(mode) with mode Regular or WithLeaves first");
         }
         if (limit < 1) {

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

@@ -21,8 +21,11 @@
 /**
  * Debug flags typically enable additional "debug logging" that can be helpful to better understand what is going on
  * internally. These are intended for the development process only; typically one does not enable them for releases.
+ *
+ * @deprecated DebugFlags moved to config package: use {@link io.objectbox.config.DebugFlags} instead.
  */
 @SuppressWarnings("unused")
+@Deprecated
 public final class DebugFlags {
   private DebugFlags() { }
   public static final int LOG_TRANSACTIONS_READ = 1;

objectbox-java/src/main/java/io/objectbox/config/DebugFlags.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2023 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.
+ */
+
+// automatically generated by the FlatBuffers compiler, do not modify
+
+package io.objectbox.config;
+
+/**
+ * Debug flags typically enable additional "debug logging" that can be helpful to better understand what is going on
+ * internally. These are intended for the development process only; typically one does not enable them for releases.
+ */
+@SuppressWarnings("unused")
+public final class DebugFlags {
+  private DebugFlags() { }
+  public static final int LOG_TRANSACTIONS_READ = 1;
+  public static final int LOG_TRANSACTIONS_WRITE = 2;
+  public static final int LOG_QUERIES = 4;
+  public static final int LOG_QUERY_PARAMETERS = 8;
+  public static final int LOG_ASYNC_QUEUE = 16;
+  public static final int LOG_CACHE_HITS = 32;
+  public static final int LOG_CACHE_ALL = 64;
+  public static final int LOG_TREE = 128;
+  /**
+   * For a limited number of error conditions, this will try to print stack traces.
+   * Note: this is Linux-only, experimental, and has several limitations:
+   * The usefulness of these stack traces depends on several factors and might not be helpful at all.
+   */
+  public static final int LOG_EXCEPTION_STACK_TRACE = 256;
+  /**
+   * Run a quick self-test to verify basic threading; somewhat paranoia to check the platform and the library setup.
+   */
+  public static final int RUN_THREADING_SELF_TEST = 512;
+}
+

objectbox-java/src/main/java/io/objectbox/model/FlatStoreOptions.java renamed to objectbox-java/src/main/java/io/objectbox/config/FlatStoreOptions.java

@@ -16,7 +16,7 @@
 
 // automatically generated by the FlatBuffers compiler, do not modify
 
-package io.objectbox.model;
+package io.objectbox.config;
 
 import io.objectbox.flatbuffers.BaseVector;
 import io.objectbox.flatbuffers.BooleanVector;

objectbox-java/src/main/java/io/objectbox/model/TreeOptionFlags.java renamed to objectbox-java/src/main/java/io/objectbox/config/TreeOptionFlags.java

@@ -16,7 +16,7 @@
 
 // automatically generated by the FlatBuffers compiler, do not modify
 
-package io.objectbox.model;
+package io.objectbox.config;
 
 /**
  * Options flags for trees.

objectbox-java/src/main/java/io/objectbox/model/ValidateOnOpenModeKv.java renamed to objectbox-java/src/main/java/io/objectbox/config/ValidateOnOpenModeKv.java

@@ -16,7 +16,7 @@
 
 // automatically generated by the FlatBuffers compiler, do not modify
 
-package io.objectbox.model;
+package io.objectbox.config;
 
 /**
  * Defines if and how the database is checked for valid key/value (KV) entries when opening it.

objectbox-java/src/main/java/io/objectbox/config/ValidateOnOpenModePages.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2023 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.
+ */
+
+// automatically generated by the FlatBuffers compiler, do not modify
+
+package io.objectbox.config;
+
+/**
+ * Defines if and how the database is checked for structural consistency (pages) when opening it.
+ */
+@SuppressWarnings("unused")
+public final class ValidateOnOpenModePages {
+  private ValidateOnOpenModePages() { }
+  /**
+   * Not a real type, just best practice (e.g. forward compatibility)
+   */
+  public static final short Unknown = 0;
+  /**
+   * No additional checks are performed. This is fine if your file system is reliable (which it typically should be).
+   */
+  public static final short None = 1;
+  /**
+   * Performs a limited number of checks on the most important database structures (e.g. "branch pages").
+   */
+  public static final short Regular = 2;
+  /**
+   * Performs a limited number of checks on database structures including "data leaves".
+   */
+  public static final short WithLeaves = 3;
+  /**
+   * Performs a unlimited number of checks on the most important database structures (e.g. "branch pages").
+   */
+  public static final short AllBranches = 4;
+  /**
+   * Performs a unlimited number of checks on database structures including "data leaves".
+   */
+  public static final short Full = 5;
+
+  public static final String[] names = { "Unknown", "None", "Regular", "WithLeaves", "AllBranches", "Full", };
+
+  public static String name(int e) { return names[e]; }
+}
+

objectbox-java/src/main/java/io/objectbox/model/ValidateOnOpenMode.java

@@ -20,7 +20,10 @@
 
 /**
  * Defines if and how the database is checked for structural consistency (pages) when opening it.
+ *
+ * @deprecated This class has moved to the config package, use {@link io.objectbox.config.ValidateOnOpenModePages} instead.
  */
+@Deprecated
 @SuppressWarnings("unused")
 public final class ValidateOnOpenMode {
   private ValidateOnOpenMode() { }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2018 ObjectBox Ltd. All rights reserved.
+ * Copyright 2017-2023 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.
@@ -19,6 +19,7 @@
 import io.objectbox.ModelBuilder.EntityBuilder;
 import io.objectbox.ModelBuilder.PropertyBuilder;
 import io.objectbox.annotation.IndexType;
+import io.objectbox.config.DebugFlags;
 import io.objectbox.model.PropertyFlags;
 import io.objectbox.model.PropertyType;
 import org.junit.After;

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

@@ -21,9 +21,9 @@
 import java.io.IOException;
 import java.io.InputStream;
 
+import io.objectbox.config.ValidateOnOpenModePages;
 import io.objectbox.exception.FileCorruptException;
 import io.objectbox.exception.PagesCorruptException;
-import io.objectbox.model.ValidateOnOpenMode;
 import org.greenrobot.essentials.io.IoUtils;
 import org.junit.Before;
 import org.junit.Test;
@@ -62,7 +62,7 @@ public void validateOnOpen() {
         // Then re-open database with validation and ensure db is operational
         builder = new BoxStoreBuilder(model).directory(boxStoreDir);
         builder.entity(new TestEntity_());
-        builder.validateOnOpen(ValidateOnOpenMode.Full);
+        builder.validateOnOpen(ValidateOnOpenModePages.Full);
         store = builder.build();
         assertNotNull(getTestEntityBox().get(id));
         getTestEntityBox().put(new TestEntity(0));
@@ -75,7 +75,7 @@ public void validateOnOpenCorruptFile() throws IOException {
         prepareBadDataFile(dir, "corrupt-pageno-in-branch-data.mdb");
 
         builder = BoxStoreBuilder.createDebugWithoutModel().directory(dir);
-        builder.validateOnOpen(ValidateOnOpenMode.Full);
+        builder.validateOnOpen(ValidateOnOpenModePages.Full);
 
         @SuppressWarnings("resource")
         FileCorruptException ex = assertThrows(PagesCorruptException.class, () -> builder.build());
@@ -90,7 +90,7 @@ public void usePreviousCommitWithCorruptFile() throws IOException {
         File dir = prepareTempDir("object-store-test-corrupted");
         prepareBadDataFile(dir, "corrupt-pageno-in-branch-data.mdb");
         builder = BoxStoreBuilder.createDebugWithoutModel().directory(dir);
-        builder.validateOnOpen(ValidateOnOpenMode.Full).usePreviousCommit();
+        builder.validateOnOpen(ValidateOnOpenModePages.Full).usePreviousCommit();
         store = builder.build();
         String diagnoseString = store.diagnose();
         assertTrue(diagnoseString.contains("entries=2"));
@@ -104,7 +104,7 @@ public void usePreviousCommitAfterFileCorruptException() throws IOException {
         File dir = prepareTempDir("object-store-test-corrupted");
         prepareBadDataFile(dir, "corrupt-pageno-in-branch-data.mdb");
         builder = BoxStoreBuilder.createDebugWithoutModel().directory(dir);
-        builder.validateOnOpen(ValidateOnOpenMode.Full);
+        builder.validateOnOpen(ValidateOnOpenModePages.Full);
         try {
             store = builder.build();
             fail("Should have thrown");

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018 ObjectBox Ltd. All rights reserved.
+ * Copyright 2018-2023 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.
@@ -25,8 +25,8 @@
 import io.objectbox.AbstractObjectBoxTest;
 import io.objectbox.Box;
 import io.objectbox.BoxStoreBuilder;
-import io.objectbox.DebugFlags;
 import io.objectbox.TestEntity;
+import io.objectbox.config.DebugFlags;
 
 import javax.annotation.Nullable;
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017 ObjectBox Ltd. All rights reserved.
+ * Copyright 2017-2023 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.
@@ -19,12 +19,12 @@
 import io.objectbox.Box;
 import io.objectbox.BoxStore;
 import io.objectbox.BoxStoreBuilder;
-import io.objectbox.DebugFlags;
 import io.objectbox.TestEntity;
 import io.objectbox.TestEntity_;
 import io.objectbox.TestUtils;
 import io.objectbox.exception.DbExceptionListener;
 import io.objectbox.exception.NonUniqueResultException;
+import io.objectbox.config.DebugFlags;
 import io.objectbox.query.QueryBuilder.StringOrder;
 import io.objectbox.relation.MyObjectBox;
 import io.objectbox.relation.Order;

tests/objectbox-java-test/src/test/java/io/objectbox/relation/AbstractRelationTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017 ObjectBox Ltd. All rights reserved.
+ * Copyright 2017-2023 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.
@@ -27,7 +27,7 @@
 import io.objectbox.Box;
 import io.objectbox.BoxStore;
 import io.objectbox.BoxStoreBuilder;
-import io.objectbox.DebugFlags;
+import io.objectbox.config.DebugFlags;
 
 public abstract class AbstractRelationTest extends AbstractObjectBoxTest {