Add support for embedded objects

[nirinchev]

Description

Adds support for embedded objects. Embedded objects are objects which are owned by a single parent object, and are deleted when that parent object is deleted or their parent no longer references them. Embedded objects are declared by subclassing EmbeddedObject instead of RealmObject. Reassigning an embedded object is not allowed and neither is linking to it from multiple parents. Querying for embedded objects directly is also disallowed as they should be viewed as complex structures belonging to their parents as opposed to standalone objects. A trivial example is:

public class Address : EmbeddedObject
{
    public string Street { get; set; }

    public string City { get; set; }
}

public class Person : RealmObject
{
    public string Name { get; set; }

    // Address is an embedded object - you reference it as usual
    public Address Address { get; set; }
}

public class Company : RealmObject
{
    public string PhoneNumber { get; set; }

    // Embedded objects can be contained in lists too
    public IList<Address> OfficeAddresses { get; }
}

Added new dynamic methods for instantiating embedded objects:

• Realm.DynamicApi.CreateEmbeddedObjectForProperty should be used to create an embedded object and assign it to a parent's property. For example:

  // static API
  var person = new Person();
  person.Address = new Address
  {
      City = "New York"
  };
  
  // dynamic API
  var dynamicPerson = realm.DynamicApi.CreateObject("Person");
  var address = realm.DynamicApi.CreateEmbeddedObjectForProperty(dynamicPerson, "Address")
  address.City = "New York";

• Realm.DynamicApi.AddEmbeddedObjectToList should be used to create an embedded object and add it to a parent's list property.

• Realm.DynamicApi.InsertEmbeddedObjectInList should be used to create an embedded object and insert it in a parent's list property at a specified index.

• Realm.DynamicApi.SetEmbeddedObjectInList should be used to create an embedded object and set it at an index in a parent's list property.

  // static API
  var company = new Company();
  company.OfficeAddresses.Add(new Address
  {
      City = "New York"
  });
  
  company.OfficeAddresses.Insert(0, new Address
  {
      City = "Palo Alto"
  });
  
  company.OfficeAddresses[1] = new Address
  {
      City = "New Jersey"
  };
  
  // dynamic API
  var dynamicCompany = realm.DynamicApi.CreateObject("Company");
  var officeToAdd = realm.DynamicApi.AddEmbeddedObjectToList(dynamicCompany.OfficeAddresses)  ;
  officeToAdd.City = "New York";
  
  var officeToInsert = realm.DynamicApi.InsertEmbeddedObjectInList(dynamicCompany.  OfficeAddresses, 0);
  officeToInsert.City = "Palo Alto";
  
  var officeToSet = realm.DynamicApi.SetEmbeddedObjectInList(dynamicCompany.  OfficeAddresses, 1);
  officeToSet.City = "New Jersey";

Fixes #1937

Breaking changes

This moves all the string-based/dynamic API from Realm to Realm.DynamicAPI. This is necessary because of the increased number of dynamic API which would unnecessarily pollute the interface for strongly typed access which is the primary use case.

TODO

• Changelog entry
• Test recursive objects
• Implement lists of embedded objects
• Test lists
• Test dynamic API
• Wire up EmbeddedObject.Parent (blocked on Expose a Obj::get_parent API realm-core#3898)
• Test backlinks
• Read embeddedness from object store schema

[nirinchev]

??

[nirinchev]

Suggested change

	return new Object(list.get_realm(), list.add_embedded());
	return new Object(list.get_realm(), list.get_object_schema(), list.add_embedded());

[nirinchev]

same

[dev-thinks]

@nirinchev The description over here is clearly explaining the usage of IList. I think this need to be transferred to the documentation as well. Thank you.