Merge branch 'docs-updates' into 'dev'

Docs: details for put and remove, more ToMany details

See merge request objectbox/objectbox-java!134

Author: greenrobot-team

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

@@ -28,6 +28,8 @@
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.ThreadSafe;
 
+import io.objectbox.annotation.Backlink;
+import io.objectbox.annotation.Id;
 import io.objectbox.annotation.apihint.Beta;
 import io.objectbox.annotation.apihint.Experimental;
 import io.objectbox.annotation.apihint.Internal;
@@ -38,6 +40,8 @@
 import io.objectbox.query.QueryBuilder;
 import io.objectbox.query.QueryCondition;
 import io.objectbox.relation.RelationInfo;
+import io.objectbox.relation.ToMany;
+import io.objectbox.relation.ToOne;
 
 /**
  * A Box to put and get Objects of a specific Entity class.
@@ -335,12 +339,25 @@ public boolean contains(long id) {
     }
 
     /**
-     * Puts the given object in the box (aka persisting it). If this is a new entity (its ID property is 0), a new ID
-     * will be assigned to the entity (and returned). If the entity was already put in the box before, it will be
-     * overwritten.
+     * Puts the given object and returns its (new) ID.
      * <p>
-     * Performance note: if you want to put several entities, consider {@link #put(Collection)},
-     * {@link #put(Object[])}, {@link BoxStore#runInTx(Runnable)}, etc. instead.
+     * This means that if its {@link Id @Id} property is 0 or null, it is inserted as a new object and assigned the next
+     * available ID. For example, if there is an object with ID 1 and another with ID 100, it will be assigned ID 101.
+     * The new ID is also set on the given object before this returns.
+     * <p>
+     * If instead the object has an assigned ID set, if an object with the same ID exists it is updated. Otherwise, it
+     * is inserted with that ID.
+     * <p>
+     * If the ID was not assigned before an {@link IllegalArgumentException} is thrown.
+     * <p>
+     * When the object contains {@link ToOne} or {@link ToMany} relations, they are created (or updated) to point to the
+     * (new) target objects. The target objects themselves are typically not updated or removed. To do so, put or remove
+     * them using their {@link Box}. However, for convenience, if a target object is new, it will be inserted and
+     * assigned an ID in its Box before creating or updating the relation. Also, for ToMany relations based on a
+     * {@link Backlink} the target objects are updated (to store changes in the linked ToOne or ToMany relation).
+     * <p>
+     * Performance note: if you want to put several objects, consider {@link #put(Collection)}, {@link #put(Object[])},
+     * {@link BoxStore#runInTx(Runnable)}, etc. instead.
      */
     public long put(T entity) {
         Cursor<T> cursor = getWriter();
@@ -432,9 +449,11 @@ public void putBatched(@Nullable Collection<T> entities, int batchSize) {
     }
 
     /**
-     * Removes (deletes) the Object by its ID.
+     * Removes (deletes) the object with the given ID.
+     * <p>
+     * If the object is part of a relation, it will be removed from that relation as well.
      *
-     * @return true if an entity was actually removed (false if no entity exists with the given ID)
+     * @return true if the object did exist and was removed, otherwise false.
      */
     public boolean remove(long id) {
         Cursor<T> cursor = getWriter();
@@ -449,7 +468,7 @@ public boolean remove(long id) {
     }
 
     /**
-     * Removes (deletes) Objects by their ID in a single transaction.
+     * Like {@link #remove(long)}, but removes multiple objects in a single transaction.
      */
     public void remove(@Nullable long... ids) {
         if (ids == null || ids.length == 0) {
@@ -476,7 +495,7 @@ public void removeByKeys(@Nullable Collection<Long> ids) {
     }
 
     /**
-     * Due to type erasure collision, we cannot simply use "remove" as a method name here.
+     * Like {@link #remove(long)}, but removes multiple objects in a single transaction.
      */
     public void removeByIds(@Nullable Collection<Long> ids) {
         if (ids == null || ids.isEmpty()) {
@@ -494,9 +513,7 @@ public void removeByIds(@Nullable Collection<Long> ids) {
     }
 
     /**
-     * Removes (deletes) the given Object.
-     *
-     * @return true if an entity was actually removed (false if no entity exists with the given ID)
+     * Like {@link #remove(long)}, but obtains the ID from the {@link Id @Id} property of the given object instead.
      */
     public boolean remove(T object) {
         Cursor<T> cursor = getWriter();
@@ -512,7 +529,7 @@ public boolean remove(T object) {
     }
 
     /**
-     * Removes (deletes) the given Objects in a single transaction.
+     * Like {@link #remove(Object)}, but removes multiple objects in a single transaction.
      */
     @SafeVarargs // Not using T... as Object[], no ClassCastException expected.
     @SuppressWarnings("Duplicates") // Detected duplicate has different type
@@ -533,7 +550,7 @@ public final void remove(@Nullable T... objects) {
     }
 
     /**
-     * Removes (deletes) the given Objects in a single transaction.
+     * Like {@link #remove(Object)}, but removes multiple objects in a single transaction.
      */
     @SuppressWarnings("Duplicates") // Detected duplicate has different type
     public void remove(@Nullable Collection<T> objects) {
@@ -553,7 +570,7 @@ public void remove(@Nullable Collection<T> objects) {
     }
 
     /**
-     * Removes (deletes) ALL Objects in a single transaction.
+     * Like {@link #remove(long)}, but removes <b>all</b> objects in a single transaction.
      */
     public void removeAll() {
         Cursor<T> cursor = getWriter();
@@ -578,9 +595,10 @@ public long panicModeRemoveAll() {
 
     /**
      * Returns a builder to create queries for Object matching supplied criteria.
-     * <p>
-     * New code should use {@link #query(QueryCondition)} instead.
+     *
+     * @deprecated New code should use {@link #query(QueryCondition)} instead.
      */
+    @Deprecated
     public QueryBuilder<T> query() {
         return new QueryBuilder<>(this, store.getNativeStore(), store.getDbName(entityClass));
     }

objectbox-java/src/main/java/io/objectbox/query/Query.java

@@ -31,16 +31,17 @@
 import io.objectbox.BoxStore;
 import io.objectbox.InternalAccess;
 import io.objectbox.Property;
+import io.objectbox.exception.NonUniqueResultException;
 import io.objectbox.reactive.DataObserver;
 import io.objectbox.reactive.DataSubscriptionList;
 import io.objectbox.reactive.SubscriptionBuilder;
 import io.objectbox.relation.RelationInfo;
 import io.objectbox.relation.ToOne;
 
 /**
- * A repeatable Query returning the latest matching Objects.
+ * A repeatable Query returning the latest matching objects.
  * <p>
- * Use {@link #find()} or related methods to fetch the latest results from the BoxStore.
+ * Use {@link #find()} or related methods to fetch the latest results from the {@link BoxStore}.
  * <p>
  * Use {@link #property(Property)} to only return values or an aggregate of a single Property.
  * <p>
@@ -195,7 +196,12 @@ long cursorHandle() {
     }
 
     /**
-     * Find the first Object matching the query.
+     * Finds the first object matching this query.
+     * <p>
+     * Note: if no {@link QueryBuilder#order} conditions are present, which object is the first one might be arbitrary
+     * (sometimes the one with the lowest ID, but never guaranteed to be).
+     *
+     * @return The first object if there are matches. {@code null} if no object matches.
      */
     @Nullable
     public T findFirst() {
@@ -228,9 +234,10 @@ private void ensureNoComparator() {
     }
 
     /**
-     * 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.
+     * Finds the only object matching this query.
+     *
+     * @return The object if a single object matches. {@code null} if no object matches. Throws
+     * {@link NonUniqueResultException} if there are multiple objects matching the query.
      */
     @Nullable
     public T findUnique() {
@@ -244,7 +251,12 @@ public T findUnique() {
     }
 
     /**
-     * Find all Objects matching the query.
+     * Finds objects matching the query.
+     * <p>
+     * Note: if no {@link QueryBuilder#order} conditions are present, the order is arbitrary (sometimes ordered by ID,
+     * but never guaranteed to).
+     *
+     * @return A list of matching objects. An empty list if no object matches.
      */
     @Nonnull
     public List<T> find() {
@@ -268,8 +280,12 @@ public List<T> find() {
     }
 
     /**
-     * Find all Objects matching the query, skipping the first offset results and returning at most limit results.
-     * Use this for pagination.
+     * Like {@link #find()}, but can skip and limit results.
+     * <p>
+     * Use to get a slice of the whole result, e.g. for "result paging".
+     *
+     * @param offset If greater than 0, skips this many results.
+     * @param limit If greater than 0, returns at most this many results.
      */
     @Nonnull
     public List<T> find(final long offset, final long limit) {
@@ -282,46 +298,59 @@ 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.
+     * Like {@link #findFirst()}, but returns just the ID of the object.
      * <p>
-     * Like {@link #findFirst()}, but more efficient as no object is created.
+     * This is more efficient as no object is created.
      * <p>
      * Ignores any {@link QueryBuilder#filter(QueryFilter) query filter}.
+     *
+     * @return The ID of the first matching object. {@code 0} if no object matches.
      */
     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.
+     * Like {@link #findUnique()}, but returns just the ID of the object.
      * <p>
-     * Like {@link #findUnique()}, but more efficient as no object is created.
+     * This is more efficient as no object is created.
      * <p>
      * Ignores any {@link QueryBuilder#filter(QueryFilter) query filter}.
+     *
+     * @return The ID of the object, if a single object matches. {@code 0} if no object matches. Throws
+     * {@link NonUniqueResultException} if there are multiple objects matching the query.
      */
     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).
+     * Like {@link #find()}, but returns just the IDs of the objects.
+     * <p>
+     * IDs can later be used to {@link Box#get} objects.
+     * <p>
+     * This is very efficient as no objects are created.
      * <p>
      * Note: a filter set with {@link QueryBuilder#filter(QueryFilter)} will be silently ignored!
+     *
+     * @return An array of IDs of matching objects. An empty array if no objects match.
      */
     @Nonnull
     public long[] findIds() {
         return findIds(0, 0);
     }
 
     /**
-     * Like {@link #findIds()} but with a offset/limit param, e.g. for pagination.
+     * Like {@link #findIds()}, but can skip and limit results.
+     * <p>
+     * Use to get a slice of the whole result, e.g. for "result paging".
      * <p>
      * Note: a filter set with {@link QueryBuilder#filter(QueryFilter)} will be silently ignored!
+     *
+     * @param offset If greater than 0, skips this many results.
+     * @param limit If greater than 0, returns at most this many results.
      */
     @Nonnull
     public long[] findIds(final long offset, final long limit) {

objectbox-java/src/main/java/io/objectbox/query/QueryBuilder.java

@@ -425,8 +425,7 @@ public <TARGET> QueryBuilder<TARGET> backlink(RelationInfo<TARGET, ?> relationIn
 
     /**
      * Specifies relations that should be resolved eagerly.
-     * This prepares the given relation objects to be preloaded (cached) avoiding further get operations from the db.
-     * A common use case is prealoading all
+     * This prepares the given relation objects to be preloaded (cached) avoiding further get operations from the database.
      *
      * @param relationInfo The relation as found in the generated meta info class ("EntityName_") of class T.
      * @param more         Supply further relations to be eagerly loaded.