Merge branch 'dev' into sync

greenrobot-team · greenrobot-team · commit db8a98d9c4ed · 2020-11-02T11:24:10.000+01:00
diff --git a/.github/no-response.yml b/.github/no-response.yml
@@ -0,0 +1,11 @@
+# Configuration for probot-no-response - https://github.com/probot/no-response
+
+# Number of days of inactivity before an Issue is closed for lack of response
+daysUntilClose: 21
+# Label requiring a response
+responseRequiredLabel: "more info required"
+# Comment to post when closing an Issue for lack of response. Set to `false` to disable
+closeComment: >
+  Without additional information, we are unfortunately not sure how to
+  resolve this issue. Therefore this issue has been automatically closed.
+  Feel free to comment with additional details and we can re-open this issue.
diff --git a/objectbox-java-api/src/main/java/io/objectbox/annotation/BaseEntity.java b/objectbox-java-api/src/main/java/io/objectbox/annotation/BaseEntity.java
@@ -6,8 +6,9 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotation for an entity base class.
- * ObjectBox will include properties of an entity super class marked with this annotation.
+ * Marks a class as an ObjectBox Entity super class.
+ * ObjectBox will store properties of this class as part of an Entity that inherits from this class.
+ * See <a href="https://docs.objectbox.io/advanced/entity-inheritance">the Entity Inheritance documentation</a> for details.
  */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.TYPE)
diff --git a/objectbox-java-api/src/main/java/io/objectbox/annotation/Convert.java b/objectbox-java-api/src/main/java/io/objectbox/annotation/Convert.java
@@ -16,25 +16,29 @@
 
 package io.objectbox.annotation;
 
-import io.objectbox.converter.PropertyConverter;
-
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import io.objectbox.converter.PropertyConverter;
+
 /**
- * Specifies {@link PropertyConverter} for the field to support custom types
+ * Supplies a {@link PropertyConverter converter} to store custom Property types as a supported {@link #dbType()}.
+ * See the <a href="https://docs.objectbox.io/advanced/custom-types">Custom Types documentation</a> for details.
  */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.FIELD)
 public @interface Convert {
-    /** Converter class */
+    /**
+     * The converter class that ObjectBox should use. See {@link PropertyConverter} for implementation guidelines.
+     */
     Class<? extends PropertyConverter> converter();
 
     /**
-     * Class of the DB type the Java property is converted to/from.
-     * This is limited to all java classes which are supported natively by ObjectBox.
+     * The Property type the Java field value is converted to/from.
+     * See the <a href="https://docs.objectbox.io/advanced/custom-types">Custom Types documentation</a> for a list
+     * of supported types.
      */
     Class dbType();
 }
diff --git a/objectbox-java-api/src/main/java/io/objectbox/annotation/Entity.java b/objectbox-java-api/src/main/java/io/objectbox/annotation/Entity.java
@@ -22,8 +22,8 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotation for entities
- * ObjectBox only persist objects of classes which are marked with this annotation
+ * Marks a class as an ObjectBox Entity.
+ * Allows to obtain a Box for this Entity from BoxStore to persist Objects of this class.
  */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.TYPE)
