Realm Java 0.86 — with new Migration API!
We just released a new version of Realm Java to this website and to Maven. This release includes a replacement for the old Migration API, as well as a new Dynamic API to complement it.
Migration API
Migrations are still specified using a migration block in RealmConfiguration, but the interface has changed. Migrations now operate on a new Realm type called a DynamicRealm. DynamicRealm is a special variant of a conventional Realm that allows you to interact and change the schema while still having access to all of the ordinary object creation and query capabilities.
RealmMigration migration = new RealmMigration() {
@Override
public void migrate(DynamicRealm realm, long oldVersion, long newVersion) {
// DynamicRealm exposes an editable schema
RealmSchema schema = realm.getSchema();
if (oldVersion == 0) {
// Migrate to version 1
oldVersion++;
}
if (oldVersion == 1) {
// Migrate to version 2
oldVersion++;
}
}
}
// Configure the migration as normal
RealmConfiguration realmConfig = new RealmConfiguration.Builder(context)
.schemaVersion(2)
.migration(migration)
.build();
Classes and fields are now referenced using their names and can be created and modified in a fluent manner.
RealmSchema schema = realm.getSchema();
// Create Person class with two fields: name and age
schema.create("Person")
.addField("name", String.class)
.addField("age", int.class);
// Fields with special properties
schema.get("Person")
.addField("id", long.class, FieldAttribute.PRIMARY_KEY);
// References to other Realm objects
schema.get("Person")
.addRealmObjectField("favoriteDog", schema.get("Dog"))
.addRealmListField("dogs", schema.get("Dog"));
// Creating new data during migrations
DynamicRealmObject person = realm.createObject("Person");
person.setString("name", "John");
// Delete a class and all its data
schema.remove("Person");
It is also possible to run custom transformations on all RealmObjects of a specific type. This can be useful if converting between types, or merging or splitting fields.
schema.get("Person")
.transform(new RealmObjectSchema.Function() {
@Override
public void apply(DynamicRealmObject obj) {
obj.setInt("age", obj.getInt("age") + 1); // Add 1 to all ages
}
});
See RealmSchema and RealmObjectSchema for all options, and take a look at our updated migration example.
Dynamic API
Migrations make use of the new Dynamic API, but it is also available outside migrations. It can be useful in scenarios where you are working with data where the model is not known at compile time, like importing data from CSV files.
Dynamic Realms are opened using the same configuration you use for the conventional Realms, but they ignore any schema, migration, and schema version.
RealmConfiguration realmConfig = new RealmConfiguration.Builder(context).build();
DynamicRealm realm = DynamicRealm.getInstance(realmConfig);
// In a DynamicRealm all objects are DynamicRealmObjects
DynamicRealmObject person = realm.createObject("Person");
// All fields are accessed using strings
String name = person.getString("name");
int age = person.getInt("age");
// An underlying schema still exists, so accessing a field that does not exist will throw an exception
person.getString("I don't exist");
// Queries still work normally
RealmResults<DynamicRealmObject> persons = realm.where("Person").equalTo("name", "John").findAll();
A DynamicRealm trades type safety and performance for flexibility, so only use it in cases where you really need the flexibility.
#enumsmatter
We have updated our query API so it now uses enums instead of booleans when specifying Sort and Case options. This should provide a more readable and type-safe API.
realm.where(Person.class)
.beginsWith("name", "John", Case.INSENSITIVE)
.findAllSorted("name", Sort.ASCENDING)
See the full changelog for all the details.
Thanks for reading. Now go forth and build amazing apps with Realm! As always, we’re around on Stack Overflow, GitHub, and Twitter.
