Merge branch 'releases' into release/transformer-api

# Conflicts:
#	CHANGELOG.md
#	version.txt

Author: Christian Melchior

CHANGELOG.md

@@ -8,6 +8,7 @@ the main release [CHANGELOG.md](https://github.com/realm/realm-java/blob/release
 * None.
 
 ### Fixed
+* Added support for automatic handling of orphan embedded objects after migrating regular object properties to become embedded objects. (Issue [#7769](https://github.com/realm/realm-java/issues/7769)).
 * Unit tests not being executed. (Issue [#7771](https://github.com/realm/realm-java/issues/7771))
 * Instrumented unit tests failed to execute because of the Realm dependencies being missing. (Issue [#7736](https://github.com/realm/realm-java/issues/7736))
 

realm/realm-library/src/androidTest/java/io/realm/RealmMigrationTests.java

@@ -37,6 +37,9 @@
 
 import androidx.test.ext.junit.runners.AndroidJUnit4;
 import androidx.test.platform.app.InstrumentationRegistry;
+
+import io.realm.annotations.PrimaryKey;
+import io.realm.annotations.RealmClass;
 import io.realm.entities.AllTypes;
 import io.realm.entities.AnnotationTypes;
 import io.realm.entities.CatOwner;
@@ -62,6 +65,10 @@
 import io.realm.entities.Thread;
 import io.realm.entities.embedded.EmbeddedSimpleChild;
 import io.realm.entities.embedded.EmbeddedSimpleParent;
+import io.realm.entities.migration.HandleBackLinksChild1;
+import io.realm.entities.migration.HandleBackLinksChild2;
+import io.realm.entities.migration.HandleBackLinksParent1;
+import io.realm.entities.migration.HandleBackLinksParent2;
 import io.realm.entities.migration.MigrationClassRenamed;
 import io.realm.entities.migration.MigrationCore6PKStringIndexedByDefault;
 import io.realm.entities.migration.MigrationFieldRenameAndAdd;
@@ -1712,6 +1719,135 @@ public void migrate(DynamicRealm realm, long oldVersion, long newVersion) {
         realm = Realm.getInstance(realmConfig);
     }
 
+    @Test
+    public void migrate_embeddedObject_deleteOrphans() {
+        RealmConfiguration config1 = configFactory.createConfigurationBuilder()
+                .schema(HandleBackLinksParent1.class, HandleBackLinksChild1.class)
+                .schemaVersion(1)
+                .build();
+
+        Realm realm1 = Realm.getInstance(config1);
+        realm1.executeTransaction(realm -> {
+            HandleBackLinksChild1 child = new HandleBackLinksChild1();
+            HandleBackLinksParent1 parent = new HandleBackLinksParent1();
+            parent.child = child;
+            HandleBackLinksChild1 orphan = new HandleBackLinksChild1();
+            realm.insertOrUpdate(parent);
+            realm.insertOrUpdate(orphan);
+        });
+        long parentCountV1 = realm1.where(HandleBackLinksParent1.class)
+                .count();
+        assertEquals(1L, parentCountV1);
+        long childCountV1 = realm1.where(HandleBackLinksChild1.class)
+                .count();
+        assertEquals(2L, childCountV1);
+        realm1.close();
+
+        RealmMigration migration = (realm, oldVersion, newVersion) -> {
+            RealmSchema schema = realm.getSchema();
+            if (oldVersion == 1L) {
+                RealmObjectSchema parent = schema.get("HandleBackLinksParent1");
+                assertNotNull(parent);
+                RealmObjectSchema child = schema.get("HandleBackLinksChild1");
+                assertNotNull(child);
+                try {
+                    child.setEmbedded(true);
+                } catch (Exception e) {
+                    assertEquals(IllegalStateException.class, e.getClass());
+                    assertEquals("Cannot convert 'HandleBackLinksChild1' to embedded: at least one object has no incoming links and would be deleted.", e.getMessage());
+                }
+                child.setEmbedded(true, true);
+
+                // Rename classes to avoid conflicts with all other tests
+                parent.setClassName("HandleBackLinksParent2");
+                child.setClassName("HandleBackLinksChild2");
+            }
+        };
+
+        // Create schema v2
+        RealmConfiguration config2 = configFactory.createConfigurationBuilder()
+                .schema(HandleBackLinksParent2.class, HandleBackLinksChild2.class)
+                .schemaVersion(2)
+                .migration(migration)
+                .build();
+
+        // The orphan child is erased
+        Realm realm2 = Realm.getInstance(config2);
+        long parentCountV2 = realm2.where(HandleBackLinksParent2.class)
+                .count();
+        assertEquals(1L, parentCountV2);
+        long childCountV2 = realm2.where(HandleBackLinksChild2.class)
+                .count();
+        assertEquals(1L, childCountV2);
+        realm2.close();
+    }
+
+    @Test
+    public void migrate_embeddedObject_clonesChildWhenReferencedMoreThanOnce() {
+        RealmConfiguration config1 = configFactory.createConfigurationBuilder()
+                .schema(HandleBackLinksParent1.class, HandleBackLinksChild1.class)
+                .schemaVersion(1)
+                .build();
+
+        Realm realm1 = Realm.getInstance(config1);
+        HandleBackLinksChild1 child = new HandleBackLinksChild1();
+        HandleBackLinksParent1 parent1 = new HandleBackLinksParent1();
+        HandleBackLinksParent1 parent2 = new HandleBackLinksParent1();
+        realm1.executeTransaction(realm -> {
+            // Copy child and set it as children for both parents.
+            // Now the managed child has two parents. This will not be allowed after converting it
+            // to an embedded object and will result into the child object being duplicated so that
+            // both parents can have a reference to a separate and different embedded object.
+            HandleBackLinksChild1 managedChild = realm.copyToRealm(child);
+            parent1.id = 1L;
+            parent1.child = managedChild;
+            realm.insert(parent1);
+            parent2.id = 2L;
+            parent2.child = managedChild;
+            realm.insert(parent2);
+        });
+        long parentCountV1 = realm1.where(HandleBackLinksParent1.class)
+                .count();
+        assertEquals(2L, parentCountV1);
+        long childCountV1 = realm1.where(HandleBackLinksChild1.class)
+                .count();
+        assertEquals(1L, childCountV1);
+        realm1.close();
+
+        RealmMigration migration = (realm, oldVersion, newVersion) -> {
+            RealmSchema schema = realm.getSchema();
+            if (oldVersion == 1L) {
+                RealmObjectSchema parentSchema = schema.get("HandleBackLinksParent1");
+                assertNotNull(parentSchema);
+                RealmObjectSchema childSchema = schema.get("HandleBackLinksChild1");
+                assertNotNull(childSchema);
+                childSchema.setEmbedded(true, true);
+
+                // Rename classes to avoid conflicts with all other tests
+                parentSchema.setClassName("HandleBackLinksParent2");
+                childSchema.setClassName("HandleBackLinksChild2");
+            }
+        };
+
+        // Create schema v2
+        RealmConfiguration config2 = configFactory.createConfigurationBuilder()
+                .schema(HandleBackLinksParent2.class, HandleBackLinksChild2.class)
+                .schemaVersion(2)
+                .migration(migration)
+                .build();
+
+        // After the migration the only child class is embedded and will not be allowed to have two parents
+        // so the child object will be duplicated
+        Realm realm2 = Realm.getInstance(config2);
+        long parentCountV2 = realm2.where(HandleBackLinksParent2.class)
+                .count();
+        assertEquals(2L, parentCountV2);
+        long childCountV2 = realm2.where(HandleBackLinksChild2.class)
+                .count();
+        assertEquals(2L, childCountV2);
+        realm2.close();
+    }
+
     // TODO Add unit tests for default nullability
     // TODO Add unit tests for default Indexing for Primary keys
 }

realm/realm-library/src/androidTest/java/io/realm/entities/migration/HandleBackLinksChild1.java

@@ -0,0 +1,12 @@
+package io.realm.entities.migration;
+
+import io.realm.RealmObject;
+
+// Original child as a regular object
+public class HandleBackLinksChild1 extends RealmObject {
+
+    public String name;
+
+    public HandleBackLinksChild1() {}
+
+}

realm/realm-library/src/androidTest/java/io/realm/entities/migration/HandleBackLinksChild2.java

@@ -0,0 +1,14 @@
+package io.realm.entities.migration;
+
+import io.realm.RealmObject;
+import io.realm.annotations.RealmClass;
+
+// Child, now as an embedded object, respecting table names
+@RealmClass(embedded = true)
+public class HandleBackLinksChild2 extends RealmObject {
+
+    public String name;
+
+    public HandleBackLinksChild2() {}
+
+}

realm/realm-library/src/androidTest/java/io/realm/entities/migration/HandleBackLinksParent1.java

@@ -0,0 +1,14 @@
+package io.realm.entities.migration;
+
+import io.realm.RealmObject;
+import io.realm.annotations.PrimaryKey;
+
+// Original parent with a regular object as a child
+public class HandleBackLinksParent1 extends RealmObject {
+    @PrimaryKey
+    public long id;
+
+    public HandleBackLinksChild1 child;
+
+    public HandleBackLinksParent1() {}
+}

realm/realm-library/src/androidTest/java/io/realm/entities/migration/HandleBackLinksParent2.java

@@ -0,0 +1,14 @@
+package io.realm.entities.migration;
+
+import io.realm.RealmObject;
+import io.realm.annotations.PrimaryKey;
+
+// Parent, now having an embedded object as a child, respecting table names
+public class HandleBackLinksParent2 extends RealmObject {
+    @PrimaryKey
+    public long id;
+
+    public HandleBackLinksChild2 child;
+
+    public HandleBackLinksParent2() {}
+}

realm/realm-library/src/main/cpp/io_realm_internal_Table.cpp

@@ -1120,11 +1120,11 @@ JNIEXPORT jboolean JNICALL Java_io_realm_internal_Table_nativeIsEmbedded(JNIEnv*
     return false;
 }
 
-JNIEXPORT jboolean JNICALL Java_io_realm_internal_Table_nativeSetEmbedded(JNIEnv* env, jclass, jlong j_table_ptr, jboolean j_embedded)
+JNIEXPORT jboolean JNICALL Java_io_realm_internal_Table_nativeSetEmbedded(JNIEnv* env, jclass, jlong j_table_ptr, jboolean j_embedded, jboolean j_handle_backlinks)
 {
     try {
         TableRef table = TableRef(TBL_REF(j_table_ptr));
-        table->set_table_type(to_bool(j_embedded) ? Table::Type::Embedded : Table::Type::TopLevel);
+        table->set_table_type(to_bool(j_embedded) ? Table::Type::Embedded : Table::Type::TopLevel, to_bool(j_handle_backlinks));
         return true;
     }
     CATCH_STD()

realm/realm-library/src/main/java/io/realm/RealmObjectSchema.java

@@ -584,15 +584,66 @@ public boolean isEmbedded() {
      *     </li>
      * </ul>
      *
-     * @throws IllegalStateException if the class could not be converted because it broke some of the Embedded Objects invariants.
+     * @param embedded If @{code true}, the class type will be turned into an embedded class, and
+     * must satisfy the constraints defined above. If @{code false}, the class will be turn into
+     * a normal class. An embeded class can always be turned into a non-embedded one.
+     * @throws IllegalStateException if the class could not be converted because it broke some of
+     * the Embedded Objects invariants.
      * @see RealmClass#embedded()
      */
     public void setEmbedded(boolean embedded) {
+        setEmbedded(embedded, false);
+    }
+
+    /**
+     * Converts the class to be embedded or not, while also providing automatic handling of objects
+     * that break some of the constraints for making the class embedded.
+     * <p>
+     * A class can only be marked as embedded if the following invariants are satisfied:
+     * <ul>
+     *     <li>
+     *         The class is not allowed to have a primary key defined.
+     *     </li>
+     *     <li>
+     *         All existing objects of this type, must have one and exactly one parent object
+     *         already pointing to it. If 0 or more than 1 object has a reference to an object
+     *         about to be marked embedded an {@link IllegalStateException} will be thrown.
+     *     </li>
+     * </ul>
+     *
+     * If some of these constraints are broken you can ask Realm to resolve them automatically using
+     * the @{code resolveEmbeddedClassConstraints} parameter. Setting this to @{code true} will
+     * do the following:
+     * <ul>
+     *     <li>
+     *         An object with 0 parents, i.e. no other objects have a reference to it, will be
+     *         deleted.
+     *     </li>
+     *     <li>
+     *         An object with more than 1 parent, i.e. 2 or more objects have a reference to it,
+     *         will be copied so each copy have exactly one parent.
+     *     </li>
+     *     <li>
+     *         Objects with a primary key defined will still throw an IllegalStateException and
+     *         cannot be converted.
+     *     </li>
+     * </ul>
+     *
+     * @param embedded If @{code true}, the class type will be turned into an embedded class, and
+     * must satisfy the constraints defined above. If @{code false}, the class will be turn into
+     * a normal class. An embeded class can always be turned into a non-embedded one.
+     * @param resolveEmbeddedClassConstraints whether or not to automatically fix broken constraints
+     * if @{code embedded} was set to true. See above for a full description of what that entails.
+     * @throws IllegalStateException if the class could not be converted because it broke some of
+     * the Embedded Objects invariants and these could not be resolved automatically.
+     * @see RealmClass#embedded()
+     */
+    public void setEmbedded(boolean embedded, boolean resolveEmbeddedClassConstraints) {
         if (hasPrimaryKey()) {
             throw new IllegalStateException("Embedded classes cannot have primary keys. This class " +
                     "has a primary key defined so cannot be marked as embedded: " + getClassName());
         }
-        boolean setEmbedded = table.setEmbedded(embedded);
+        boolean setEmbedded = table.setEmbedded(embedded, resolveEmbeddedClassConstraints);
         if (!setEmbedded && embedded) {
             throw new IllegalStateException("The class could not be marked as embedded as some " +
                     "objects of this type break some of the Embedded Objects invariants. In order to convert " +

realm/realm-library/src/main/java/io/realm/internal/Table.java

@@ -793,7 +793,18 @@ public boolean isEmbedded() {
      * some invariant was broken when trying to change the state
      */
     public boolean setEmbedded(boolean embedded) {
-        return nativeSetEmbedded(nativeTableRefPtr, embedded);
+        return setEmbedded(embedded, false);
+    }
+
+    /**
+     * Returns true if the state was changed, false if not. If false was returned, it meant
+     * some invariant was broken when trying to change the state. The {@code handleBackLinks}
+     * parameter tells Core to automatically handle all unsatisfied invariants for backlinks, e.g.
+     * children becoming orphan or cloning objects with multiple references during migrations from
+     * a regular object to an embedded object.
+     */
+    public boolean setEmbedded(boolean embedded, boolean handleBackLinks) {
+        return nativeSetEmbedded(nativeTableRefPtr, embedded, handleBackLinks);
     }
 
     @Nullable
@@ -957,5 +968,5 @@ public static String getTableNameForClass(String name) {
 
     private static native boolean nativeIsEmbedded(long nativeTableRefPtr);
 
-    private static native boolean nativeSetEmbedded(long nativeTableRefPtr, boolean isEmbedded);
+    private static native boolean nativeSetEmbedded(long nativeTableRefPtr, boolean isEmbedded, boolean handleBackLinks);
 }