Merge branch 'to-one-docs-polish' into 'dev'

ToOne: update setTarget and related docs to match implementation

See merge request objectbox/objectbox-java!26

Author: greenrobot-team

objectbox-java/src/main/java/io/objectbox/relation/ToOne.java

@@ -33,8 +33,9 @@
  * A to-relation is unidirectional: it points from the source entity to the target entity.
  * The target is referenced by its ID, which is persisted in the source entity.
  * <p>
- * If their is a backlink {@link ToMany} relation based on this to-one relation,
- * the ToMany object will not be notified/updated about changes done here (use {@link ToMany#reset()} if required).
+ * If there is a {@link ToMany} relation linking back to this to-one relation (@Backlink),
+ * the ToMany object will not be notified/updated about persisted changes here.
+ * Call {@link ToMany#reset()} so it will update when next accessed.
  */
 // TODO add more tests
 // TODO not exactly thread safe
@@ -106,7 +107,7 @@ public TARGET getTarget(long targetId) {
         return targetNew;
     }
 
-    private void ensureBoxes(TARGET target) {
+    private void ensureBoxes(@Nullable TARGET target) {
         // Only check the property set last
         if (targetBox == null) {
             Field boxStoreField = ReflectionCache.getInstance().getField(entity.getClass(), "__boxStore");
@@ -148,6 +149,14 @@ public boolean isNull() {
         return getTargetId() == 0 && target == null;
     }
 
+    /**
+     * Sets or clears the target ID in the source entity. Pass 0 to clear.
+     * <p>
+     * Put the source entity to persist changes.
+     * If the ID is not 0 creates a relation to the target entity with this ID, otherwise dissolves it.
+     *
+     * @see #setTarget
+     */
     public void setTargetId(long targetId) {
         if (virtualProperty) {
             this.targetId = targetId;
@@ -172,10 +181,13 @@ void setAndUpdateTargetId(long targetId) {
     }
 
     /**
-     * Sets the relation ID in the enclosed entity to the ID of the given target entity.
-     * If the target entity was not put in the DB yet (its ID is 0), it will be put before to get its ID.
+     * Sets or clears the target entity and ID in the source entity. Pass null to clear.
+     * <p>
+     * Put the source entity to persist changes.
+     * If the target entity was not put yet (its ID is 0), it will be stored when the source entity is put.
+     *
+     * @see #setTargetId
      */
-    // TODO provide a overload with a ToMany parameter, which also gets updated
     public void setTarget(@Nullable final TARGET target) {
         if (target != null) {
             long targetId = relationInfo.targetInfo.getIdGetter().getId(target);
@@ -189,10 +201,11 @@ public void setTarget(@Nullable final TARGET target) {
     }
 
     /**
-     * Sets the relation ID in the enclosed entity to the ID of the given target entity and puts the enclosed entity.
-     * If the target entity was not put in the DB yet (its ID is 0), it will be put before to get its ID.
+     * Sets or clears the target entity and ID in the source entity, then puts the source entity to persist changes.
+     * Pass null to clear.
+     * <p>
+     * If the target entity was not put yet (its ID is 0), it will be put before the source entity.
      */
-    // TODO provide a overload with a ToMany parameter, which also gets updated
     public void setAndPutTarget(@Nullable final TARGET target) {
         ensureBoxes(target);
         if (target != null) {
@@ -212,9 +225,13 @@ public void setAndPutTarget(@Nullable final TARGET target) {
     }
 
     /**
-     * Sets the relation ID in the enclosed entity to the ID of the given target entity and puts both entities.
+     * Sets or clears the target entity and ID in the source entity,
+     * then puts the target (if not null) and source entity to persist changes.
+     * Pass null to clear.
+     * <p>
+     * When clearing the target entity, this does not remove it from its box.
+     * This only dissolves the relation.
      */
-    // TODO provide a overload with a ToMany parameter, which also gets updated
     public void setAndPutTargetAlways(@Nullable final TARGET target) {
         ensureBoxes(target);
         if (target != null) {