Docs: details for put and remove, match with Dart

Author: greenrobot-team

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

@@ -28,6 +28,7 @@
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.ThreadSafe;
 
+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 +39,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,11 +338,24 @@ 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)},
+     * 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 will be updated.
+     * Otherwise, it will be 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 not updated or removed. To do so, put or remove them using their 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.
+     * <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) {
@@ -432,9 +448,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 +467,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 +494,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 +512,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 +528,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 +549,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 +569,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();