diff --git a/objectbox-java-api/src/main/java/io/objectbox/annotation/apihint/Temporary.java b/objectbox-java-api/src/main/java/io/objectbox/annotation/apihint/Temporary.java
diff --git a/objectbox-java-api/src/main/java/io/objectbox/annotation/package-info.java b/objectbox-java-api/src/main/java/io/objectbox/annotation/package-info.java
@@ -16,9 +16,9 @@
 
 /**
  * Annotations to mark a class as an {@link io.objectbox.annotation.Entity @Entity},
- * to specify the {@link io.objectbox.annotation.Id @Id} property,
+ * to specify the {@link io.objectbox.annotation.Id @Id} Property,
  * to create an {@link io.objectbox.annotation.Index @Index} or
- * a {@link io.objectbox.annotation.Transient @Transient} property.
+ * a {@link io.objectbox.annotation.Transient @Transient} Property.
  * <p>
  * For more details look at the documentation of individual classes and
  * <a href="https://docs.objectbox.io/entity-annotations">docs.objectbox.io/entity-annotations</a>.
diff --git a/objectbox-java-api/src/main/java/io/objectbox/converter/package-info.java b/objectbox-java-api/src/main/java/io/objectbox/converter/package-info.java
@@ -16,7 +16,7 @@
 
 /**
  * For use with {@link io.objectbox.annotation.Convert @Convert}: {@link io.objectbox.converter.PropertyConverter}
- * to convert custom property types.
+ * to convert custom Property types.
  * <p>
  * For more details look at the documentation of individual classes and
  * <a href="https://docs.objectbox.io/advanced/custom-types">docs.objectbox.io/advanced/custom-types</a>.
diff --git a/objectbox-java/src/main/java/io/objectbox/Box.java b/objectbox-java/src/main/java/io/objectbox/Box.java
@@ -39,11 +39,10 @@
 import io.objectbox.relation.RelationInfo;
 
 /**
- * A box to store objects of a particular class.
+ * A Box to put and get Objects of a specific Entity class.
  * <p>
  * Thread-safe.
  */
