New migration API

[cmelchior]

This depends on #1200

This PR adds the new Migration API. It introduces a breaking change as the Migration interface has changed. It also introduces 2 new classes: RealmSchema and RealmObjectSchema. The interface for those methods are below and should hopefully be mostly self explanatory (that was the whole point :) )

// New interface for writing migration blocks
public interface RealmMigration {
  void migrate(RealmSchema schema, long oldVersion, long newVersion);
}

// Public methods in RealmSchema
public interface RealmSchemaInterface {
    RealmObjectSchema getClass(String className);
    RealmObjectSchema addClass(String className);
    void removeClass(String className);
    RealmObjectSchema renameClass(String oldName, String newName);
}

// Public methods in RealmObjectSchema
public interface RealmObjectSchemaInterface {
    RealmObjectSchema addString(String fieldName);
    RealmObjectSchema addString(String fieldName, Set<RealmModifier> modifiers);
    RealmObjectSchema addShort(String fieldName);
    RealmObjectSchema addShort(String fieldName, Set<RealmModifier> modifiers);
    RealmObjectSchema addInt(String fieldName);
    RealmObjectSchema addInt(String fieldName, Set<RealmModifier> modifiers);
    RealmObjectSchema addLong(String fieldName);
    RealmObjectSchema addLong(String fieldName, Set<RealmModifier> modifiers);
    RealmObjectSchema addBoolean(String fieldName);
    RealmObjectSchema addBoolean(String fieldName, Set<RealmModifier> modifiers);
    RealmObjectSchema addByteArray(String fieldName);
    RealmObjectSchema addByteArray(String fieldName, Set<RealmModifier> modifiers);
    RealmObjectSchema addFloat(String fieldName);
    RealmObjectSchema addFloat(String fieldName, Set<RealmModifier> modifiers);
    RealmObjectSchema addDouble(String fieldName);
    RealmObjectSchema addDouble(String fieldName, Set<RealmModifier> modifiers);
    RealmObjectSchema addDate(String fieldName);
    RealmObjectSchema addDate(String fieldName, Set<RealmModifier> modifiers);
    RealmObjectSchema addObject(String fieldName, RealmObjectSchema objectSchema);
    RealmObjectSchema addList(String fieldName, RealmObjectSchema objectSchema);
    RealmObjectSchema removeField(String fieldName);
    RealmObjectSchema renameField(String currentFieldName, String newFieldName);
    RealmObjectSchema addIndex(String fieldName);
    RealmObjectSchema removeIndex(String fieldName);
    RealmObjectSchema addPrimaryKey(String fieldName);
    RealmObjectSchema setNonNullable(String fieldName); // Not supported yet
    RealmObjectSchema setNullable(String fieldName); // Not supported yet
    boolean hasPrimaryKey();
    boolean hasIndex(String fieldName);
    RealmObjectSchema removePrimaryKey();
    DynamicRealmObject createObject();
    DynamicRealmObject createObject(Object primaryKeyValue);
    DynamicRealmObject forEach(RealmSchemaObject.Iterator iterator);
}

// Example of usage
public class Migration implements RealmMigration {

    @Override
    public void migrate(RealmSchema schema, long oldVersion, long newVersion) {
        /*
            // Version 0
            class Person
                String fullName;
                String lastName;
                int    age;
            // Version 1
            class Person
                String fullName;        // combine firstName and lastName into single field
                int age;
        */
        if (oldVersion == 0) {
            schema.getClass("Person")
                    .addString("fullName")
                    .forEach(new RealmObjectSchema.Iterator() {
                        @Override
                        public void next(DynamicRealmObject obj) {
                            obj.setString("fullName", obj.getString("firstName") + " " + obj.getString("lastName"));
                        }
                    })
                    .removeField("firstName")
                    .removeField("lastName");
            oldVersion++;
        }

        /*
            // Version 2
            class Pet                   // add a new model class
                String name;
                String type;
            class Person
                String fullName;
                int age;
                RealmList<Pet> pets;    // add a RealmList field
        */
        if (oldVersion == 1) {

            final RealmObjectSchema petSchema = schema.addClass("Pet")
                    .addString("name")
                    .addString("type");

            schema.getClass("Person")
                    .addList("pets", petSchema)
                    .forEach(new RealmObjectSchema.Iterator() { // TODO Should we add query support now?
                        @Override
                        public void next(DynamicRealmObject obj) {
                            if (obj.getString("fullName").equals("JP McDonald")) {
                                DynamicRealmObject pet = petSchema.createObject();
                                pet.setString("name", "Jimbo");
                                pet.setString("type", "dog");
                                obj.getList("pets").add(pet);
                            }
                        }
                    });
            oldVersion++;
        }

        /*
            // Version 3
            class Pet
                @Index
                String name;            // name is indexed
                int type;               // type becomes int
            class Person
                String fullName;
                RealmList<Pet> pets;    // age and pets re-ordered
                int age;
        */
        if (oldVersion == 2) {
            schema.getClass("Pet")
                    .addIndex("name")
                    .addInt("typeTmp")
                    .forEach(new RealmObjectSchema.Iterator() {
                        @Override
                        public void next(DynamicRealmObject obj) {
                            String type = obj.getString("type");
                            if (type.equals("dog")) {
                                obj.setInt("typeTmp", 1);
                            } else if (type.equals("cat")) {
                                obj.setInt("typeTmp", 2);
                            } else if (type.equals("hamster")) {
                                obj.setInt("typeTmp", 3);
                            }
                        }
                    })
                    .removeField("type")
                    .renameField("typeTmp", "type");

            // TODO 4 instructions to change a type, is that acceptable? But the alternative would be an
            // API explosion or to expose something like a "RealmField" which would mean we would have to expose
            // the internal Realm types
            // schema.addField(new RealmField("type", ColumnType.INTEGER))
            oldVersion++;
        }
    }
}

Missing:

• JavaDoc
• Unit tests
• Feedback on missing methods for manipulating schema
• Feedback from Cocoa
• Add Null support
• Class iterator: forEach, Java8 stream/RxJava like

[cmelchior]

This is being superseded by a new PR against the Dynamic/Migration feature branch instead of against master.