-@Beta
 @ThreadSafe
 @SuppressWarnings("WeakerAccess,UnusedReturnValue,unused")
 public class Box<T> {
diff --git a/objectbox-java/src/main/java/io/objectbox/BoxStore.java b/objectbox-java/src/main/java/io/objectbox/BoxStore.java
@@ -56,8 +56,8 @@
 import io.objectbox.sync.SyncClient;
 
 /**
- * Represents an ObjectBox database and gives you {@link Box}es to get and put Objects of a specific type
- * (see {@link #boxFor(Class)}).
+ * An ObjectBox database that provides {@link Box Boxes} to put and get Objects of a specific Entity class
+ * (see {@link #boxFor(Class)}). To get an instance of this class use {@code MyObjectBox.builder()}.
  */
 @SuppressWarnings({"unused", "UnusedReturnValue", "SameParameterValue", "WeakerAccess"})
 @ThreadSafe
diff --git a/objectbox-java/src/main/java/io/objectbox/BoxStoreBuilder.java b/objectbox-java/src/main/java/io/objectbox/BoxStoreBuilder.java
@@ -17,7 +17,7 @@
 package io.objectbox;
 
 import com.google.flatbuffers.FlatBufferBuilder;
-import io.objectbox.model.FlatStoreOptions;
+
 import org.greenrobot.essentials.io.IoUtils;
 
 import java.io.BufferedInputStream;
@@ -39,21 +39,20 @@
 import io.objectbox.annotation.apihint.Internal;
 import io.objectbox.exception.DbException;
 import io.objectbox.ideasonly.ModelUpdate;
+import io.objectbox.model.FlatStoreOptions;
 import io.objectbox.model.ValidateOnOpenMode;
 
 /**
- * Builds a {@link BoxStore} with optional configurations. The class is not initiated directly; use
- * MyObjectBox.builder() to get an instance.
+ * Configures and builds a {@link BoxStore} with reasonable defaults. To get an instance use {@code MyObjectBox.builder()}.
  * <p>
- * Each configuration has reasonable defaults, which you can adjust.
- * For Android, you must pass a Context using {@link #androidContext(Object)}.
+ * On Android, make sure to provide a Context to {@link #androidContext(Object) androidContext(context)}.
  * <p>
- * Configurations you can override:
+ * Some common defaults to override are:
  * <ol>
- * <li>Name/location of DB: use {@link #name(String)}/{@link #baseDirectory}/{@link #androidContext(Object)}
- * OR {@link #directory(File)}(default: name "objectbox)</li>
- * <li>Max DB size: see {@link #maxSizeInKByte} (default: 1 GB)</li>
- * <li>Max readers: see {@link #maxReaders(int)} (default: 126)</li>
+ * <li>Name/location of Store: use either {@link #name(String)}, {@link #baseDirectory(File)},
+ * {@link #androidContext(Object)} or {@link #directory(File)} (default: name "objectbox),</li>
+ * <li>Max DB size: see {@link #maxSizeInKByte(long)} (default: 1024 * 1024 KB = 1 GB),</li>
+ * <li>Max readers: see {@link #maxReaders(int)} (default: 126),</li>
  * </ol>
  */
 public class BoxStoreBuilder {
diff --git a/objectbox-java/src/main/java/io/objectbox/Property.java b/objectbox-java/src/main/java/io/objectbox/Property.java
@@ -29,8 +29,10 @@
 import io.objectbox.query.QueryCondition.PropertyCondition.Operation;
 
 /**
- * Meta data describing a property of an ObjectBox entity.
- * Properties are typically used to define query criteria using {@link io.objectbox.query.QueryBuilder}.
+ * Meta data describing a Property of an ObjectBox Entity.
+ * Properties are typically used when defining {@link io.objectbox.query.Query Query} conditions
+ * using {@link io.objectbox.query.QueryBuilder QueryBuilder}.
+ * Access properties using the generated underscore class of an entity (e.g. {@code Example_.id}).
  */
 @SuppressWarnings("WeakerAccess,UnusedReturnValue, unused")
 public class Property<ENTITY> implements Serializable {
diff --git a/objectbox-java/src/main/java/io/objectbox/model/Model.java b/objectbox-java/src/main/java/io/objectbox/model/Model.java
@@ -64,8 +64,19 @@ public final class Model extends Table {
   public io.objectbox.model.IdUid lastSequenceId(io.objectbox.model.IdUid obj) { int o = __offset(16); return o != 0 ? obj.__assign(o + bb_pos, bb) : null; }
   public io.objectbox.model.IdUid lastRelationId() { return lastRelationId(new io.objectbox.model.IdUid()); }
   public io.objectbox.model.IdUid lastRelationId(io.objectbox.model.IdUid obj) { int o = __offset(18); return o != 0 ? obj.__assign(o + bb_pos, bb) : null; }
+  /**
+   * Hash of the model/schema; usually want to check hashes before even creating a model and thus avoiding creating
+   * the model altogether. But, at least for now, let language bindings provide it via the model optionally.
+   * We use SipHash 128 (16 bytes).
+   */
+  public int hash(int j) { int o = __offset(20); return o != 0 ? bb.get(__vector(o) + j * 1) & 0xFF : 0; }
+  public int hashLength() { int o = __offset(20); return o != 0 ? __vector_len(o) : 0; }
+  public ByteVector hashVector() { return hashVector(new ByteVector()); }
+  public ByteVector hashVector(ByteVector obj) { int o = __offset(20); return o != 0 ? obj.__assign(__vector(o), bb) : null; }
+  public ByteBuffer hashAsByteBuffer() { return __vector_as_bytebuffer(20, 1); }
+  public ByteBuffer hashInByteBuffer(ByteBuffer _bb) { return __vector_in_bytebuffer(_bb, 20, 1); }
 
-  public static void startModel(FlatBufferBuilder builder) { builder.startTable(8); }
+  public static void startModel(FlatBufferBuilder builder) { builder.startTable(9); }
   public static void addModelVersion(FlatBufferBuilder builder, long modelVersion) { builder.addInt(0, (int)modelVersion, (int)0L); }
   public static void addName(FlatBufferBuilder builder, int nameOffset) { builder.addOffset(1, nameOffset, 0); }
   public static void addVersion(FlatBufferBuilder builder, long version) { builder.addLong(2, version, 0L); }
@@ -76,6 +87,10 @@ public final class Model extends Table {
   public static void addLastIndexId(FlatBufferBuilder builder, int lastIndexIdOffset) { builder.addStruct(5, lastIndexIdOffset, 0); }
   public static void addLastSequenceId(FlatBufferBuilder builder, int lastSequenceIdOffset) { builder.addStruct(6, lastSequenceIdOffset, 0); }
   public static void addLastRelationId(FlatBufferBuilder builder, int lastRelationIdOffset) { builder.addStruct(7, lastRelationIdOffset, 0); }
+  public static void addHash(FlatBufferBuilder builder, int hashOffset) { builder.addOffset(8, hashOffset, 0); }
+  public static int createHashVector(FlatBufferBuilder builder, byte[] data) { return builder.createByteVector(data); }
+  public static int createHashVector(FlatBufferBuilder builder, ByteBuffer data) { return builder.createByteVector(data); }
+  public static void startHashVector(FlatBufferBuilder builder, int numElems) { builder.startVector(1, numElems, 1); }
   public static int endModel(FlatBufferBuilder builder) {
     int o = builder.endTable();
     return o;
diff --git a/objectbox-java/src/main/java/io/objectbox/package-info.java b/objectbox-java/src/main/java/io/objectbox/package-info.java
@@ -22,7 +22,7 @@
  * <li>MyObjectBox: Generated by the Gradle plugin, supplies a {@link io.objectbox.BoxStoreBuilder}
  * to build a BoxStore for your app.</li>
  * <li>{@link io.objectbox.BoxStore}: The database interface, allows to manage Boxes.</li>
- * <li>{@link io.objectbox.Box}: Persists and queries for entities, there is one for each entity.</li>
+ * <li>{@link io.objectbox.Box}: Persists and queries for Objects, there is one for each Entity class.</li>
  * </ul>
  * <p>
  * For more details look at the documentation of individual classes and
diff --git a/objectbox-java/src/main/java/io/objectbox/query/LazyList.java b/objectbox-java/src/main/java/io/objectbox/query/LazyList.java
@@ -22,24 +22,33 @@
 import java.util.ListIterator;
 import java.util.NoSuchElementException;
 
+import javax.annotation.Nullable;
+
 import io.objectbox.Box;
 import io.objectbox.exception.DbException;
 
 /**
- * A thread-safe, unmodifiable list that reads entities lazily once they are accessed.
- * A lazy list can be cached or not.
- * Cached lazy lists store the previously accessed objects to avoid loading entities more than once.
- * Some features of the list are limited to cached lists (e.g. features that require the entire list).
+ * A thread-safe, unmodifiable {@link List} that gets Objects from their Box not until they are accessed.
+ * Internally the list is backed by an array of Object IDs.
+ * <p>
+ * If the list is set to not cache retrieved Objects, each operation will get the latest version of an Object
+ * from its Box. However, in this mode only a limited set of {@link List} operations,
+ * like get or iterator are supported.
  * <p>
- * Note: this list gives an semiconsitent view on the data at the moment it was created.
- * If you remove objects from their object box after this list was created, this list will null instead of an object.
- * However, if you add objects to their object box after this list was created, this list will not be extended.
+ * If the list is set to cache retrieved Objects, operations will return a previously fetched version of an Object,
+ * which might not equal the latest version in its Box. However, in this mode almost all {@link List}
+ * operations are supported. Note that operations that require the whole list, like contains, will fetch all
+ * Objects in this list from the Box at once.
+ * <p>
+ * Note: as Objects are fetched on demand, this list returns a null Object if the Object was removed from its Box
+ * after this list was created.
  *
  * @param <E> Object type (entity).
- * @author Markus
  */
-// Threading note: locking is tailored to ArrayList assuming that concurrent positional gets/sets are OK.
-// To enable this, the internal ArrayList is prepopulated with null.
+/*
+ Threading note: locking is tailored to ArrayList assuming that concurrent positional gets/sets are OK.
+ To enable this, the internal ArrayList is prepopulated with null.
+*/
 public class LazyList<E> implements List<E> {
     protected class LazyIterator implements ListIterator<E> {
         private int index;
@@ -206,9 +215,11 @@ public boolean containsAll(Collection<?> collection) {
     }
 
     /**
-     * @return An object for the given ID, or null if the object was already removed from its box
-     * (and was not cached before).
+     * Gets and returns the Object at the specified position in this list from its Box. Returns null if the
+     * Object was removed from its Box. If this list is caching retrieved Objects, returns the previously
+     * fetched version.
      */
+    @Nullable
     @Override
     public E get(int location) {
         if (location < 0 || location > size) {
diff --git a/objectbox-java/src/main/java/io/objectbox/query/Query.java b/objectbox-java/src/main/java/io/objectbox/query/Query.java
@@ -38,11 +38,15 @@
 import io.objectbox.relation.ToOne;
 
 /**
- * A repeatable query returning entities.
+ * A repeatable Query returning the latest matching Objects.
+ * <p>
+ * Use {@link #find()} or related methods to fetch the latest results from the BoxStore.
+ * <p>
+ * Use {@link #property(Property)} to only return values or an aggregate of a single Property.
+ * <p>
+ * See the <a href="https://docs.objectbox.io/queries">Queries documentation</a> for details.
  *
- * @param <T> The entity class the query will return results for.
- * @author Markus
- * @see QueryBuilder
+ * @param <T> Entity class for which results are returned.
  */
 @SuppressWarnings({"SameParameterValue", "UnusedReturnValue", "WeakerAccess"})
 public class Query<T> implements Closeable {
@@ -250,14 +254,26 @@ public long[] findIds(final long offset, final long limit) {
     }
 
     /**
-     * Find all Objects matching the query without actually loading the Objects. See @{@link LazyList} for details.
+     * Like {@link #findIds()}, but wraps the Object IDs in an unmodifiable {@link LazyList}
+     * so Objects can be retrieved on demand. The LazyList does not cache retrieved Objects, so only basic
+     * {@link List} operations like getting or iterating list items are supported. See {@link LazyList} for details.
      */
+    @Nonnull
     public LazyList<T> findLazy() {
         ensureNoFilterNoComparator();
         return new LazyList<>(box, findIds(), false);
     }
 
-    // TODO we might move all those property find methods in a "PropertyQuery" class for divide & conquer.
+    /**
+     * Like {@link #findIds()}, but wraps the Object IDs in an unmodifiable, caching {@link LazyList}
+     * so Objects can be retrieved on demand. The LazyList caches retrieved Objects supporting almost
+     * all {@link List} operations, at the expense of used memory. See {@link LazyList} for details.
+     */
+    @Nonnull
+    public LazyList<T> findLazyCached() {
+        ensureNoFilterNoComparator();
+        return new LazyList<>(box, findIds(), true);
+    }
 
     /**
      * Creates a {@link PropertyQuery} for the given property.
@@ -311,15 +327,6 @@ public void forEach(final QueryConsumer<T> consumer) {
         });
     }
 
-    /**
-     * Find all Objects matching the query without actually loading the Objects. See @{@link LazyList} for details.
-     */
-    @Nonnull
-    public LazyList<T> findLazyCached() {
-        ensureNoFilterNoComparator();
-        return new LazyList<>(box, findIds(), true);
-    }
-
     void resolveEagerRelations(List<T> entities) {
         if (eagerRelations != null) {
             int entityIndex = 0;
diff --git a/objectbox-java/src/main/java/io/objectbox/query/QueryBuilder.java b/objectbox-java/src/main/java/io/objectbox/query/QueryBuilder.java
diff --git a/objectbox-java/src/main/java/io/objectbox/reactive/package-info.java b/objectbox-java/src/main/java/io/objectbox/reactive/package-info.java
diff --git a/objectbox-java/src/main/java/io/objectbox/relation/package-info.java b/objectbox-java/src/main/java/io/objectbox/relation/package-info.java
diff --git a/tests/objectbox-java-test/src/test/java/io/objectbox/query/QueryObserverTest.java b/tests/objectbox-java-test/src/test/java/io/objectbox/query/QueryObserverTest.java
